# joaopauloolt/library-api architecture

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

- Interactive diagram: https://gitdiagram.com/joaopauloolt/library-api
- Repository: https://github.com/joaopauloolt/library-api

## Overview

Library API is a Spring REST backend for catalog, physical copies, user identity and loan circulation. The main workflow runs from an API request through an application use case to domain repositories and PostgreSQL; loan operations enforce copy availability and update loan/copy state. Authentication issues and rotates JWT/refresh tokens, while security infrastructure handles token validation and RBAC. The README documents pagination, filtering and additional user/author capabilities; unsampled controllers and services are represented by their exact tree paths, but their internal calls are not inferred.

Main entry points: [`src/main/java/com/jpoltramari/library_api/application/service/LoanService.java`](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/LoanService.java) (Loan Circulation), [`src/main/java/com/jpoltramari/library_api/application/service/AuthService.java`](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/AuthService.java) (Authentication), [`src/main/java/com/jpoltramari/library_api/application/service/BookService.java`](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/BookService.java) (Book Catalog), [`src/main/java/com/jpoltramari/library_api/domain/repository/UserRepository.java`](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/UserRepository.java) (User Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_auth_api["Authentication API"]
  node_catalog_api["Catalog API"]
  node_author_api["Author API"]
  node_copy_api["Book Copy API"]
  node_loan_api["Loan API"]
  node_user_api["User API"]
end

subgraph group_application["Application Use Cases"]
  node_auth_usecase["Authentication<br/>[AuthService.java]"]
  node_catalog_usecase["Book Catalog<br/>[BookService.java]"]
  node_author_usecase["Author Management<br/>[AuthorService.java]"]
  node_copy_usecase["Copy Management"]
  node_circulation["Loan Circulation<br/>[LoanService.java]"]
  node_user_usecase["User Management<br/>[UserService.java]"]
  node_token_version["Token Versions"]
end

subgraph group_security["Security Infrastructure"]
  node_jwt["JWT Validation<br/>[JwtService.java]"]
  node_refresh["Refresh Tokens"]
  node_security_stack["Authentication and RBAC"]
end

subgraph group_domain["Domain and Persistence"]
  node_domain_models["Library Entities"]
  node_user_repo["User Repository"]
  node_loan_repo["Loan Repository"]
  node_book_repo["Book Repository"]
  node_copy_repo["Copy Repository"]
  node_author_repo["Author Repository"]
end

node_client(("API Client"))
node_postgres[("PostgreSQL")]

node_client -->|"requests"| node_auth_api
node_client -->|"requests"| node_catalog_api
node_client -->|"requests"| node_author_api
node_client -->|"requests"| node_copy_api
node_client -->|"requests"| node_loan_api
node_client -->|"requests"| node_user_api
node_auth_api -->|"delegates"| node_auth_usecase
node_catalog_api -->|"delegates"| node_catalog_usecase
node_author_api -->|"delegates"| node_author_usecase
node_copy_api -->|"delegates"| node_copy_usecase
node_loan_api -->|"delegates"| node_circulation
node_user_api -->|"delegates"| node_user_usecase
node_auth_usecase -->|"loads user"| node_user_repo
node_auth_usecase -->|"blacklists token"| node_jwt
node_auth_usecase -->|"issues or rotates"| node_refresh
node_catalog_usecase -->|"queries and saves"| node_book_repo
node_catalog_usecase -->|"loads authors"| node_author_repo
node_catalog_usecase -->|"creates copies"| node_copy_repo
node_author_usecase -->|"queries and saves"| node_author_repo
node_circulation -->|"loads borrower"| node_user_repo
node_circulation -->|"checks book"| node_book_repo
node_circulation -->|"selects and updates copy"| node_copy_repo
node_circulation -->|"checks and saves loans"| node_loan_repo
node_refresh -->|"loads user"| node_user_repo
node_refresh -->|"revokes sessions"| node_token_version
node_jwt -.->|"blacklist state"| node_postgres
node_loan_repo -->|"persists loans"| node_postgres
node_book_repo -->|"persists catalog"| node_postgres
node_copy_repo -->|"persists copies"| node_postgres
node_author_repo -->|"persists authors"| node_postgres
node_user_repo -->|"persists users"| node_postgres

click node_auth_api "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/AuthController.java"
click node_catalog_api "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/BookController.java"
click node_author_api "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/AuthorController.java"
click node_copy_api "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/BookCopyController.java"
click node_loan_api "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/LoanController.java"
click node_user_api "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/UserController.java"
click node_auth_usecase "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/AuthService.java"
click node_catalog_usecase "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/BookService.java"
click node_author_usecase "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/AuthorService.java"
click node_copy_usecase "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/BookCopyService.java"
click node_circulation "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/LoanService.java"
click node_user_usecase "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/UserService.java"
click node_token_version "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/TokenVersionService.java"
click node_jwt "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/infrastructure/security/JwtService.java"
click node_refresh "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/infrastructure/security/jwt/RefreshTokenService.java"
click node_security_stack "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/infrastructure/security/SecurityConfig.java"
click node_domain_models "https://github.com/joaopauloolt/library-api/tree/develop/src/main/java/com/jpoltramari/library_api/domain/model"
click node_user_repo "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/UserRepository.java"
click node_loan_repo "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/LoanRepository.java"
click node_book_repo "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/BookRepository.java"
click node_copy_repo "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/BookCopyRepository.java"
click node_author_repo "https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/AuthorRepository.java"

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_auth_api,node_catalog_api,node_author_api,node_copy_api,node_loan_api,node_user_api,node_client toneBlue
class node_auth_usecase,node_catalog_usecase,node_author_usecase,node_copy_usecase,node_circulation,node_user_usecase,node_token_version,node_postgres toneAmber
class node_jwt,node_refresh,node_security_stack toneMint
class node_domain_models,node_user_repo,node_loan_repo,node_book_repo,node_copy_repo,node_author_repo toneRose
```

## Components

### REST API

- [Authentication API](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/AuthController.java): `src/main/java/com/jpoltramari/library_api/api/controller/AuthController.java`
- [Catalog API](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/BookController.java): `src/main/java/com/jpoltramari/library_api/api/controller/BookController.java`
- [Author API](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/AuthorController.java): `src/main/java/com/jpoltramari/library_api/api/controller/AuthorController.java`
- [Book Copy API](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/BookCopyController.java): `src/main/java/com/jpoltramari/library_api/api/controller/BookCopyController.java`
- [Loan API](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/LoanController.java): `src/main/java/com/jpoltramari/library_api/api/controller/LoanController.java`
- [User API](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/api/controller/UserController.java): `src/main/java/com/jpoltramari/library_api/api/controller/UserController.java`

### Application Use Cases

- [Authentication](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/AuthService.java): `src/main/java/com/jpoltramari/library_api/application/service/AuthService.java`
- [Book Catalog](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/BookService.java): `src/main/java/com/jpoltramari/library_api/application/service/BookService.java`
- [Author Management](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/AuthorService.java): `src/main/java/com/jpoltramari/library_api/application/service/AuthorService.java`
- [Copy Management](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/BookCopyService.java): `src/main/java/com/jpoltramari/library_api/application/service/BookCopyService.java`
- [Loan Circulation](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/LoanService.java): `src/main/java/com/jpoltramari/library_api/application/service/LoanService.java`
- [User Management](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/UserService.java): `src/main/java/com/jpoltramari/library_api/application/service/UserService.java`
- [Token Versions](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/application/service/TokenVersionService.java): `src/main/java/com/jpoltramari/library_api/application/service/TokenVersionService.java`

### Security Infrastructure

- [JWT Validation](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/infrastructure/security/JwtService.java): `src/main/java/com/jpoltramari/library_api/infrastructure/security/JwtService.java`
- [Refresh Tokens](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/infrastructure/security/jwt/RefreshTokenService.java): `src/main/java/com/jpoltramari/library_api/infrastructure/security/jwt/RefreshTokenService.java`
- [Authentication and RBAC](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/infrastructure/security/SecurityConfig.java): `src/main/java/com/jpoltramari/library_api/infrastructure/security/SecurityConfig.java`

### Domain and Persistence

- [Library Entities](https://github.com/joaopauloolt/library-api/tree/develop/src/main/java/com/jpoltramari/library_api/domain/model): `src/main/java/com/jpoltramari/library_api/domain/model`
- [User Repository](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/UserRepository.java): `src/main/java/com/jpoltramari/library_api/domain/repository/UserRepository.java`
- [Loan Repository](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/LoanRepository.java): `src/main/java/com/jpoltramari/library_api/domain/repository/LoanRepository.java`
- [Book Repository](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/BookRepository.java): `src/main/java/com/jpoltramari/library_api/domain/repository/BookRepository.java`
- [Copy Repository](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/BookCopyRepository.java): `src/main/java/com/jpoltramari/library_api/domain/repository/BookCopyRepository.java`
- [Author Repository](https://github.com/joaopauloolt/library-api/blob/develop/src/main/java/com/jpoltramari/library_api/domain/repository/AuthorRepository.java): `src/main/java/com/jpoltramari/library_api/domain/repository/AuthorRepository.java`

### Other components

- **API Client**
- **PostgreSQL**

## Connections

- API Client → Authentication API: requests (evidence: `README.md`)
- API Client → Catalog API: requests (evidence: `README.md`)
- API Client → Author API: requests (evidence: `README.md`)
- API Client → Book Copy API: requests (evidence: `README.md`)
- API Client → Loan API: requests (evidence: `README.md`)
- API Client → User API: requests (evidence: `README.md`)
- Authentication API → Authentication: delegates (evidence: `README.md`)
- Catalog API → Book Catalog: delegates (evidence: `README.md`)
- Author API → Author Management: delegates (evidence: `README.md`)
- Book Copy API → Copy Management: delegates (evidence: `src/main/java/com/jpoltramari/library_api/api/controller/BookCopyController.java`)
- Loan API → Loan Circulation: delegates (evidence: `src/main/java/com/jpoltramari/library_api/api/controller/LoanController.java`)
- User API → User Management: delegates (evidence: `README.md`)
- Authentication → User Repository: loads user (evidence: `src/main/java/com/jpoltramari/library_api/application/service/AuthService.java`)
- Authentication → JWT Validation: blacklists token (evidence: `src/main/java/com/jpoltramari/library_api/application/service/AuthService.java`)
- Authentication → Refresh Tokens: issues or rotates (evidence: `src/main/java/com/jpoltramari/library_api/application/service/AuthService.java`)
- Book Catalog → Book Repository: queries and saves (evidence: `src/main/java/com/jpoltramari/library_api/application/service/BookService.java`)
- Book Catalog → Author Repository: loads authors (evidence: `src/main/java/com/jpoltramari/library_api/application/service/BookService.java`)
- Book Catalog → Copy Repository: creates copies (evidence: `src/main/java/com/jpoltramari/library_api/application/service/BookService.java`)
- Author Management → Author Repository: queries and saves (evidence: `src/main/java/com/jpoltramari/library_api/application/service/AuthorService.java`)
- Loan Circulation → User Repository: loads borrower (evidence: `src/main/java/com/jpoltramari/library_api/application/service/LoanService.java`)
- Loan Circulation → Book Repository: checks book (evidence: `src/main/java/com/jpoltramari/library_api/application/service/LoanService.java`)
- Loan Circulation → Copy Repository: selects and updates copy (evidence: `src/main/java/com/jpoltramari/library_api/application/service/LoanService.java`)
- Loan Circulation → Loan Repository: checks and saves loans (evidence: `src/main/java/com/jpoltramari/library_api/application/service/LoanService.java`)
- Refresh Tokens → User Repository: loads user (evidence: `src/main/java/com/jpoltramari/library_api/infrastructure/security/jwt/RefreshTokenService.java`)
- Refresh Tokens → Token Versions: revokes sessions (evidence: `src/main/java/com/jpoltramari/library_api/infrastructure/security/jwt/RefreshTokenService.java`)
- JWT Validation → PostgreSQL: blacklist state
- Loan Repository → PostgreSQL: persists loans (evidence: `README.md`)
- Book Repository → PostgreSQL: persists catalog (evidence: `README.md`)
- Copy Repository → PostgreSQL: persists copies (evidence: `README.md`)
- Author Repository → PostgreSQL: persists authors (evidence: `README.md`)
- User Repository → PostgreSQL: persists users (evidence: `README.md`)
