# fernandatperez/booklibre architecture

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

- Interactive diagram: https://gitdiagram.com/fernandatperez/booklibre
- Repository: https://github.com/fernandatperez/booklibre

## Overview

BookLibre is a two-part platform for peer-to-peer book lending: readers and publishers browse a catalog, reserve books, manage profiles, and earn BiblioKarmas. The frontend SPA calls the Kotlin/Spring API; backend controllers delegate catalog, reservation, user, and authentication work to services and persistence. The README also documents a Redis-backed popular-home path, GraphQL/OpenLibrary metadata, and role-based security. Several of these implementations are unsampled, so their internal links are omitted or shown only where documented.

Main entry points: [`backend/src/main/kotlin/ar/edu/unsam/phm/repository/MongoBookRepository.kt`](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/repository/MongoBookRepository.kt) (Book repository), [`backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt`](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt) (Reservation lifecycle), [`backend/src/main/kotlin/ar/edu/unsam/phm/services/UserService.kt`](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/UserService.kt) (User profiles), [`backend/src/main/kotlin/ar/edu/unsam/phm/controller/BookController.kt`](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/BookController.kt) (Book endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["BookLibre SPA<br/>[main.tsx]"]
  node_routes["App routing<br/>[AppRouter.tsx]"]
  node_pages["Catalog and profiles"]
  node_clientapi["HTTP and GraphQL clients"]
end

subgraph group_api["API surface"]
  node_backend["Spring API"]
  node_bookapi["Book endpoints<br/>[BookController.kt]"]
  node_reserveapi["Reservation endpoints"]
  node_authapi["Authentication endpoints<br/>[AuthController.kt]"]
  node_usersapi["User endpoints<br/>[UserController.kt]"]
end

subgraph group_domain["Lending services"]
  node_catalog["Catalog and BiblioKarmas<br/>[BookService.kt]"]
  node_reservations["Reservation lifecycle"]
  node_userprofiles["User profiles<br/>[UserService.kt]"]
end

subgraph group_identity["Identity and access"]
  node_auth["Authentication and tokens"]
  node_security["JWT and role security"]
end

subgraph group_data["Persistence and analytics"]
  node_bookstore[("Book repository")]
  node_relational[("User and loan repositories")]
  node_popular["Popular-book ranking"]
  node_graphql["Catalog GraphQL"]
end

node_people(("Readers and publishers"))
node_openlibrary["OpenLibrary"]
node_redis[("Redis")]

node_people -->|"uses"| node_web
node_web -->|"loads"| node_routes
node_clientapi -->|"calls API"| node_backend
node_backend -.->|"serves routes"| node_bookapi
node_bookapi -->|"delegates"| node_catalog
node_bookapi -->|"routes home query"| node_popular
node_reserveapi -->|"delegates"| node_reservations
node_authapi -->|"delegates"| node_auth
node_usersapi -.->|"delegates"| node_userprofiles
node_auth -->|"loads user"| node_userprofiles
node_auth -->|"uses JWT config"| node_security
node_catalog -->|"queries books"| node_bookstore
node_reservations -->|"reads and writes"| node_relational
node_reservations -->|"updates book"| node_bookstore
node_reservations -->|"reads ratings"| node_relational
node_userprofiles -->|"reads and writes"| node_relational
node_userprofiles -->|"updates owned books"| node_bookstore
node_popular -.->|"reads ranking"| node_redis
node_popular -.->|"serves book data"| node_bookstore
node_graphql -.->|"stitches catalog data"| node_bookstore
node_graphql -.->|"loads metadata lazily"| node_openlibrary

click node_web "https://github.com/fernandatperez/booklibre/blob/main/frontend/src/main.tsx"
click node_routes "https://github.com/fernandatperez/booklibre/blob/main/frontend/src/router/AppRouter.tsx"
click node_pages "https://github.com/fernandatperez/booklibre/tree/main/frontend/src/pages"
click node_clientapi "https://github.com/fernandatperez/booklibre/tree/main/frontend/src/services"
click node_backend "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/ProjectApplication.kt"
click node_bookapi "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/BookController.kt"
click node_reserveapi "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/ReservationController.kt"
click node_authapi "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/auth/AuthController.kt"
click node_usersapi "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/UserController.kt"
click node_catalog "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/BookService.kt"
click node_reservations "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt"
click node_userprofiles "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/UserService.kt"
click node_auth "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/AuthenticationService.kt"
click node_security "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/config/SecurityConfiguration.kt"
click node_bookstore "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/repository/MongoBookRepository.kt"
click node_relational "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/repository/CrudReservationRepository.kt"
click node_popular "https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/PopularBooksService.kt"
click node_graphql "https://github.com/fernandatperez/booklibre/tree/main/backend/src/main/kotlin/ar/edu/unsam/phm/graphql"

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_web,node_routes,node_pages,node_clientapi toneBlue
class node_backend,node_bookapi,node_reserveapi,node_authapi,node_usersapi,node_redis toneAmber
class node_catalog,node_reservations,node_userprofiles toneMint
class node_auth,node_security toneRose
class node_bookstore,node_relational,node_popular,node_graphql,node_people,node_openlibrary toneIndigo
```

## Components

### Web client

- [BookLibre SPA](https://github.com/fernandatperez/booklibre/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [App routing](https://github.com/fernandatperez/booklibre/blob/main/frontend/src/router/AppRouter.tsx): `frontend/src/router/AppRouter.tsx`
- [Catalog and profiles](https://github.com/fernandatperez/booklibre/tree/main/frontend/src/pages): `frontend/src/pages`
- [HTTP and GraphQL clients](https://github.com/fernandatperez/booklibre/tree/main/frontend/src/services): `frontend/src/services`

### API surface

- [Spring API](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/ProjectApplication.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/ProjectApplication.kt`
- [Book endpoints](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/BookController.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/controller/BookController.kt`
- [Reservation endpoints](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/ReservationController.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/controller/ReservationController.kt`
- [Authentication endpoints](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/auth/AuthController.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/controller/auth/AuthController.kt`
- [User endpoints](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/controller/UserController.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/controller/UserController.kt`

### Lending services

- [Catalog and BiblioKarmas](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/BookService.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/services/BookService.kt`
- [Reservation lifecycle](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt`
- [User profiles](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/UserService.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/services/UserService.kt`

### Identity and access

- [Authentication and tokens](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/AuthenticationService.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/services/AuthenticationService.kt`
- [JWT and role security](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/config/SecurityConfiguration.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/config/SecurityConfiguration.kt`

### Persistence and analytics

- [Book repository](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/repository/MongoBookRepository.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/repository/MongoBookRepository.kt`
- [User and loan repositories](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/repository/CrudReservationRepository.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/repository/CrudReservationRepository.kt`
- [Popular-book ranking](https://github.com/fernandatperez/booklibre/blob/main/backend/src/main/kotlin/ar/edu/unsam/phm/services/PopularBooksService.kt): `backend/src/main/kotlin/ar/edu/unsam/phm/services/PopularBooksService.kt`
- [Catalog GraphQL](https://github.com/fernandatperez/booklibre/tree/main/backend/src/main/kotlin/ar/edu/unsam/phm/graphql): `backend/src/main/kotlin/ar/edu/unsam/phm/graphql`

### Other components

- **Readers and publishers**
- **OpenLibrary**
- **Redis**

## Connections

- Readers and publishers → BookLibre SPA: uses
- BookLibre SPA → App routing: loads
- HTTP and GraphQL clients → Spring API: calls API
- Spring API → Book endpoints: serves routes
- Book endpoints → Catalog and BiblioKarmas: delegates (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/controller/BookController.kt`)
- Book endpoints → Popular-book ranking: routes home query (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/controller/BookController.kt`)
- Reservation endpoints → Reservation lifecycle: delegates (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/controller/ReservationController.kt`)
- Authentication endpoints → Authentication and tokens: delegates (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/controller/auth/AuthController.kt`)
- User endpoints → User profiles: delegates
- Authentication and tokens → User profiles: loads user (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/AuthenticationService.kt`)
- Authentication and tokens → JWT and role security: uses JWT config (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/AuthenticationService.kt`)
- Catalog and BiblioKarmas → Book repository: queries books (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/BookService.kt`)
- Reservation lifecycle → User and loan repositories: reads and writes (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt`)
- Reservation lifecycle → Book repository: updates book (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt`)
- Reservation lifecycle → User and loan repositories: reads ratings (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/ReservationService.kt`)
- User profiles → User and loan repositories: reads and writes (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/UserService.kt`)
- User profiles → Book repository: updates owned books (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/services/UserService.kt`)
- Popular-book ranking → Redis: reads ranking
- Popular-book ranking → Book repository: serves book data
- Catalog GraphQL → Book repository: stitches catalog data (evidence: `backend/src/main/kotlin/ar/edu/unsam/phm/repository/MongoBookRepository.kt`)
- Catalog GraphQL → OpenLibrary: loads metadata lazily
