# asmaanaiim/library architecture

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

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

## Overview

1. This is a Spring Boot REST backend for a library management system. The repository is organized around a standard layered architecture: HTTP controllers at the edge, a single business service layer, Spring Data repositories for persistence, and JPA-style model classes for domain state.

2. The main runtime entrypoint is `LibraryApplication`. Maven is the build tool, with the Maven wrapper checked in, so the project is intended to run consistently across environments. Configuration lives in `src/main/resources/application.properties`; the README indicates a MySQL-backed database.

3. The domain model is centered on four core persisted concepts: `Book`, `Patron`, `BorrowingRecord`, and `User`. There are also request/response DTOs for authentication and error handling: `LoginReq`, `LoginRes`, and `ErrorRes`.

4. There are two HTTP controller boundaries:
   - `AuthController` handles login and token issuance.
   - `LibraryController` appears to expose the library CRUD and workflow endpoints for books, patrons, and borrowing/returning.
   This means clients talk only to controllers; they do not access repositories or security internals directly.

5. Business logic is concentrated in `LibraryService`, which likely coordinates validation, book inventory rules, patron lifecycle, and borrowing/returning rules. The tests show this service is responsible for stateful workflows such as creating, reading, updating, deleting, and enforcing availability constraints during borrowing.

6. Persistence is split across four repositories:
   - `BookRepository`
   - `PatronRepository`
   - `BorrowingRecordRepository`
   - `UserRepository`
   These are the database access boundary for the app, and they are used by the service layer rather than by controllers.

7. Security is JWT-based. `JwtAuthorizationFilter` is the request-time gatekeeper that checks the `Authorization: Bearer ...` header. `JwtUtil` handles token creation/validation, and `CustomUserDetailsService` bridges application users to Spring Security authentication. `SecurityConfig` wires the authentication and authorization rules.

8. The authentication flow is: client posts credentials to `/rest/auth/login`, `AuthController` verifies them through the security/user-details pipeline, and a JWT is returned in `LoginRes`. All later requests pass through the JWT filter before reaching the controllers.

9. Cross-cutting logging is implemented with AOP. `LoggingAspect` and `AopConfig` indicate method-level interception for logging actions, exceptions, or execution details. This is a separate concern from the core business flow and applies across layers rather than inside one controller or service.

10. Error handling is likely standardized through `ErrorRes`, which suggests API failures are returned in a consistent response shape. The README and tests indicate validation errors are important, especially for `Book` and `Patron` input constraints.

11. The main application flow for library operations is:
   client request -> security filter -> controller -> service -> repository -> database -> service/controller response.
   Borrowing is an important transactional boundary because it must coordinate book availability, patron eligibility, and record creation/removal consistently.

12. The test suite is focused on API and service behavior rather than low-level persistence:
   - controller validation and endpoint behavior for books and patrons
   - service-level CRUD behavior
   - normal borrowing/return scenarios
   - edge-case borrowing when copies are exhausted
   This confirms the system’s critical architecture concern is correct business rule enforcement under REST access.

13. For an architecture diagram, the key subsystems to show are: external client, auth/security layer, library REST layer, business service, persistence repositories, database, and the AOP logging cross-cutting path. The most important data boundary is JWT-protected HTTP traffic into the library API, and the most important business boundary is inventory/borrowing consistency in `LibraryService`.

Main entry points: [`src/main/java/com/spring/library/service/LibraryService.java`](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/service/LibraryService.java) (Library Service), [`src/main/java/com/spring/library/config/SecurityConfig.java`](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/config/SecurityConfig.java) (Security Config), [`src/main/java/com/spring/library/controller/AuthController.java`](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/controller/AuthController.java) (Auth Controller), [`src/main/java/com/spring/library/components/LoggingAspect.java`](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/components/LoggingAspect.java) (Logging Aspect)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & Run"]
  node_library_application(("LibraryApp<br/>spring boot entrypoint"))
  node_application_properties["App Config<br/>runtime config"]
end

subgraph group_security["Security"]
  node_security_config["Security Config"]
  node_jwt_filter["JWT Filter<br/>request filter"]
  node_jwt_util["JWT Util<br/>token helper<br/>[JwtUtil.java]"]
  node_user_details_service["User Details<br/>auth bridge"]
end

subgraph group_api["HTTP API"]
  node_auth_controller["Auth Controller<br/>auth endpoint"]
  node_library_controller["Library Controller<br/>rest controller"]
end

subgraph group_core["Core Logic"]
  node_library_service["Library Service<br/>business service"]
  node_logging_aspect{{"Logging Aspect<br/>aop concern<br/>[LoggingAspect.java]"}}
  node_aop_config["AOP Config<br/>[AopConfig.java]"]
end

