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

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