# mehdibennis/bookly architecture

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

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

## Overview

Bookly is a FastAPI books-and-authors API. Clients call versioned CRUD and pagination endpoints; routes validate and map DTOs, services apply domain rules, and repositories read or mutate PostgreSQL through the async unit of work. Paginated collections use Redis caching. Protected operations use Keycloak JWT authentication, while admin-user routes and system health endpoints are separate API branches. The tree and excerpts support these main boundaries; some route, dependency, and integration wiring is documented but not sampled, so uncertain call edges are omitted.

Main entry points: [`app/main.py`](https://github.com/mehdibennis/bookly/blob/main/app/main.py) (FastAPI App), [`app/api/v1/routes/books.py`](https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/books.py) (Book Routes), [`app/api/v1/routes/authors.py`](https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/authors.py) (Author Routes), [`app/services/book_service.py`](https://github.com/mehdibennis/bookly/blob/main/app/services/book_service.py) (Book Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["FastAPI App<br/>[main.py]"]
  node_book_routes["Book Routes<br/>[books.py]"]
  node_author_routes["Author Routes<br/>[authors.py]"]
  node_admin_routes["Admin User Routes<br/>[admin_users.py]"]
  node_system_routes["System Endpoints<br/>[system.py]"]
  node_schemas["Request Schemas"]
  node_mappers["API Mappers<br/>[mappers.py]"]
  node_dependencies["Service Dependencies<br/>[dependencies.py]"]
end

subgraph group_domain["Domain Services"]
  node_book_service["Book Service<br/>[book_service.py]"]
  node_author_service["Author Service<br/>[author_service.py]"]
  node_domain_model["Domain Contracts"]
end

subgraph group_data["Persistence"]
  node_book_repo["Book Repository<br/>[book_repository.py]"]
  node_author_repo["Author Repository"]
  node_uow["Unit of Work<br/>[unit_of_work.py]"]
  node_db_session["Async DB Session<br/>[session.py]"]
  node_orm_models["Book Author Models"]
  node_postgres[("PostgreSQL")]
end

subgraph group_platform["Platform Integrations"]
  node_cache["Redis Cache<br/>[cache_service.py]"]
  node_redis[("Redis")]
  node_keycloak_auth["JWT Authentication<br/>[keycloak_auth.py]"]
  node_keycloak_admin["Keycloak Admin<br/>[keycloak_admin.py]"]
  node_keycloak["Keycloak"]
  node_request_controls["Request Middleware<br/>[middleware.py]"]
  node_rate_limiter["Rate Limiter<br/>[limiter.py]"]
  node_errors["Error Handlers<br/>[error_handlers.py]"]
  node_observability["Logging &amp; Monitoring<br/>[observability.py]"]
end

node_client(("API Client"))

node_client -->|"sends HTTP"| node_app
node_app -->|"dispatches"| node_book_routes
node_app -->|"dispatches"| node_author_routes
node_app -->|"dispatches"| node_admin_routes
node_app -->|"dispatches"| node_system_routes
node_app -->|"installs middleware"| node_request_controls
node_app -->|"registers limits"| node_rate_limiter
node_app -->|"registers handlers"| node_errors
node_app -->|"configures monitoring"| node_observability
node_book_routes -->|"validates DTOs"| node_schemas
node_author_routes -->|"validates DTOs"| node_schemas
node_book_routes -->|"maps data"| node_mappers
node_author_routes -->|"maps data"| node_mappers
node_book_routes -->|"resolves services"| node_dependencies
node_author_routes -->|"resolves services"| node_dependencies
node_book_routes -->|"calls"| node_book_service
node_author_routes -->|"calls"| node_author_service
node_admin_routes -->|"authenticates"| node_keycloak_auth
node_book_routes -->|"authenticates protected calls"| node_keycloak_auth
node_author_routes -->|"authenticates protected calls"| node_keycloak_auth
node_admin_routes -->|"manages users"| node_keycloak_admin
node_keycloak_auth -->|"validates tokens"| node_keycloak
node_keycloak_admin -->|"admin requests"| node_keycloak
node_book_service -->|"reads and writes"| node_book_repo
node_author_service -->|"reads and writes"| node_author_repo
node_book_service -->|"runs transactions"| node_uow
node_author_service -->|"runs transactions"| node_uow
node_book_service -->|"gets and invalidates"| node_cache
node_author_service -->|"gets and sets"| node_cache
node_book_service -->|"uses contracts"| node_domain_model
node_author_service -->|"uses contracts"| node_domain_model
node_book_repo -->|"executes queries"| node_db_session
node_author_repo -->|"executes queries"| node_db_session
node_uow -->|"controls transaction"| node_db_session
node_db_session -->|"queries"| node_postgres
node_book_repo -->|"maps entities"| node_orm_models
node_author_repo -->|"maps entities"| node_orm_models
node_cache -->|"reads and writes pages"| node_redis

click node_app "https://github.com/mehdibennis/bookly/blob/main/app/main.py"
click node_book_routes "https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/books.py"
click node_author_routes "https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/authors.py"
click node_admin_routes "https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/admin_users.py"
click node_system_routes "https://github.com/mehdibennis/bookly/blob/main/app/api/system.py"
click node_schemas "https://github.com/mehdibennis/bookly/tree/main/app/schemas"
click node_mappers "https://github.com/mehdibennis/bookly/blob/main/app/api/mappers.py"
click node_dependencies "https://github.com/mehdibennis/bookly/blob/main/app/api/dependencies.py"
click node_book_service "https://github.com/mehdibennis/bookly/blob/main/app/services/book_service.py"
click node_author_service "https://github.com/mehdibennis/bookly/blob/main/app/services/author_service.py"
click node_domain_model "https://github.com/mehdibennis/bookly/tree/main/app/domain"
click node_book_repo "https://github.com/mehdibennis/bookly/blob/main/app/repositories/book_repository.py"
click node_author_repo "https://github.com/mehdibennis/bookly/blob/main/app/repositories/author_repository.py"
click node_uow "https://github.com/mehdibennis/bookly/blob/main/app/db/unit_of_work.py"
click node_db_session "https://github.com/mehdibennis/bookly/blob/main/app/db/session.py"
click node_orm_models "https://github.com/mehdibennis/bookly/tree/main/app/db/models"
click node_cache "https://github.com/mehdibennis/bookly/blob/main/app/core/cache_service.py"
click node_keycloak_auth "https://github.com/mehdibennis/bookly/blob/main/app/core/keycloak_auth.py"
click node_keycloak_admin "https://github.com/mehdibennis/bookly/blob/main/app/core/keycloak_admin.py"
click node_request_controls "https://github.com/mehdibennis/bookly/blob/main/app/core/middleware.py"
click node_rate_limiter "https://github.com/mehdibennis/bookly/blob/main/app/core/limiter.py"
click node_errors "https://github.com/mehdibennis/bookly/blob/main/app/core/error_handlers.py"
click node_observability "https://github.com/mehdibennis/bookly/blob/main/app/core/observability.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_app,node_book_routes,node_author_routes,node_admin_routes,node_system_routes,node_schemas,node_mappers,node_dependencies,node_client toneBlue
class node_book_service,node_author_service,node_domain_model toneAmber
class node_book_repo,node_author_repo,node_uow,node_db_session,node_orm_models,node_postgres toneMint
class node_cache,node_redis,node_keycloak_auth,node_keycloak_admin,node_keycloak,node_request_controls,node_rate_limiter,node_errors,node_observability toneRose
```

## Components

### HTTP API

- [FastAPI App](https://github.com/mehdibennis/bookly/blob/main/app/main.py): `app/main.py`
- [Book Routes](https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/books.py): `app/api/v1/routes/books.py`
- [Author Routes](https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/authors.py): `app/api/v1/routes/authors.py`
- [Admin User Routes](https://github.com/mehdibennis/bookly/blob/main/app/api/v1/routes/admin_users.py): `app/api/v1/routes/admin_users.py`
- [System Endpoints](https://github.com/mehdibennis/bookly/blob/main/app/api/system.py): `app/api/system.py`
- [Request Schemas](https://github.com/mehdibennis/bookly/tree/main/app/schemas): `app/schemas`
- [API Mappers](https://github.com/mehdibennis/bookly/blob/main/app/api/mappers.py): `app/api/mappers.py`
- [Service Dependencies](https://github.com/mehdibennis/bookly/blob/main/app/api/dependencies.py): `app/api/dependencies.py`

### Domain Services

- [Book Service](https://github.com/mehdibennis/bookly/blob/main/app/services/book_service.py): `app/services/book_service.py`
- [Author Service](https://github.com/mehdibennis/bookly/blob/main/app/services/author_service.py): `app/services/author_service.py`
- [Domain Contracts](https://github.com/mehdibennis/bookly/tree/main/app/domain): `app/domain`

### Persistence

- [Book Repository](https://github.com/mehdibennis/bookly/blob/main/app/repositories/book_repository.py): `app/repositories/book_repository.py`
- [Author Repository](https://github.com/mehdibennis/bookly/blob/main/app/repositories/author_repository.py): `app/repositories/author_repository.py`
- [Unit of Work](https://github.com/mehdibennis/bookly/blob/main/app/db/unit_of_work.py): `app/db/unit_of_work.py`
- [Async DB Session](https://github.com/mehdibennis/bookly/blob/main/app/db/session.py): `app/db/session.py`
- [Book Author Models](https://github.com/mehdibennis/bookly/tree/main/app/db/models): `app/db/models`
- **PostgreSQL**

### Platform Integrations

- [Redis Cache](https://github.com/mehdibennis/bookly/blob/main/app/core/cache_service.py): `app/core/cache_service.py`
- **Redis**
- [JWT Authentication](https://github.com/mehdibennis/bookly/blob/main/app/core/keycloak_auth.py): `app/core/keycloak_auth.py`
- [Keycloak Admin](https://github.com/mehdibennis/bookly/blob/main/app/core/keycloak_admin.py): `app/core/keycloak_admin.py`
- **Keycloak**
- [Request Middleware](https://github.com/mehdibennis/bookly/blob/main/app/core/middleware.py): `app/core/middleware.py`
- [Rate Limiter](https://github.com/mehdibennis/bookly/blob/main/app/core/limiter.py): `app/core/limiter.py`
- [Error Handlers](https://github.com/mehdibennis/bookly/blob/main/app/core/error_handlers.py): `app/core/error_handlers.py`
- [Logging & Monitoring](https://github.com/mehdibennis/bookly/blob/main/app/core/observability.py): `app/core/observability.py`

### Other components

- **API Client**

## Connections

- API Client → FastAPI App: sends HTTP
- FastAPI App → Book Routes: dispatches
- FastAPI App → Author Routes: dispatches
- FastAPI App → Admin User Routes: dispatches
- FastAPI App → System Endpoints: dispatches
- FastAPI App → Request Middleware: installs middleware
- FastAPI App → Rate Limiter: registers limits
- FastAPI App → Error Handlers: registers handlers
- FastAPI App → Logging & Monitoring: configures monitoring
- Book Routes → Request Schemas: validates DTOs
- Author Routes → Request Schemas: validates DTOs
- Book Routes → API Mappers: maps data
- Author Routes → API Mappers: maps data
- Book Routes → Service Dependencies: resolves services
- Author Routes → Service Dependencies: resolves services
- Book Routes → Book Service: calls
- Author Routes → Author Service: calls
- Admin User Routes → JWT Authentication: authenticates
- Book Routes → JWT Authentication: authenticates protected calls
- Author Routes → JWT Authentication: authenticates protected calls
- Admin User Routes → Keycloak Admin: manages users
- JWT Authentication → Keycloak: validates tokens
- Keycloak Admin → Keycloak: admin requests
- Book Service → Book Repository: reads and writes
- Author Service → Author Repository: reads and writes
- Book Service → Unit of Work: runs transactions
- Author Service → Unit of Work: runs transactions
- Book Service → Redis Cache: gets and invalidates
- Author Service → Redis Cache: gets and sets
- Book Service → Domain Contracts: uses contracts
- Author Service → Domain Contracts: uses contracts
- Book Repository → Async DB Session: executes queries
- Author Repository → Async DB Session: executes queries
- Unit of Work → Async DB Session: controls transaction
- Async DB Session → PostgreSQL: queries
- Book Repository → Book Author Models: maps entities
- Author Repository → Book Author Models: maps entities
- Redis Cache → Redis: reads and writes pages