subgraph group_data["Data Layer"]
  node_book_repo["Book Repo"]
  node_patron_repo["Patron Repo"]
  node_record_repo["Record Repo"]
  node_user_repo["User Repo"]
  node_book_model["Book<br/>domain entity<br/>[Book.java]"]
  node_patron_model["Patron<br/>domain entity<br/>[Patron.java]"]
  node_record_model["Borrowing Record<br/>domain entity"]
  node_user_model["User<br/>domain entity<br/>[User.java]"]
  node_login_req["Login Req<br/>dto<br/>[LoginReq.java]"]
  node_login_res["Login Res<br/>dto<br/>[LoginRes.java]"]
  node_error_res["Error Res<br/>dto<br/>[ErrorRes.java]"]
end

node_library_application -->|"starts with"| node_security_config
node_library_application -->|"starts with"| node_aop_config
node_library_application -->|"reads config"| node_application_properties
node_security_config -->|"registers"| node_jwt_filter
node_security_config -->|"uses"| node_user_details_service
node_security_config -->|"uses"| node_jwt_util
node_jwt_filter -->|"validates with"| node_jwt_util
node_auth_controller -->|"accepts"| node_login_req
node_auth_controller -->|"returns"| node_login_res
node_auth_controller -->|"authenticates via"| node_user_details_service
node_library_controller -->|"delegates to"| node_library_service
node_library_controller -->|"formats errors"| node_error_res
node_library_service -->|"uses"| node_book_repo
node_library_service -->|"uses"| node_patron_repo
node_library_service -->|"uses"| node_record_repo
node_library_service -->|"uses"| node_user_repo
node_library_service -->|"manages"| node_book_model
node_library_service -->|"manages"| node_patron_model
node_library_service -->|"creates"| node_record_model
node_user_details_service -->|"loads from"| node_user_repo
node_logging_aspect -.->|"advises"| node_library_controller
node_logging_aspect -.->|"advises"| node_library_service
node_logging_aspect -.->|"advises"| node_auth_controller
node_aop_config -->|"enables"| node_logging_aspect

