# say-boop/booknest architecture

> Architecture diagram of the GitHub repository say-boop/booknest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/say-boop/booknest
- Repository: https://github.com/say-boop/booknest

## Overview

BookNest is a FastAPI REST API for managing each user’s personal book library. Users register or log in to obtain a JWT; authenticated users can manage, search, filter, sort, import, export, and view statistics for their own books. The internal flow separates HTTP routing, service logic, and database repositories. Redis caches per-user statistics, while Celery handles scheduled reminders. The graph reflects shown calls and README-documented capabilities; unsampled scheduling and broker wiring are documented rather than inferred from source.

Main entry points: [`app/features/books/tasks.py`](https://github.com/say-boop/booknest/blob/main/app/features/books/tasks.py) (Book reminders), [`app/features/users/service.py`](https://github.com/say-boop/booknest/blob/main/app/features/users/service.py) (User service), [`app/features/books/router.py`](https://github.com/say-boop/booknest/blob/main/app/features/books/router.py) (Book routes), [`app/core/dependencies.py`](https://github.com/say-boop/booknest/blob/main/app/core/dependencies.py) (JWT auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_user_routes["User routes<br/>[router.py]"]
  node_user_service["User service<br/>[service.py]"]
  node_auth["JWT auth<br/>[dependencies.py]"]
  node_jwt["JWT tokens<br/>[generate_jwt.py]"]
  node_passwords["Password hashing<br/>[security.py]"]
  node_user_model["User model<br/>[models.py]"]
end

subgraph group_books["Book library"]
  node_book_routes["Book routes<br/>[router.py]"]
  node_book_service["Book service<br/>[service.py]"]
  node_book_repository["Book repository<br/>[repository.py]"]
  node_book_model["Book model<br/>[models.py]"]
end

subgraph group_storage["Persistence and cache"]
  node_user_repository["User repository<br/>[repository.py]"]
  node_database["DB session<br/>[database.py]"]
  node_postgres[("PostgreSQL")]
  node_redis_client["Redis client<br/>[redis_client.py]"]
  node_redis[("Redis cache")]
end

subgraph group_background["Background work"]
  node_celery_app["Celery app<br/>[celery_app.py]"]
  node_book_tasks["Book reminders<br/>[tasks.py]"]
  node_rabbitmq["RabbitMQ broker"]
end

node_reader(("Reader"))
node_app_log["Application log"]

node_reader -->|"uses API"| node_fastapi
node_fastapi -->|"registers routes"| node_user_routes
node_fastapi -->|"registers routes"| node_book_routes
node_user_routes -->|"calls"| node_user_service
node_user_service -->|"calls"| node_user_repository
node_user_service -->|"hashes passwords"| node_passwords
node_user_service -->|"creates token"| node_jwt
node_user_routes -->|"requires identity"| node_auth
node_book_routes -->|"requires identity"| node_auth
node_auth -->|"verifies token"| node_jwt
node_auth -->|"loads user"| node_user_repository
node_book_routes -->|"calls"| node_book_service
node_book_service -->|"calls"| node_book_repository
node_book_service -->|"invalidates stats"| node_redis_client
node_book_routes -->|"obtains client"| node_redis_client
node_book_repository -->|"queries and writes"| node_book_model
node_user_repository -->|"queries and writes"| node_user_model
node_book_repository -->|"uses session"| node_database
node_user_repository -->|"uses session"| node_database
node_database -.->|"connects to"| node_postgres
node_redis_client -.->|"connects to"| node_redis
node_celery_app -.->|"uses broker"| node_rabbitmq
node_book_tasks -->|"registers task"| node_celery_app
node_book_tasks -->|"reads books"| node_database
node_book_tasks -->|"checks status"| node_book_model
node_book_tasks -->|"logs reminder"| node_app_log

click node_fastapi "https://github.com/say-boop/booknest/blob/main/app/main.py"
click node_user_routes "https://github.com/say-boop/booknest/blob/main/app/features/users/router.py"
click node_user_service "https://github.com/say-boop/booknest/blob/main/app/features/users/service.py"
click node_user_repository "https://github.com/say-boop/booknest/blob/main/app/features/users/repository.py"
click node_auth "https://github.com/say-boop/booknest/blob/main/app/core/dependencies.py"
click node_jwt "https://github.com/say-boop/booknest/blob/main/app/core/generate_jwt.py"
click node_passwords "https://github.com/say-boop/booknest/blob/main/app/core/security.py"
click node_book_routes "https://github.com/say-boop/booknest/blob/main/app/features/books/router.py"
click node_book_service "https://github.com/say-boop/booknest/blob/main/app/features/books/service.py"
click node_book_repository "https://github.com/say-boop/booknest/blob/main/app/features/books/repository.py"
click node_book_model "https://github.com/say-boop/booknest/blob/main/app/features/books/models.py"
click node_user_model "https://github.com/say-boop/booknest/blob/main/app/features/users/models.py"
click node_database "https://github.com/say-boop/booknest/blob/main/app/core/database.py"
click node_redis_client "https://github.com/say-boop/booknest/blob/main/app/core/redis_client.py"
click node_celery_app "https://github.com/say-boop/booknest/blob/main/app/core/celery_app.py"
click node_book_tasks "https://github.com/say-boop/booknest/blob/main/app/features/books/tasks.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fastapi,node_user_routes,node_user_service,node_auth,node_jwt,node_passwords,node_user_model toneBlue
class node_book_routes,node_book_service,node_book_repository,node_book_model toneAmber
class node_user_repository,node_database,node_postgres,node_redis_client,node_redis toneMint
class node_celery_app,node_book_tasks,node_rabbitmq toneRose
class node_reader,node_app_log toneIndigo
```

## Components

### API and identity

- [FastAPI app](https://github.com/say-boop/booknest/blob/main/app/main.py): `app/main.py`
- [User routes](https://github.com/say-boop/booknest/blob/main/app/features/users/router.py): `app/features/users/router.py`
- [User service](https://github.com/say-boop/booknest/blob/main/app/features/users/service.py): `app/features/users/service.py`
- [JWT auth](https://github.com/say-boop/booknest/blob/main/app/core/dependencies.py): `app/core/dependencies.py`
- [JWT tokens](https://github.com/say-boop/booknest/blob/main/app/core/generate_jwt.py): `app/core/generate_jwt.py`
- [Password hashing](https://github.com/say-boop/booknest/blob/main/app/core/security.py): `app/core/security.py`
- [User model](https://github.com/say-boop/booknest/blob/main/app/features/users/models.py): `app/features/users/models.py`

### Book library

- [Book routes](https://github.com/say-boop/booknest/blob/main/app/features/books/router.py): `app/features/books/router.py`
- [Book service](https://github.com/say-boop/booknest/blob/main/app/features/books/service.py): `app/features/books/service.py`
- [Book repository](https://github.com/say-boop/booknest/blob/main/app/features/books/repository.py): `app/features/books/repository.py`
- [Book model](https://github.com/say-boop/booknest/blob/main/app/features/books/models.py): `app/features/books/models.py`

### Persistence and cache

- [User repository](https://github.com/say-boop/booknest/blob/main/app/features/users/repository.py): `app/features/users/repository.py`
- [DB session](https://github.com/say-boop/booknest/blob/main/app/core/database.py): `app/core/database.py`
- **PostgreSQL**
- [Redis client](https://github.com/say-boop/booknest/blob/main/app/core/redis_client.py): `app/core/redis_client.py`
- **Redis cache**

### Background work

- [Celery app](https://github.com/say-boop/booknest/blob/main/app/core/celery_app.py): `app/core/celery_app.py`
- [Book reminders](https://github.com/say-boop/booknest/blob/main/app/features/books/tasks.py): `app/features/books/tasks.py`
- **RabbitMQ broker**

### Other components

- **Reader**
- **Application log**

## Connections

- Reader → FastAPI app: uses API (evidence: `README.md`)
- FastAPI app → User routes: registers routes (evidence: `app/main.py`)
- FastAPI app → Book routes: registers routes (evidence: `app/main.py`)
- User routes → User service: calls (evidence: `app/features/users/router.py`)
- User service → User repository: calls (evidence: `app/features/users/service.py`)
- User service → Password hashing: hashes passwords (evidence: `app/features/users/service.py`)
- User service → JWT tokens: creates token (evidence: `app/features/users/service.py`)
- User routes → JWT auth: requires identity (evidence: `app/features/users/router.py`)
- Book routes → JWT auth: requires identity (evidence: `app/features/books/router.py`)
- JWT auth → JWT tokens: verifies token (evidence: `app/core/dependencies.py`)
- JWT auth → User repository: loads user (evidence: `app/core/dependencies.py`)
- Book routes → Book service: calls (evidence: `app/features/books/router.py`)
- Book service → Book repository: calls (evidence: `app/features/books/service.py`)
- Book service → Redis client: invalidates stats (evidence: `app/features/books/service.py`)
- Book routes → Redis client: obtains client (evidence: `app/features/books/router.py`)
- Book repository → Book model: queries and writes (evidence: `app/features/books/repository.py`)
- User repository → User model: queries and writes (evidence: `app/features/users/repository.py`)
- Book repository → DB session: uses session (evidence: `app/features/books/repository.py`)
- User repository → DB session: uses session (evidence: `app/features/users/repository.py`)
- DB session → PostgreSQL: connects to (evidence: `app/core/database.py`)
- Redis client → Redis cache: connects to (evidence: `README.md`)
- Celery app → RabbitMQ broker: uses broker (evidence: `README.md`)
- Book reminders → Celery app: registers task (evidence: `app/features/books/tasks.py`)
- Book reminders → DB session: reads books (evidence: `app/features/books/tasks.py`)
- Book reminders → Book model: checks status (evidence: `app/features/books/tasks.py`)
- Book reminders → Application log: logs reminder (evidence: `README.md`)
