# abhimvp/bookly-fastapi architecture

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

- Interactive diagram: https://gitdiagram.com/abhimvp/bookly-fastapi
- Repository: https://github.com/abhimvp/bookly-fastapi

## Overview

##### Project Type and Purpose
- This is a backend RESTful API built with FastAPI (an ASGI framework) that manages books, users, reviews, and tags.
- It uses Pydantic/SQLModel for data validation and ORM, Alembic for migrations, Redis for JWT token revocation, and FastAPI-Mail/SMTP for email.

##### Main Architectural Components
- API Layer: FastAPI application, routers grouping endpoints by module (auth, books, reviews, tags).
- Business Logic Layer: “service” classes under each module (service.py) implementing CRUD and domain rules.
- Data Layer:
– PostgreSQL (via SQLModel + SQLAlchemy) for persistent storage.
– Alembic for schema migrations (“migrations/” directory and alembic.ini).
– Redis (aioredis) for token revocation/block lists.
- Infrastructure & Config:
– Dependency Injection via FastAPI’s Depends (dependencies.py).
– Configuration management (src/config.py, environment variables).
– Middleware (src/middleware.py) for cross-cutting concerns (logging, CORS, auth checks).
– Error handling (src/errors.py) with custom exception handlers.
- External Services:
– SMTP/email server via FastAPI-Mail (src/mail.py + email templates in src/templates).
– Optional WebSocket support (inherent via ASGI).

##### Relationships & Data Flow
1. Client (Postman/RESTfox) sends HTTP/HTTPS request.
2. Uvicorn (ASGI server) routes the request into the FastAPI app.
3. Request passes through Middleware (authentication, logging, CORS).
4. Router dispatch: Based on path prefix (e.g., /auth, /books), control flows to the correct module’s routes.py.
5. Route handler extracts/validates input via Pydantic schemas (schemas.py) and dependencies (e.g., DB session).
6. Route calls Service layer (service.py) to perform business logic, which:
a. Interacts with the database via SQLModel models (src/db/models.py) and session (src/db/main.py).
b. May push/revoke tokens in Redis.
c. May call FastAPI-Mail to send emails, signing tokens with ItsDangerous or PyJWT.
7. Service returns domain objects (Pydantic models) back to route, which serializes them to JSON.
8. FastAPI sends the HTTP response back to the client.