click node_library_application "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/LibraryApplication.java"
click node_application_properties "https://github.com/asmaanaiim/library/blob/main/src/main/resources/application.properties"
click node_security_config "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/config/SecurityConfig.java"
click node_jwt_filter "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/auth/JwtAuthorizationFilter.java"
click node_jwt_util "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/auth/JwtUtil.java"
click node_user_details_service "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/service/CustomUserDetailsService.java"
click node_auth_controller "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/controller/AuthController.java"
click node_library_controller "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/controller/LibraryController.java"
click node_library_service "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/service/LibraryService.java"
click node_logging_aspect "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/components/LoggingAspect.java"
click node_aop_config "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/config/AopConfig.java"
click node_book_repo "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/BookRepository.java"
click node_patron_repo "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/PatronRepository.java"
click node_record_repo "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/BorrowingRecordRepository.java"
click node_user_repo "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/UserRepository.java"
click node_book_model "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/Book.java"
click node_patron_model "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/Patron.java"
click node_record_model "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/BorrowingRecord.java"
click node_user_model "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/User.java"
click node_login_req "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/LoginReq.java"
click node_login_res "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/LoginRes.java"
click node_error_res "https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/ErrorRes.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_library_application,node_application_properties toneBlue
class node_security_config,node_jwt_filter,node_jwt_util,node_user_details_service toneAmber
class node_auth_controller,node_library_controller toneMint
class node_library_service,node_logging_aspect,node_aop_config toneRose
class node_book_repo,node_patron_repo,node_record_repo,node_user_repo,node_book_model,node_patron_model,node_record_model,node_user_model,node_login_req,node_login_res,node_error_res toneIndigo
```

## Components

### Build & Run

Maven-based application bootstrap and runtime configuration.

- [LibraryApp](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/LibraryApplication.java): spring boot entrypoint · Main application bootstrap for the Spring Boot runtime. · `src/main/java/com/spring/library/LibraryApplication.java`
- [App Config](https://github.com/asmaanaiim/library/blob/main/src/main/resources/application.properties): runtime config · Application properties including database/runtime settings. · `src/main/resources/application.properties`

### Security

JWT authentication, authorization, and Spring Security wiring.

- [Security Config](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/config/SecurityConfig.java): spring security config · Configures authentication, authorization, and filter chain behavior. · `src/main/java/com/spring/library/config/SecurityConfig.java`
- [JWT Filter](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/auth/JwtAuthorizationFilter.java): request filter · Intercepts requests and validates Bearer tokens. · `src/main/java/com/spring/library/auth/JwtAuthorizationFilter.java`
- [JWT Util](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/auth/JwtUtil.java): token helper · Creates and validates JWT tokens. · `src/main/java/com/spring/library/auth/JwtUtil.java`
- [User Details](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/service/CustomUserDetailsService.java): auth bridge · Adapts application users to Spring Security authentication. · `src/main/java/com/spring/library/service/CustomUserDetailsService.java`

### HTTP API

REST controllers exposed to clients.

- [Auth Controller](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/controller/AuthController.java): auth endpoint · Handles login and token issuance. · `src/main/java/com/spring/library/controller/AuthController.java`
- [Library Controller](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/controller/LibraryController.java): rest controller · Exposes library CRUD and borrowing workflows. · `src/main/java/com/spring/library/controller/LibraryController.java`

### Core Logic

Business service and cross-cutting aspects.

- [Library Service](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/service/LibraryService.java): business service · Coordinates validation, CRUD, inventory, and borrowing rules. · `src/main/java/com/spring/library/service/LibraryService.java`
- [Logging Aspect](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/components/LoggingAspect.java): aop concern · Cross-cutting interception for logging and exceptions. · `src/main/java/com/spring/library/components/LoggingAspect.java`
- [AOP Config](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/config/AopConfig.java): aop config · Enables and wires aspect-oriented logging support. · `src/main/java/com/spring/library/config/AopConfig.java`

### Data Layer

Domain models, repositories, and database configuration.

- [Book Repo](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/BookRepository.java): repository · Persistence boundary for books. · `src/main/java/com/spring/library/repository/BookRepository.java`
- [Patron Repo](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/PatronRepository.java): repository · Persistence boundary for patrons. · `src/main/java/com/spring/library/repository/PatronRepository.java`
- [Record Repo](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/BorrowingRecordRepository.java): repository · Persistence boundary for borrowing records. · `src/main/java/com/spring/library/repository/BorrowingRecordRepository.java`
- [User Repo](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/repository/UserRepository.java): repository · Persistence boundary for authenticated users. · `src/main/java/com/spring/library/repository/UserRepository.java`
- [Book](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/Book.java): domain entity · Persisted book state and inventory fields. · `src/main/java/com/spring/library/model/Book.java`
- [Patron](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/Patron.java): domain entity · Persisted patron state and lifecycle data. · `src/main/java/com/spring/library/model/Patron.java`
- [Borrowing Record](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/BorrowingRecord.java): domain entity · Tracks loans and returns for books and patrons. · `src/main/java/com/spring/library/model/BorrowingRecord.java`
- [User](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/User.java): domain entity · Authenticated application user record. · `src/main/java/com/spring/library/model/User.java`
- [Login Req](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/LoginReq.java): dto · Credentials request payload for authentication. · `src/main/java/com/spring/library/model/LoginReq.java`
- [Login Res](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/LoginRes.java): dto · JWT-bearing login response payload. · `src/main/java/com/spring/library/model/LoginRes.java`
- [Error Res](https://github.com/asmaanaiim/library/blob/main/src/main/java/com/spring/library/model/ErrorRes.java): dto · Standardized API error response shape. · `src/main/java/com/spring/library/model/ErrorRes.java`

## Connections

- LibraryApp → Security Config: starts with · Bootstraps the application context including security setup.
- LibraryApp → AOP Config: starts with · Loads aspect-oriented configuration at startup.
- LibraryApp → App Config: reads config · Uses externalized runtime and database settings.
- Security Config → JWT Filter: registers · Adds the JWT request filter into the security chain.
- Security Config → User Details: uses · Delegates authentication lookup to the user-details bridge.
- Security Config → JWT Util: uses · Relies on token utility for JWT operations.
- JWT Filter → JWT Util: validates with · Checks incoming bearer tokens against JWT rules.
- Auth Controller → Login Req: accepts · Consumes login credentials from clients.
- Auth Controller → Login Res: returns · Responds with issued token and auth result.
- Auth Controller → User Details: authenticates via · Verifies credentials through the security user pipeline.
- Library Controller → Library Service: delegates to · Routes library operations into business logic.
- Library Controller → Error Res: formats errors · Uses a standard error response shape for failures.
- Library Service → Book Repo: uses · Reads and writes book records.
- Library Service → Patron Repo: uses · Reads and writes patron records.
- Library Service → Record Repo: uses · Manages borrowing record persistence.
- Library Service → User Repo: uses · Looks up users for authentication-related workflows.
- Library Service → Book: manages · Applies inventory and book lifecycle rules.
- Library Service → Patron: manages · Applies patron lifecycle and validation rules.
- Library Service → Borrowing Record: creates · Creates and updates borrowing transactions.
- User Details → User Repo: loads from · Fetches application users for security authentication.
- Logging Aspect → Library Controller: advises · Intercepts controller execution for logging.
- Logging Aspect → Library Service: advises · Intercepts business methods for logging and tracing.
- Logging Aspect → Auth Controller: advises · Applies cross-cutting logging to auth endpoints.
- AOP Config → Logging Aspect: enables · Wires the aspect into application AOP support.