# aceeca1/library-backend architecture

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

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

## Overview

1. This is a single Spring Boot 3 / Java 17 backend monolith for a digital library. The code is organized into the usual layered boundary: REST controllers at the edge, service classes for business logic, Spring Data repositories for persistence, JPA entities in `model`, and DTOs for all API payloads.

2. The main domain is a PDF book library. Core entities include `Book`, `Category`, `Tag`, `Series`, `BookView`, `Bookmark`, `ReadingProgress`, `Review`, `Comment`, `Report`, `Notification`, and `User`. That gives the system both content management and user-interaction behavior in one backend.

3. Authentication and authorization are a major subsystem. `AuthController`, `AuthService`, `JwtAuthenticationFilter`, `JwtUtils`, `RefreshTokenService`, and `SecurityConfig` implement JWT login/session handling, refresh tokens, password reset, profile updates, bans/timeouts, and role/permission-based access control. `RateLimitFilter` adds an additional security boundary at the HTTP layer.

4. Administration is separated from general user flows. `AdminController`, `UserManagementController`, `RoleManagementController`, and `ReportController` support moderation, user lifecycle actions, role assignment, and audit visibility. Admin requests are backed by DTOs for bans, timeouts, role creation/update, and audit metadata updates.

5. Book ingestion and processing is a distinct pipeline. The README and classes like `BookService`, `MetadataService`, and `VirusScanService` indicate uploaded PDFs are validated, virus-scanned via ClamAV, and then processed for thumbnail generation and text extraction. `BookSearchRepositoryImpl` suggests extracted text is indexed for fast search, likely using a separate search-oriented persistence path from the main book record.

6. Search and metadata are modeled as first-class concerns. Repositories exist for books, book views, categories, tags, and series, and the controller/service split for metadata shows that categorization is managed independently from the core book entity. Related-book suggestions are likely derived from shared categories or tags rather than a separate recommendation service.

7. User engagement features form another cluster. `BookmarkService`, `ReadingProgressService`, `CommentService`, and `ReviewService` support personal collections, reading state, nested discussion, voting, and rating aggregation. DTOs in these packages show the API is designed around request/response shaping rather than exposing entities directly.

8. Notifications and real-time updates are handled separately from core CRUD. `NotificationService`, `NotificationController`, `WebSocketConfig`, and `WebSocketAuthInterceptor` indicate STOMP over WebSocket for live delivery, while persisted notifications are still stored through `NotificationRepository`. This creates a split between durable notification history and real-time push.

9. The system uses asynchronous messaging for cross-cutting side effects. `RabbitMQConfig`, `AuditProducer`, `AuditConsumer`, `BadgeProducer`, and `BadgeConsumer` show RabbitMQ is used to decouple event generation from processing. Audit logging and badge awarding are both event-driven workflows rather than inline synchronous updates.

10. Audit logging is a dedicated subsystem, not just a table. `AuditLog`, `AuditLogRepository`, `AuditLogService`, and the audit DTO/message classes indicate administrative and user actions are captured, published, and consumed asynchronously. This is important for diagramming because audit trails cross-cut many other business flows instead of living inside one controller.

11. Badge/achievement logic is similarly event-driven. The `badge` service package and `UserBadgeRepository` imply user engagement events trigger badge evaluation and persistence, with messages passing through RabbitMQ. That keeps gamification logic independent from comment, review, or reading-progress endpoints.

12. Persistence is standard Spring Data JPA over MySQL. The `dao` package contains repositories for each aggregate, plus specialized repos such as refresh tokens, password reset requests, comment votes, reports, and search/views. `BaseEntity` suggests common audit fields and identifiers are centralized at the entity layer.

13. Configuration and operational wiring are concentrated in `config`. `AppProperties`, `DataSeeder`, `SecurityConfig`, `RabbitMQConfig`, and WebSocket configuration classes define startup behavior, bootstrapping data, security rules, and infrastructure integration. `Dockerfile`, `.env` examples, and the Maven wrapper show the app is intended to be run containerized or via Maven directly.

14. Overall architecture: HTTP requests enter controllers, are filtered by JWT/rate-limit/security components, flow into services, and then reach repositories and external systems such as MySQL, RabbitMQ, WebSocket/STOMP clients, and ClamAV. The clearest diagram boundaries are the API layer, business services, persistence layer, and the async/integration layer around messaging and live notifications.

