# adr1enbe4udou1n/fastapi-realworld-example-app architecture

> Architecture diagram of the GitHub repository adr1enbe4udou1n/fastapi-realworld-example-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adr1enbe4udou1n/fastapi-realworld-example-app
- Repository: https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app

## Overview

##### Project Type and Purpose
- This is a backend-focused, “RealWorld” reference implementation of a full-stack app spec.
- Built with FastAPI to expose a RESTful JSON API (CRUD, auth, pagination, etc.).
- Uses PostgreSQL (two containers: one for dev, one for integration testing), Alembic for migrations, and Docker Compose for local orchestration.

##### Main Architectural Layers and Components
A. External Clients & Tools
- Browsers or front-end apps consuming the API (RealWorld spec).
- CLI tools (Newman/Postman) for automated API validation.
- CI/CD workflow (Gitea Actions) for build & quality checks.
B. Application Server (FastAPI/Uvicorn)
- Entry point: app/main.py → Uvicorn
- API Layer: app/api/routes/* – endpoint definitions split by resource (articles, comments, users, etc.)
- Dependency Injection: app/api/deps.py – security, DB session provisioning
- Core Config & Security: app/core/config.py, app/core/security.py
C. Business Logic & Persistence
- CRUD Services: app/crud/* – encapsulate create/read/update/delete operations on models
- ORM Models (SQLAlchemy 2.0): app/models/* – table definitions & relationships
- DB Session Management: app/db/session.py + base_class.py
D. Database & Migrations
- PostgreSQL containers (dev & test) spun up via compose.yaml
- Alembic: alembic/env.py + alembic/versions/*.py – versioned schema migrations
E. Supporting & Orchestration
- Docker Compose: compose.yaml – service definitions for API and DBs
- Taskfile.yml & make scripts – shortcuts for migrations, seed, tests
- Seed Script: app/seed.py – injects fake data for dev/testing
- Tests: tests/api/**/* – pytest suite validating endpoints against the spec

##### Relationships & Data Flows
1. Client → HTTP request → Uvicorn/FastAPI
2. FastAPI dispatches to Router → applies Dependency (DB session, auth)
3. Router calls CRUD service → issues SQLAlchemy operations via session
4. Session → Postgres → returns data/models
5. CRUD returns model instance → converted to Pydantic schema → JSON response to client
6. Alembic/Taskfile/Seed scripts run externally for DB lifecycle management
7. CI (Gitea) → builds Docker image, runs tests, performs static analysis

