social-app/backend/AGENTS.md

Python Environment

MUST use uv for dependency management and virtual environment execution.

• All Python commands: uv run <command>
• Add dependencies: uv add <package>
• All dependencies declared in pyproject.toml

Process Entrypoints

Bootstrap Gate (REQUIRED)

The bootstrap gate is the ONLY allowed entry point for deployment.

# Using Makefile (recommended)
make runtime-bootstrap-gate

# Or directly using the script
bash infra/scripts/runtime-bootstrap-gate.sh

This gate:

1. Runs init-job bootstrap (migrate + init-data)
2. Starts web and worker services
3. Aborts if bootstrap fails (prevents web/worker startup)

Deployment without passing the bootstrap gate is PROHIBITED.

New Entrypoints (Phase 1-2, 2026-02-24)

Primary (recommended): Use Docker Compose orchestration.

# Bootstrap gate (required before web/worker)
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm init-job bootstrap

# Web
docker compose --env-file .env -f infra/docker/docker-compose.yml up -d web

# Worker (grouped)
docker compose --env-file .env -f infra/docker/docker-compose.yml up -d \
  worker-critical worker-default worker-bulk

One-shot jobs:

# Migrate only
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm init-job migrate

# Init data only
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm init-job init-data

# Full bootstrap (migrate + init-data)
docker compose --env-file .env -f infra/docker/docker-compose.yml run --rm init-job bootstrap

One-shot CLI (local development)

# Bootstrap (migrate + init-data)
PYTHONPATH=backend/src uv run python -m core.runtime.cli bootstrap

# Migrate only
PYTHONPATH=backend/src uv run python -m core.runtime.cli migrate

# Init data only
PYTHONPATH=backend/src uv run python -m core.runtime.cli init-data

Logging

MUST use project logger for all runtime logging.

• Use project logger from backend/src/core/logging/*
• Prohibit: print(), logging.info/warning/error directly
• Required: structured logging with context
• Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

HTTP API Standards

MUST follow RESTful conventions and RFC 7807 for error responses.

• Errors must use application/problem+json with RFC 7807 fields
• No custom response envelopes for HTTP APIs
• Request and response validation must use Pydantic models

Environment Variables

Backend env access MUST go through backend/src/core/config/settings.py.

• Only use Settings() / config from core.config.settings
• Do not call os.environ, os.getenv, dotenv, or manual parsing in backend runtime code
• Tests can set env vars via monkeypatch.setenv, and should read values via Settings() unless the test is explicitly validating env plumbing
• Canonical principle: one source of truth per setting; no duplicate/derived env vars in backend code

Code Quality Checks

Git pre-commit hook enforces code quality before commit.

Pre-commit hook automatically runs on backend/ directory:

• ruff check - code style and linting
• basedpyright - type checking with error level

If any error detected, commit is rejected. Fix errors before committing. Do not bypass or weaken checks (no ignores, disables, or config relaxations). Resolve the underlying issues.

TDD First Policy

Principle: tests before implementation.

Coverage Requirements

• Minimum coverage: 80%
• Required test types:
  • Unit: isolated functions, utilities, components
  • Integration: API endpoints, database operations
  • E2E: critical user flows (Playwright)

Limited Exceptions

• Docs-only changes (README, comments, formatting) may skip integration/E2E
• Non-runtime config changes may skip E2E if no behavior changes
• Any runtime code change requires unit + integration + E2E
• If an exception is used, record the reason in the PR/test notes

Mandatory TDD Workflow

1. Write tests (RED) - they must fail
2. Run tests - confirm failure
3. Implement minimal code (GREEN) - only to pass
4. Run tests - confirm success
5. Refactor (IMPROVE)
6. Verify coverage - must be 80%+

Enforcement

• Must use the tdd-guide agent for new features
• Do not write implementation before tests
• Do not lower coverage requirements
• Must include unit, integration, and E2E tests

Database Development Rules

Core Principle

• Supabase: authentication (JWT source of truth)
• Backend: business authorization (service layer)
• SQLAlchemy ORM: data access layer (async + asyncpg, service_role connection)

Architecture

Use schemas / repository / service pattern:

• schemas.py — Pydantic models
• repository.py — CRUD only, no auth, no commit (only flush), must receive session (never create session/engine)
• service.py — authorization + business logic + transaction boundary (must commit/rollback)
• dependencies.py — DI (get_db, get_current_user)

Auth & Data Access

• Backend must verify JWT signature and expiration (not just decode)
• Extract user_id from JWT sub claim
• Backend connects with service_role (bypasses RLS)
• owner_id always derived from JWT, never from client
• Scope queries by owner/org; public access must be explicit
• service_role key is backend-only; never expose credentials
• Prohibit calling Supabase Admin API (service_role key) from repository/service layers

Migrations

• Alembic is the single source of truth for schema migrations
• ORM model changes → alembic revision --autogenerate
• Raw SQL (policies, triggers, functions) → op.execute()
• Migrations must be reversible; no reliance on generated IDs

RLS Guidance

• Backend does not rely on RLS for correctness (uses service_role)
• Backend-only tables: RLS optional (skip to reduce maintenance)
• Client-direct tables: must enable RLS with policies covering select/insert/update/delete
• alembic_version must not be exposed to anonymous clients (revoke anon access)
• Business tables that may be exposed to clients should enable defensive RLS even if the backend does not depend on it