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.**

```bash
# 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.

```bash
# 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:**
```bash
# 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)

```bash
# 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