aceeca1/library-backend

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.