##### Key Architectural Patterns & Principles
- Layered Architecture: clear separation of API, business logic (CRUD), models, and DB.
- Dependency Injection: FastAPI’s “Depends” for session & auth decoupling.
- Repository‐Style CRUD: isolates persistence logic from route handlers.
- Migrations as Code: version control for DB schema via Alembic.
- Containerization: each component (app, Postgres) runs in its own container.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients & Tools
    subgraph "External Clients & Tools"
        Browser["Client (Browser)"]:::external
        CLI["Postman/Newman"]:::external
        CI["Gitea CI/CD"]:::external
    end

    %% API Server Layer
    subgraph "API Server (FastAPI/Uvicorn)"
        Main["Uvicorn\n(app/main.py)"]:::api
        API["API Aggregator\n(app/api/api.py)"]:::api
        subgraph "API Layer"
            RoutesArticles["articles.py"]:::api
            RoutesComments["comments.py"]:::api
            RoutesFavorites["favorites.py"]:::api
            RoutesProfiles["profiles.py"]:::api
            RoutesTags["tags.py"]:::api
            RoutesAuth["auth.py"]:::api
            RoutesUser["user.py"]:::api
        end
        Deps["Dependency Injection\ndeps.py"]:::api
        Config["Configuration\nconfig.py"]:::api
        Security["Security\nsecurity.py"]:::api
    end

    %% Business Logic & Persistence
    subgraph "Business Logic & Persistence"
        subgraph "CRUD Services"
            CRUDArticle["crud_article.py"]:::logic
            CRUDComment["crud_comment.py"]:::logic
            CRUDUser["crud_user.py"]:::logic
        end
        subgraph "Schemas (Pydantic)"
            SchemaBase["base.py"]:::logic
            SchemaArticles["articles.py"]:::logic
            SchemaComments["comments.py"]:::logic
            SchemaProfiles["profiles.py"]:::logic
            SchemaTags["tags.py"]:::logic
            SchemaUsers["users.py"]:::logic
        end
        subgraph "ORM Models"
            ModelArticle["article.py"]:::logic
            ModelComment["comment.py"]:::logic
            ModelTag["tag.py"]:::logic
            ModelUser["user.py"]:::logic
        end
        Session["DB Session\nsession.py"]:::logic
        BaseClass["Declarative Base\nbase_class.py"]:::logic
    end

    %% Database & Migrations
    subgraph "Database & Migrations"
        PostgresDev[(PostgreSQL Dev)]:::db
        PostgresTest[(PostgreSQL Test)]:::db
        Alembic["Alembic\nenv.py + versions"]:::db
    end

    %% Supporting & Orchestration
    subgraph "Supporting & Orchestration"
        Compose["Docker Compose\ncompose.yaml"]:::orchestration
        DockerfileNode["Dockerfile"]:::orchestration
        Taskfile["Taskfile.yml"]:::orchestration
        Seed["Seed Script\napp/seed.py"]:::orchestration
        Tests["Pytest Suite\ntests/api"]:::orchestration
    end

    %% Data Flows
    Browser -->|HTTP Request| Main
    CLI -->|API Validation| API
    CI -->|Build & Test| DockerfileNode
    CI -->|Run Tests| Tests

    Main -->|Routes to| API
    API -->|Includes| RoutesArticles
    API -->|Includes| RoutesComments
    API -->|Includes| RoutesFavorites
    API -->|Includes| RoutesProfiles
    API -->|Includes| RoutesTags
    API -->|Includes| RoutesAuth
    API -->|Includes| RoutesUser
    RoutesArticles -->|Depends on| Deps
    RoutesComments -->|Depends on| Deps
    RoutesFavorites -->|Depends on| Deps
    RoutesProfiles -->|Depends on| Deps
    RoutesTags -->|Depends on| Deps
    RoutesAuth -->|Depends on| Deps
    RoutesUser -->|Depends on| Deps

    Deps -->|Creates| Session
    Deps -->|Uses| Security
    Deps -->|Uses| Config

    RoutesArticles -->|Calls| CRUDArticle
    RoutesComments -->|Calls| CRUDComment
    RoutesAuth -->|Calls| CRUDUser
    RoutesUser -->|Calls| CRUDUser

    CRUDArticle -->|Uses| Session
    CRUDComment -->|Uses| Session
    CRUDUser -->|Uses| Session

    CRUDArticle -->|Reads/Writes| ModelArticle
    CRUDComment -->|Reads/Writes| ModelComment
    CRUDUser -->|Reads/Writes| ModelUser

    ModelArticle -->|Validate/Serialize| SchemaArticles
    ModelComment -->|Validate/Serialize| SchemaComments
    ModelUser -->|Validate/Serialize| SchemaUsers

    Session -->|Executes SQL| PostgresDev
    Session -->|Executes SQL| PostgresTest

    Alembic -->|Migrates Schema| PostgresDev
    Alembic -->|Migrates Schema| PostgresTest
    Taskfile -->|Runs Migrations| Alembic
    Taskfile -->|Seeds Data| Seed
    Seed -->|Inserts Fake Data| PostgresDev

    Compose -->|Orchestrates| Main
    Compose -->|Orchestrates| PostgresDev
    Compose -->|Orchestrates| PostgresTest

    Tests -->|Exercises| Main

    %% Click Events
    click Main "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/main.py"
    click API "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/api.py"
    click RoutesArticles "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/routes/articles.py"
    click RoutesComments "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/routes/comments.py"
    click RoutesFavorites "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/routes/favorites.py"
    click RoutesProfiles "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/routes/profiles.py"
    click RoutesTags "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/routes/tags.py"
    click RoutesAuth "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/routes/auth.py"
    click RoutesUser "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/routes/user.py"
    click Deps "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/api/deps.py"
    click Config "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/core/config.py"
    click Security "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/core/security.py"
    click CRUDArticle "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/crud/crud_article.py"
    click CRUDComment "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/crud/crud_comment.py"
    click CRUDUser "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/crud/crud_user.py"
    click SchemaBase "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/schemas/base.py"
    click SchemaArticles "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/schemas/articles.py"
    click SchemaComments "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/schemas/comments.py"
    click SchemaProfiles "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/schemas/profiles.py"
    click SchemaTags "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/schemas/tags.py"
    click SchemaUsers "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/schemas/users.py"
    click ModelArticle "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/models/article.py"
    click ModelComment "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/models/comment.py"
    click ModelTag "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/models/tag.py"
    click ModelUser "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/models/user.py"
    click Session "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/db/session.py"
    click BaseClass "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/db/base_class.py"
    click Alembic "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/alembic/env.py"
    click Compose "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/compose.yaml"
    click DockerfileNode "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/tree/main/Dockerfile"
    click Taskfile "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/Taskfile.yml"
    click Seed "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/blob/main/app/seed.py"
    click Tests "https://github.com/adr1enbe4udou1n/fastapi-realworld-example-app/tree/main/tests/api"

    %% Styles
    classDef api fill:#E3F2FD,stroke:#1E88E5,stroke-width:1px
    classDef logic fill:#E8F5E9,stroke:#43A047,stroke-width:1px
    classDef db fill:#CFD8DC,stroke:#607D8B,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px
    classDef orchestration fill:#D7CCC8,stroke:#8D6E63,stroke-width:1px
```