Main entry points: [`src/main/java/org/personal/library/dao`](https://github.com/aceeca1/library-backend/tree/master/src/main/java/org/personal/library/dao) (Repositories), [`src/main/java/org/personal/library/LibraryApplication.java`](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/LibraryApplication.java) (Library app), [`src/main/java/org/personal/library/service/book/BookService.java`](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/book/BookService.java) (Book service), [`src/main/java/org/personal/library/config/SecurityConfig.java`](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/config/SecurityConfig.java) (Security stack)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API layer"]
  node_api_auth["Auth API<br/>controller"]
  node_api_admin["Admin API<br/>controller"]
  node_api_books["Book API<br/>controller"]
  node_api_metadata["Metadata API<br/>controller"]
  node_api_engage["Engagement APIs<br/>controllers"]
end

subgraph group_domain["Core domain"]
  node_svc_auth["Auth service<br/>[AuthService.java]"]
  node_svc_books["Book service<br/>[BookService.java]"]
  node_svc_metadata["Metadata service"]
  node_svc_engage["Engagement services"]
  node_svc_users["User admin"]
  node_models{{"Entities<br/>jpa model"}}
end

subgraph group_platform["Platform layer"]
  node_app(("Library app<br/>spring boot entrypoint"))
  node_sec["Security stack<br/>filters/config"]
  node_ws["WebSocket stack<br/>config"]
  node_repos[("Repositories<br/>spring data jpa")]
  node_external(("External systems<br/>infra"))
end

subgraph group_async["Async flows"]
  node_mq["RabbitMQ<br/>messaging config"]
  node_audit["Audit flow<br/>producer/consumer/service"]
  node_badge["Badge flow<br/>producer/consumer/service<br/>[BadgeProducer.java]"]
end

node_app -->|"loads"| node_sec
node_app -->|"loads"| node_ws
node_app -->|"loads"| node_mq
node_app -->|"serves"| node_api_auth
node_app -->|"serves"| node_api_books
node_api_auth -->|"calls"| node_svc_auth
node_api_admin -->|"calls"| node_svc_users
node_api_books -->|"calls"| node_svc_books
node_api_metadata -->|"calls"| node_svc_metadata
node_api_engage -->|"calls"| node_svc_engage
node_svc_auth -->|"reads/writes"| node_repos
node_svc_books -->|"reads/writes"| node_repos
node_svc_books -->|"scans/processes"| node_external
node_svc_metadata -->|"reads/writes"| node_repos
node_svc_engage -->|"reads/writes"| node_repos
node_svc_users -->|"reads/writes"| node_repos
node_sec -->|"protects"| node_external
node_ws -->|"pushes"| node_external
node_audit -->|"publishes/consumes"| node_mq
node_badge -->|"publishes/consumes"| node_mq
node_audit -->|"writes"| node_repos
node_badge -->|"writes"| node_repos
node_svc_engage -.->|"emits"| node_audit
node_svc_engage -.->|"emits"| node_badge
node_svc_engage -.->|"notifies"| node_ws
node_repos -->|"maps"| node_models
node_sec -->|"authenticates"| node_svc_auth

click node_app "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/LibraryApplication.java"
click node_api_auth "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/auth/AuthController.java"
click node_api_admin "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/admin/AdminController.java"
click node_api_books "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/book/BookController.java"
click node_api_metadata "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/metadata/MetadataController.java"
click node_svc_auth "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/auth/AuthService.java"
click node_svc_books "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/book/BookService.java"
click node_svc_metadata "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/metadata/MetadataService.java"
click node_svc_users "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/user/UserManagementService.java"
click node_sec "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/config/SecurityConfig.java"
click node_ws "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/config/WebSocketConfig.java"
click node_mq "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/config/RabbitMQConfig.java"
click node_audit "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/audit/AuditLogService.java"
click node_badge "https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/badge/BadgeProducer.java"
click node_repos "https://github.com/aceeca1/library-backend/tree/master/src/main/java/org/personal/library/dao"
click node_models "https://github.com/aceeca1/library-backend/tree/master/src/main/java/org/personal/library/model"

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_api_auth,node_api_admin,node_api_books,node_api_metadata,node_api_engage toneBlue
class node_svc_auth,node_svc_books,node_svc_metadata,node_svc_engage,node_svc_users,node_models toneAmber
class node_app,node_sec,node_ws,node_repos,node_external toneMint
class node_mq,node_audit,node_badge toneRose
```

## Components

### API layer

HTTP controllers and request/response shaping

- [Auth API](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/auth/AuthController.java): controller · Login, refresh, password reset, and profile flows · `src/main/java/org/personal/library/controller/auth/AuthController.java`
- [Admin API](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/admin/AdminController.java): controller · User moderation, roles, and admin visibility · `src/main/java/org/personal/library/controller/admin/AdminController.java`
- [Book API](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/book/BookController.java): controller · Book ingestion, updates, and retrieval · `src/main/java/org/personal/library/controller/book/BookController.java`
- [Metadata API](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/controller/metadata/MetadataController.java): controller · Categories, tags, and series management · `src/main/java/org/personal/library/controller/metadata/MetadataController.java`
- **Engagement APIs**: controllers · Bookmarks, progress, comments, reviews, reports, notifications, and badges

### Core domain

Books, users, engagement, and metadata model

- [Auth service](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/auth/AuthService.java): service · JWT sessions, refresh tokens, and profile security · `src/main/java/org/personal/library/service/auth/AuthService.java`
- [Book service](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/book/BookService.java): service · PDF ingestion, validation, extraction, and persistence · `src/main/java/org/personal/library/service/book/BookService.java`
- [Metadata service](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/metadata/MetadataService.java): service · Book categorization and related metadata operations · `src/main/java/org/personal/library/service/metadata/MetadataService.java`
- **Engagement services**: services · Bookmarks, reading progress, comments, reviews, reports, and notifications
- [User admin](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/user/UserManagementService.java): service · Role assignment and user lifecycle moderation · `src/main/java/org/personal/library/service/user/UserManagementService.java`
- [Entities](https://github.com/aceeca1/library-backend/tree/master/src/main/java/org/personal/library/model): jpa model · Book, user, metadata, engagement, security, and audit entities · `src/main/java/org/personal/library/model`

### Platform layer

Security, configuration, storage, and infrastructure wiring

- [Library app](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/LibraryApplication.java): spring boot entrypoint · Application bootstrap and startup wiring · `src/main/java/org/personal/library/LibraryApplication.java`
- [Security stack](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/config/SecurityConfig.java): filters/config · JWT filter, rate limiting, token utils, and Spring Security rules · `src/main/java/org/personal/library/config/SecurityConfig.java`
- [WebSocket stack](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/config/WebSocketConfig.java): config · STOMP/WebSocket auth and live notification delivery · `src/main/java/org/personal/library/config/WebSocketConfig.java`
- [Repositories](https://github.com/aceeca1/library-backend/tree/master/src/main/java/org/personal/library/dao): spring data jpa · MySQL persistence for books, users, tokens, reports, search, and engagement · `src/main/java/org/personal/library/dao`
- **External systems**: infra · MySQL, ClamAV, and WebSocket clients

### Async flows

RabbitMQ-driven audit and badge processing

- [RabbitMQ](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/config/RabbitMQConfig.java): messaging config · Async event bus for audit and badge workflows · `src/main/java/org/personal/library/config/RabbitMQConfig.java`
- [Audit flow](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/audit/AuditLogService.java): producer/consumer/service · Action logging published and consumed asynchronously · `src/main/java/org/personal/library/service/audit/AuditLogService.java`
- [Badge flow](https://github.com/aceeca1/library-backend/blob/master/src/main/java/org/personal/library/service/badge/BadgeProducer.java): producer/consumer/service · Engagement events trigger badge evaluation and persistence · `src/main/java/org/personal/library/service/badge/BadgeProducer.java`

## Connections

- Library app → Security stack: loads · Registers security, filters, and application-level wiring
- Library app → WebSocket stack: loads · Enables WebSocket/STOMP support
- Library app → RabbitMQ: loads · Bootstraps RabbitMQ integration
- Library app → Auth API: serves · Exposes authentication endpoints
- Library app → Book API: serves · Exposes book endpoints
- Auth API → Auth service: calls · Delegates login and token flows
- Admin API → User admin: calls · Delegates moderation and role management
- Book API → Book service: calls · Delegates ingestion and book operations
- Metadata API → Metadata service: calls · Delegates category/tag/series changes
- Engagement APIs → Engagement services: calls · Delegates user interaction features
- Auth service → Repositories: reads/writes · Uses user, token, and password-reset repositories
- Book service → Repositories: reads/writes · Uses book and search repositories
- Book service → External systems: scans/processes · Validates PDFs and scans files with ClamAV
- Metadata service → Repositories: reads/writes · Persists categories, tags, and series
- Engagement services → Repositories: reads/writes · Persists comments, reviews, bookmarks, progress, reports, and notifications
- User admin → Repositories: reads/writes · Updates users, roles, permissions, and bans
- Security stack → External systems: protects · Secures HTTP access and rate-limits requests
- WebSocket stack → External systems: pushes · Delivers live notifications to clients
- Audit flow → RabbitMQ: publishes/consumes · Moves audit messages through RabbitMQ
- Badge flow → RabbitMQ: publishes/consumes · Moves badge events through RabbitMQ
- Audit flow → Repositories: writes · Stores audit log history
- Badge flow → Repositories: writes · Stores earned user badges
- Engagement services → Audit flow: emits · User actions generate audit events
- Engagement services → Badge flow: emits · Engagement events trigger badge workflows
- Engagement services → WebSocket stack: notifies · Sends live notification updates
- Repositories → Entities: maps · Repositories persist JPA entities
- Security stack → Auth service: authenticates · JWT filter and user details service support auth