How nsidnev/fastapi-realworld-example-app works
1. What this repo is
- A FastAPI backend implementing the RealWorld/Conduit API.
- The system is centered on a REST API backed by PostgreSQL, with JWT-based authentication and separate layers for routing, business logic, and database access.
2. Request entrypoint and application bootstrap
- app/main.py is the application entrypoint.
- app/core holds startup/config concerns: environment-based settings, logging, and app-level event hooks.
- Runtime configuration is split by environment (development, production, test) under app/core/settings.
3. HTTP/API boundary
- app/api/routes defines the public REST surface: articles, comments, profiles, tags, users, authentication, plus an API aggregator.
- These route modules are the thin outer boundary: they translate HTTP requests into service calls and return schema objects.
- app/api/errors centralizes HTTP and validation error handling so the API presents consistent responses.
4. Dependency injection layer
- app/api/dependencies contains request-scoped wiring for routes.
- This layer likely resolves the database handle, authenticated user context, and resource-specific helpers.
- It acts as the bridge between FastAPI request handling and the internal service/repository layers.
5. Business logic layer
- app/services contains non-trivial application behavior: article workflows, comments, authentication, JWT handling, and security helpers.
- This is where cross-cutting rules live, such as credential validation, token creation/verification, and orchestrating multi-step operations.
- Services sit between HTTP concerns and persistence concerns.
6. Persistence and data access
- app/db/repositories is the CRUD boundary for PostgreSQL access.
- Repositories isolate the rest of the app from raw SQL and database details.
- app/db/queries/sql stores SQL statements by domain area, while app/db/queries provides the query abstraction used by repositories.
- app/db/migrations contains Alembic migrations, showing that schema evolution is managed explicitly rather than inferred at runtime.
7. Domain vs API schema models
- app/models/domain contains internal domain models used across service and persistence logic.
- app/models/schemas contains request/response schemas for the API layer.
- The separation is important: domain objects are for internal business use, while schemas define the external contract.
- Shared base types in rwmodel.py and rwschema.py likely provide consistent read/write behavior across entities.
8. Supporting resources and constants
- app/resources/strings.py centralizes user-facing strings and response text.
- This suggests the project keeps message text out of route handlers and services to reduce duplication and improve consistency.
9. Authentication and authorization flow
- Authentication is split across services/authentication.py, services/jwt.py, and services/security.py.
- The flow is: credentials come in through auth routes, are validated in service logic, JWTs are created/checked, and protected endpoints use dependency-based user resolution.
- Profiles and user-related routes depend on this authenticated identity context.
10. Data flow through the system
- Typical request path: HTTP route -> dependency resolution -> service orchestration -> repository/query execution -> PostgreSQL -> domain/schema serialization -> HTTP response.
- Errors can be raised at any layer, but API error handlers normalize them before they leave the application boundary.
11. Testing and quality gates
- tests/ covers API routes, database query behavior, schemas, and JWT service logic.
- tests/fake_asyncpg_pool.py indicates the database layer is tested with a fake async pool, so persistence behavior can be validated without always hitting a live database.
- GitHub workflows and scripts for tests, linting, formatting, and deployment indicate CI enforces correctness and style.
12. Deployment/runtime packaging
- The repo is container-ready via Dockerfile and docker-compose.yml.
- PostgreSQL is a required external service, and the README shows local and Docker-based startup around DATABASE_URL, Alembic migrations, and Uvicorn.
- Postman collection files support API-level verification against the running service.
Main entry points: api.py API router · dependencies Deps · queries.py Queries · authentication.py Auth svc
Components 34
App runtime
FastAPI application layers and runtime bootstrapping.
- Main app · Application entrypoint and startup wiring.
app/main.py - Core config · Environment settings, logging, and app event hooks.
app/core - Env settings · Development, production, and test configuration variants.
app/core/settings - API router · Top-level REST surface composition.
app/api/routes/api.py - Articles API · Article endpoints and article resource flow.
app/api/routes/articles - Auth API · Authentication, login, and registration endpoints.
app/api/routes/authentication.py - Comments API · Comment endpoints.
app/api/routes/comments.py - Profiles API · Profile and follow endpoints.
app/api/routes/profiles.py - Tags API · Tag listing endpoints.
app/api/routes/tags.py - Users API · User account endpoints.
app/api/routes/users.py - API errors · HTTP and validation error normalization.
app/api/errors - Deps · Request-scoped dependency injection for routes.
app/api/dependencies - Articles svc · Article workflows and orchestration.
app/services/articles.py - Comments svc · Comment workflows and orchestration.
app/services/comments.py - Auth svc · Credential validation and authentication orchestration.
app/services/authentication.py - JWT svc · JWT creation and verification.
app/services/jwt.py - Security · Password and auth security helpers.
app/services/security.py - Strings · Centralized user-facing messages and response text.
app/resources/strings.py
Data layer
PostgreSQL access, queries, and migrations.
- Articles repo · Article persistence boundary.
app/db/repositories/articles.py - Comments repo · Comment persistence boundary.
app/db/repositories/comments.py - Profiles repo · Profile persistence and lookup.
app/db/repositories/profiles.py - Tags repo · Tag persistence and lookup.
app/db/repositories/tags.py - Users repo · User persistence boundary.
app/db/repositories/users.py - Queries · Database query abstraction used by repositories.
app/db/queries/queries.py - SQL files · Domain SQL grouped by area.
app/db/queries/sql - Migrations · Explicit database schema evolution.
app/db/migrations
Models
Internal domain objects and external API schemas.
- Domain models · Business-domain objects shared by services and persistence.
app/models/domain - API schemas · External contract for requests and responses.
app/models/schemas
Tests
Representative test coverage for API, DB, schemas, and services.
- API tests · Route and error handling coverage.
tests/test_api - DB tests · Query and table behavior coverage.
tests/test_db - Schema tests · Domain and schema model validation coverage.
tests/test_schemas - Service tests · JWT service behavior coverage.
tests/test_services
Ops
Container, workflow, and API tooling around the app.
- Container · Docker and compose packaging for local/runtime deployment.
Dockerfile - CI workflows · GitHub Actions for tests, linting, styles, and deploy.
.github/workflows
Connections 48
- Main app → Core config: bootstraps · Main application loads core startup behavior.
- Core config → Env settings: selects · Core config chooses environment-specific settings.
- Main app → API router: mounts · Application exposes the aggregated API router.
- API router → Articles API: includes · API surface includes article routes.
- API router → Auth API: includes · API surface includes auth routes.
- API router → Comments API: includes · API surface includes comment routes.
- API router → Profiles API: includes · API surface includes profile routes.
- API router → Tags API: includes · API surface includes tag routes.
- API router → Users API: includes · API surface includes user routes.
- Articles API → Deps: uses · Routes resolve request-scoped dependencies.
- Auth API → Deps: uses · Routes resolve request-scoped dependencies.
- Comments API → Deps: uses · Routes resolve request-scoped dependencies.
- Profiles API → Deps: uses · Routes resolve request-scoped dependencies.
- Users API → Deps: uses · Routes resolve request-scoped dependencies.
- Deps → Articles svc: wires · Dependencies connect routes to article logic.
- Deps → Comments svc: wires · Dependencies connect routes to comment logic.
- Deps → Auth svc: wires · Dependencies connect routes to auth logic.
- Deps → Users repo: wires · Dependencies provide database-backed user access.
- API errors → API router: guards · API error handling normalizes route failures.
- Auth svc → Security: calls · Authentication uses security helpers.
- Auth svc → JWT svc: issues · Authentication creates and validates JWTs.
- Auth svc → Users repo: reads/writes · Auth logic verifies and updates user records.
- Articles svc → Articles repo: uses · Article workflows persist through article repository.
- Articles svc → Tags repo: uses · Article workflows depend on tags data.
- Comments svc → Comments repo: uses · Comment workflows persist through comment repository.
- Profiles API → Profiles repo: reads · Profile routes resolve profile data.
- Tags API → Tags repo: reads · Tag routes resolve tag data.
- Users API → Auth svc: authenticates · User routes depend on authentication context.
- Articles repo → Queries: executes · Repositories execute through the query abstraction.
- Comments repo → Queries: executes · Repositories execute through the query abstraction.
- Profiles repo → Queries: executes · Repositories execute through the query abstraction.
- Tags repo → Queries: executes · Repositories execute through the query abstraction.
- Users repo → Queries: executes · Repositories execute through the query abstraction.
- Queries → SQL files: loads · Query layer is backed by domain SQL files.
- Queries → Migrations: aligns with · Queries operate against the migrated schema.
- Articles svc → Domain models: uses · Services manipulate internal domain objects.
- Comments svc → Domain models: uses · Services manipulate internal domain objects.
- Articles repo → Domain models: returns · Repositories map database records into domain objects.
- Comments repo → Domain models: returns · Repositories map database records into domain objects.
- API router → API schemas: serializes · Routes expose API schemas to clients.
- Auth API → API schemas: serializes · Auth routes use request/response schemas.
- Strings → API errors: messages · Shared text supports consistent error responses.
- API tests → API router: covers · API tests exercise route behavior.
- API tests → API errors: covers · API tests exercise error handling.
- DB tests → Queries: covers · DB tests verify query behavior.
- DB tests → Migrations: covers · DB tests verify schema expectations.
- Schema tests → Domain models: covers · Schema tests validate shared model behavior.
- Service tests → JWT svc: covers · Service tests exercise JWT logic.