Circlo

Circlo is an original, small-community social network MVP built with Django. All branding (name, logo, copy) is original Circlo — no third-party social network branding, logos, text or assets are used.

This repository currently contains package 1 of the MVP: accounts and profiles. Everything else in the spec is still planned (see below).

Status

Implemented (package 1)

• Original Circlo branding in base templates.
• Django 5.x server-rendered architecture (DjangoTemplates, no client-side framework; vanilla JS only where necessary).
• Registration, login and logout.
• User profile page (display name, biography, optional avatar) with a public detail view and an owner-only edit view.
• One Profile per User, created lazily via a post_save signal.
• Avatar upload validation: allowed MIME types are image/png, image/jpeg, image/webp, image/gif; maximum size 2 MiB; filenames are not trusted (Django stores under the avatars/ upload path).
• Focused tests under circlo/accounts/tests/.

Planned (not yet implemented)

• Text posts with optional image; post deletion by owner.
• Feed of own posts and accepted friends' posts.
• Likes (exactly once) and comments (add/delete own).
• Friend requests, accept/reject, friend list.
• Basic user search.
• Deterministic seed/demo management command with synthetic users and content.

These features do not exist in this tree; do not assume they work.

Tech stack

• Python 3.11+
• Django 5.2.1, Pillow 11.2.1 (pinned in requirements.txt)
• SQLite (local preview database)
• Uploaded media stored locally outside Git

Local setup

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver 0.0.0.0:8020

Commands

• python manage.py migrate — apply migrations (and makemigrations to create new ones).
• python manage.py runserver — dev server (playground target is port 8020).
• python manage.py test — run the test suite.
• python manage.py check — Django system checks.
• python manage.py makemigrations --check --dry-run — migration drift check.
• git diff --check — whitespace/conflict-marker hygiene.

Environment overrides

All optional; local defaults keep the preview working out of the box.

Variable	Default
DJANGO_SECRET_KEY	dev-only fallback (must be set outside local dev)
DJANGO_DEBUG	true (local dev); accepts true/false, 1/0, yes/no, on/off
DJANGO_ALLOWED_HOSTS	localhost,127.0.0.1,[::1] (comma-separated)
DJANGO_DB_PATH	<repo>/db.sqlite3
DJANGO_MEDIA_ROOT	<repo>/media
DJANGO_STATIC_ROOT	<repo>/staticfiles

Security basics

• CSRF protection (Django CsrfViewMiddleware) is on by default.
• @login_required guards profile editing; public profile reads are allowed.
• Ownership checks prevent editing another user's profile.
• The committed SECRET_KEY fallback is development-only; override via DJANGO_SECRET_KEY in any real deployment.
• No third-party trackers, CDNs, analytics, OAuth or remote APIs are included.

Local data

• db.sqlite3 and media/ are local artifacts and ignored by Git (see .gitignore). Do not commit databases or uploaded media.

Environment

• Target playground: port 8020 (port 8010 is reserved for an unrelated service and must never be used).
• Source of truth: the Forgejo repository (git remote origin).
• No deployment has been performed; the project is local-preview only.

Spec

See SPEC.md for the full MVP acceptance specification and AGENTS.md for engineering contracts and safety rules.