9. Architecture Decisions¶

ADR-001: FastAPI as the Web Framework¶

Status: Accepted
Context: The backend must expose REST APIs with automatic OpenAPI documentation and support high-concurrency I/O without blocking threads.
Decision: Use FastAPI for all three bounded context services.
Rationale: FastAPI is async-first, generates OpenAPI 3.x specs automatically via Pydantic models, and has strong community adoption in the Python ecosystem.
Consequences: All route handlers must be async def; blocking calls (e.g. file I/O) must be offloaded with run_in_executor.

ADR-002: One PostgreSQL Schema per Bounded Context¶

Status: Accepted
Context: Three bounded contexts need persistent storage. Sharing tables would couple contexts at the database level.
Decision: Use a single PostgreSQL instance with separate schemas: users, posts, messaging.
Rationale: Schema-level isolation enforces context boundaries without the operational overhead of running three separate database servers. Cross-context queries are forbidden; data is fetched via API calls.
Consequences: Each service connects with a role that has access only to its own schema. Cross-context joins are not possible by design.

ADR-003: JWT RS256 for Authentication¶

Status: Accepted
Context: Multiple services need to verify user identity without coupling to the Users Service on every request.
Decision: Issue RS256-signed JWTs from the Users Service; all other services validate tokens locally using the public key.
Rationale: Asymmetric signing allows any service to verify tokens without access to the private key or a network call, keeping services loosely coupled.
Consequences: The RS256 public key must be distributed to all services (via environment variable). Key rotation requires a coordinated redeployment.

ADR-004: Fan-out on Read for Timeline Feed¶

Status: Accepted
Context: A user’s timeline aggregates posts from all followees. Two strategies exist: fan-out on write (pre-compute per follower) and fan-out on read (query at request time).
Decision: Use fan-out on read: query the posts of all followees at request time, paginated and sorted by created_at.
Rationale: At the current scale (≤10 000 concurrent users) fan-out on read is simpler to implement and avoids write amplification for users with many followers. Can be revisited if read latency becomes a bottleneck.
Consequences: Feed query performance depends on the number of followees. An index on (author_id, created_at DESC) in the posts table is required.

ADR-005: Modular Monorepo over Microservices¶

Status: Accepted
Context: Three bounded contexts could be deployed as fully independent microservices or co-located in a monorepo.
Decision: Single Git repository; three independently deployable FastAPI processes.
Rationale: Monorepo simplifies cross-context refactoring, shared tooling (linting, CI), and onboarding while still allowing independent scaling and deployment of each service.
Consequences: Shared libraries (e.g. JWT validation, error models) live in a common/ package within the repo. Changes to common/ affect all services and require coordinated releases.