# joebui/fast-blogging architecture

> Architecture diagram of the GitHub repository joebui/fast-blogging, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joebui/fast-blogging
- Repository: https://github.com/joebui/fast-blogging

## Overview

##### Main Components
- API/Router Layer: Represented by the files under src/routers (e.g. articles_v1_router.py, auth_router.py). These endpoints handle incoming HTTP requests.
- Middleware: For example, the authentication middleware in src/middlewares/authentication.py that hooks into the request processing pipeline.
- Service Layer: Contains the business logic (located in src/services such as articles_v1_service.py and users_service.py). This layer processes requests and coordinates between the API and data access layers.
- Data Access/Repository Layer: In src/repositories (articles_repository.py, users_repository.py) which communicate with the database.
- Models: Defined in src/models, including the user and article models, plus a base class for shared functionality.
- Configurations/Utilities: The src/configs (database.py, environment.py, logger.py) provide critical configuration and utility functions. Also, custom types in src/custom_types help with standardizing requests and responses.
- Database and Migrations: The migrations folder contains the SQL scripts (V1__CreateUserTable.sql, V2__CreateArticleTable.sql) and shell scripts (migrate.sh) for schema setup. Additionally, docker-compose.yml and Dockerfile indicate that the service and the database (Postgres, as implied by the setup commands) run inside containers.
- Build/Deployment & Tasking: The presence of Taskfile.yml and Docker-related files, along with .env, configure the environment and provide task automation.

##### Establish the Relationships
- Client requests are received by the API (routers), pass through middleware (like authentication) then hit the service layer.
- The service layer calls the repository layer to perform CRUD operations, which in turn interact with the database.
- Configuration components (environment settings, logger, and database configurations) are loaded at startup and used across layers.
- The migration scripts are used to set up/update the database schema and support evolving the relational structure.

##### Architectural Patterns/Design Principles
- Layered Architecture: The separation between routers (presentation), services (business logic), repositories (data access), and models is clear.
- Dependency Injection & Separation of Concerns: Each layer is kept relatively independent (e.g., the routers do not directly access the database but instead work via services and repositories).
- Containerization: Docker-related files indicate that the service, along with its dependencies (like Postgres), is containerized for consistency and ease of deployment.

##### Relevant Technologies and Frameworks
- Python (likely using frameworks such as FastAPI or Flask based on the file structure, though the specific framework isn’t directly labeled in the file names).
- Postgres as the relational database (inferred from migration scripts and startup instructions).
- Docker and Docker Compose for container orchestration.
- Poetry for Python dependency management, and Task for running development/automation tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLIENT["Client (HTTP)"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        API["Routers (src/routers)"]:::api
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        MW["Authentication Middleware (src/middlewares)"]:::middleware
    end

    %% Service Layer
    subgraph "Service Layer"
        SERV["Services (src/services)"]:::service
    end

    %% Repository Layer
    subgraph "Repository Layer"
        REPO["Repositories (src/repositories)"]:::repository
    end

    %% Model Layer
    subgraph "Model Layer"
        MODEL["Models (src/models)"]:::model
    end

    %% Configuration & Utilities
    subgraph "Config & Utils"
        CONFIG["Configs (src/configs)"]:::config
        CT["Custom Types (src/custom_types)"]:::config
        CONST["Utils (src/utils/constants.py)"]:::config
    end

    %% Database and Migrations
    subgraph "Database & Migrations"
        DB["Postgres Database"]:::database
        MIG["Migrations (migrations)"]:::migration
    end

    %% Deployment & Build
    subgraph "Deployment & Build"
        DEPLOY["Deployment Files"]:::deployment
    end

    %% Data Flow Connections
    CLIENT -->|"HTTPRequest"| API
    API -->|"ProcessRequest"| MW
    MW -->|"Authenticate"| SERV
    SERV -->|"CallRepo"| REPO
    REPO -->|"CRUD"| DB

    %% Cross-layer Dependencies
    CONFIG -.-> API
    CONFIG -.-> MW
    CONFIG -.-> SERV
    CONFIG -.-> REPO

    CT -.-> API
    CT -.-> MW
    CT -.-> SERV
    CT -.-> REPO

    CONST -.-> CONFIG

    SERV -.-> MODEL
    REPO -.-> MODEL

    MIG -->|"SetupSchema"| DB

    DEPLOY -->|"Containerization"| DB
    DEPLOY --> API
    DEPLOY --> MW
    DEPLOY --> SERV
    DEPLOY --> REPO

    %% Click Events
    click API "https://github.com/joebui/fast-blogging/tree/main/src/routers"
    click MW "https://github.com/joebui/fast-blogging/blob/main/src/middlewares/authentication.py"
    click SERV "https://github.com/joebui/fast-blogging/tree/main/src/services"
    click REPO "https://github.com/joebui/fast-blogging/tree/main/src/repositories"
    click MODEL "https://github.com/joebui/fast-blogging/tree/main/src/models"
    click CONFIG "https://github.com/joebui/fast-blogging/tree/main/src/configs"
    click CT "https://github.com/joebui/fast-blogging/tree/main/src/custom_types"
    click CONST "https://github.com/joebui/fast-blogging/blob/main/src/utils/constants.py"
    click MIG "https://github.com/joebui/fast-blogging/tree/main/migrations"
    click DEPLOY "https://github.com/joebui/fast-blogging/tree/main/Dockerfile"

    %% Styling
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#6495ED,stroke:#000,stroke-width:2px;
    classDef middleware fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef repository fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef model fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef config fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef database fill:#FF6347,stroke:#000,stroke-width:2px;
    classDef migration fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef deployment fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