##### Architectural Patterns & Principles
- Layered Architecture: Clear separation of API (routers), Business (services), Data (repositories/ORM).
- Dependency Injection: FastAPI’s Depends to inject DB sessions, security checks, configs.
- Modularization: Each domain (auth, books, reviews, tags) lives in its own package.
- Async/Await End-to-End: ASGI-compatible stack, non-blocking DB calls (asyncpg), Redis calls (aioredis).
- Migrations as Code: Alembic environment configured to auto-generate and apply schema changes.
- Security: JWT Bearer tokens, role-based access control (RBAC), token revocation, password hashing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client to Server
    Client["Client (Postman/REST)"]:::external -->|"HTTP/HTTPS"| Uvicorn["Uvicorn (ASGI Server)"]:::infra
    Uvicorn -->|"routes to"| FastAPIApp["FastAPI Application"]:::api

    %% Middleware and DI
    FastAPIApp -->|"passes through"| Middleware["Middleware (CORS, Logging, Auth)"]:::infra
    click Middleware "https://github.com/abhimvp/bookly-fastapi/blob/main/src/middleware.py"
    Middleware -->|"error handling via"| ErrorHandlers["Custom Error Handlers"]:::infra
    click ErrorHandlers "https://github.com/abhimvp/bookly-fastapi/blob/main/src/errors.py"

    %% Routers (API Layer)
    subgraph "API Layer"
        AuthRouter["Auth Router"]:::api
        BooksRouter["Books Router"]:::api
        ReviewsRouter["Reviews Router"]:::api
        TagsRouter["Tags Router"]:::api
    end
    click AuthRouter "https://github.com/abhimvp/bookly-fastapi/blob/main/src/auth/routes.py"
    click BooksRouter "https://github.com/abhimvp/bookly-fastapi/blob/main/src/books/routes.py"
    click ReviewsRouter "https://github.com/abhimvp/bookly-fastapi/blob/main/src/reviews/routes.py"
    click TagsRouter "https://github.com/abhimvp/bookly-fastapi/blob/main/src/tags/routes.py"

    Middleware --> AuthRouter
    Middleware --> BooksRouter
    Middleware --> ReviewsRouter
    Middleware --> TagsRouter

    %% Business Logic Layer
    subgraph "Business Logic"
        AuthService["Auth Service"]:::service
        BookService["Book Service"]:::service
        ReviewService["Review Service"]:::service
        TagService["Tag Service"]:::service
    end
    click AuthService "https://github.com/abhimvp/bookly-fastapi/blob/main/src/auth/service.py"
    click BookService "https://github.com/abhimvp/bookly-fastapi/blob/main/src/books/service.py"
    click ReviewService "https://github.com/abhimvp/bookly-fastapi/blob/main/src/reviews/service.py"
    click TagService "https://github.com/abhimvp/bookly-fastapi/blob/main/src/tags/service.py"

    AuthRouter -->|"calls"| AuthService
    BooksRouter -->|"calls"| BookService
    ReviewsRouter -->|"calls"| ReviewService
    TagsRouter -->|"calls"| TagService

    %% Schemas and Utils
    AuthRouter --> AuthSchemas["Auth Schemas"]:::schema
    click AuthSchemas "https://github.com/abhimvp/bookly-fastapi/blob/main/src/auth/schemas.py"
    AuthService --> AuthUtils["Auth Utilities"]:::util
    click AuthUtils "https://github.com/abhimvp/bookly-fastapi/blob/main/src/auth/utils.py"
    AuthRouter --> AuthDeps["Auth Dependencies"]:::dep
    click AuthDeps "https://github.com/abhimvp/bookly-fastapi/blob/main/src/auth/dependencies.py"

    BooksRouter --> BookSchemas["Book Schemas"]:::schema
    click BookSchemas "https://github.com/abhimvp/bookly-fastapi/blob/main/src/books/schemas.py"
    BookService --> BookData["Book Data Helpers"]:::util
    click BookData "https://github.com/abhimvp/bookly-fastapi/blob/main/src/books/book_data.py"

    ReviewsRouter --> ReviewSchemas["Review Schemas"]:::schema
    click ReviewSchemas "https://github.com/abhimvp/bookly-fastapi/blob/main/src/reviews/schemas.py"

    TagsRouter --> TagSchemas["Tag Schemas"]:::schema
    click TagSchemas "https://github.com/abhimvp/bookly-fastapi/blob/main/src/tags/schemas.py"

    %% Data Layer
    subgraph "Data Layer"
        DBSession["Database Session Provider"]:::db
        ORMModels["ORM Models (SQLModel)"]:::orm
        RedisClient["Redis Blocklist Client"]:::redis
        AlembicCfg["Alembic Configuration"]:::alembic
        Migrations["Migration Scripts"]:::alembic
    end
    click DBSession "https://github.com/abhimvp/bookly-fastapi/blob/main/src/db/main.py"
    click ORMModels "https://github.com/abhimvp/bookly-fastapi/blob/main/src/db/models.py"
    click RedisClient "https://github.com/abhimvp/bookly-fastapi/blob/main/src/db/redis.py"
    click AlembicCfg "https://github.com/abhimvp/bookly-fastapi/blob/main/alembic.ini"
    click Migrations "https://github.com/abhimvp/bookly-fastapi/tree/main/migrations/"

    AuthService --> DBSession
    BookService --> DBSession
    ReviewService --> DBSession
    TagService --> DBSession

    AuthService --> ORMModels
    BookService --> ORMModels
    ReviewService --> ORMModels
    TagService --> ORMModels

    AuthService --> RedisClient

    AlembicCfg --> Migrations
    Migrations --> ORMModels

    %% Infrastructure & Config
    subgraph "Configuration"
        AppConfig["App Configuration"]:::config
    end
    click AppConfig "https://github.com/abhimvp/bookly-fastapi/blob/main/src/config.py"

    FastAPIApp --> AppConfig

    %% External Services
    subgraph "External Services"
        SMTP["SMTP Email Server"]:::external
        MailService["Email Service"]:::mail
        Templates["Email Templates"]:::template
    end
    click MailService "https://github.com/abhimvp/bookly-fastapi/blob/main/src/mail.py"
    click Templates "https://github.com/abhimvp/bookly-fastapi/tree/main/src/templates/"

    AuthService -->|"sends email via"| MailService
    MailService --> Templates
    MailService --> SMTP

    %% Directions back to client
    ReviewService -->|"returns data to"| ReviewsRouter
    BookService -->|"returns data to"| BooksRouter
    AuthService -->|"returns data to"| AuthRouter
    TagService -->|"returns data to"| TagsRouter
    CheapestReturn["Response JSON"]:::api
    AuthRouter --> CheapestReturn
    BooksRouter --> CheapestReturn
    ReviewsRouter --> CheapestReturn
    TagsRouter --> CheapestReturn
    CheapestReturn -->|"HTTP Response"| Client

    %% Styles
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef schema fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef util fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef dep fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#FFC0CB,stroke:#333,stroke-width:1px
    classDef infra fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef db fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef orm fill:#DCDCDC,stroke:#333,stroke-width:1px
    classDef redis fill:#A9A9A9,stroke:#333,stroke-width:1px
    classDef alembic fill:#F5DEB3,stroke:#333,stroke-width:1px
    classDef mail fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef template fill:#F5F5DC,stroke:#333,stroke-width:1px
    classDef external fill:#E0FFFF,stroke:#333,stroke-width:1px
```
