# gurudath-s/library-management-modulith architecture

> Architecture diagram of the GitHub repository gurudath-s/library-management-modulith, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gurudath-s/library-management-modulith
- Repository: https://github.com/gurudath-s/library-management-modulith

## Overview

##### Project Type and Purpose
- This is a backend‐only Modular Monolith application (no separate UI here) built with Spring Boot and Spring Modulith.
- It implements a Library Management System: user authentication, book catalog, transaction (borrow/return) processing, plus an analytics dashboard.

##### File Structure Analysis
- Top-level: Docker and build files, pom.xml, src/main contains Java packages under com.library.
- Under src/main/java/com/library: five modules by directory name:
- users
- books
- transactions
- analytics
- shared (common events/contracts)
- Each module follows an MVC-style layering: Controller → Service (implements ModuleAPI) → Repository.
- Shared emits domain events (BookAddedEvent, etc.) used by other modules.
- Security config and JWT filters live in users module.

##### Key README Insights
- Architecture Pattern: Spring Modulith (modular monolith) with explicit module boundaries and event bus.
- Modules communicate via type-safe Java interfaces (ModuleAPI) and Spring application events (@Externalized).
- Dependency graph:
Shared
↓
Users → Books → Transactions → Analytics
↘───────────↗
- Security: JWT, BCrypt, role-based access.
- Persistence: Spring Data JPA.
- Tech stack: Spring Boot 3.3, Spring Security, Spring Data, Jackson, Docker.

a. Main Components
- External Clients (e.g. REST consumers, Postman, front-end apps)
- API Gateway (if applicable, or direct REST controllers)
- Modules:
- User Management Module
- Book Management Module
- Transaction Management Module
- Analytics Module
- Shared Module (event definitions)
- Event Bus (Spring ApplicationEventPublisher)
- Relational Database (JPA/Hibernate)
- Security Layer (JWT filter chain within Users module)
- Docker / Compose environment (container boundary)

b. Relationships & Data Flows
- Clients → REST Controllers (AuthController, BookController, etc.)
- Controllers → Services (ModuleAPI implementations)
- Services → Repositories → Database
- Services → Event Bus → Other Modules (e.g. BookService publishes BookAddedEvent consumed by Analytics)

c. Important Patterns & Principles
- Modular Monolith: each package is an explicit module with public boundary interfaces.
- Layered Architecture: Controller, Service, Repository layers per module.
- Event-Driven Integration: domain events decouple modules.
- Security Cross-Cutting: JWT filter, method-level @PreAuthorize.
- DTO Pattern: clear request/response objects per module.

d. Technologies & Frameworks
- Spring Boot / Spring Web (REST)
- Spring Modulith (@Modulith, ModuleAPI, @Externalized)
- Spring Security (SecurityConfig, JwtAuthenticationFilter, JwtUtils)
- Spring Data JPA / Hibernate
- Jackson for JSON
- Docker, docker-compose for containerization

##### Detailed Coverage
- To capture:
- Module dependency graph (Shared → Users → Books → Transactions → Analytics)
- Cross-cutting Security (JWT filter before all controllers)
- Event-driven flows (BookAddedEvent, BookBorrowedEvent, BookReturnedEvent, UserRegisteredEvent)
- Docker boundary showing application container and database container

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef module fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef infra fill:#DFF5D0,stroke:#333,stroke-width:1px
    classDef security fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px

    Clients["External Clients"]:::external
    JwtFilter["JWT Authentication Filter"]:::security

    subgraph "Docker Compose"
        subgraph "App Container"
            subgraph "User Management Module"
                direction TB
                UC1["AuthController"]:::module
                UC2["UserController"]:::module
                US["UserService\n(implements UserModuleAPI)"]:::module
                UMA["UserModuleAPI"]:::module
                UR["UserRepository"]:::module
                SC["SecurityConfig"]:::module
                JF["JwtAuthenticationFilter"]:::module
                JU["JwtUtils"]:::module
            end

            subgraph "Book Management Module"
                direction TB
                BC["BookController"]:::module
                BS["BookService\n(implements BookModuleAPI)"]:::module
                BAPI["BookModuleAPI"]:::module
                BR["BookRepository"]:::module
                BE["Book Entity"]:::module
            end

            subgraph "Transaction Management Module"
                direction TB
                TC["TransactionController"]:::module
                TS["TransactionService\n(implements TransactionModuleAPI)"]:::module
                TAPI["TransactionModuleAPI"]:::module
                TR["TransactionRepository"]:::module
                TE["Transaction Entity"]:::module
            end

            subgraph "Analytics Module"
                direction TB
                AC["AnalyticsController"]:::module
                AS["AnalyticsService\n(implements AnalyticsModuleAPI)"]:::module
                AAPI["AnalyticsModuleAPI"]:::module
                AD["AnalyticsDashboardDto"]:::module
            end

            subgraph "Shared Module"
                direction TB
                SAE["BookAddedEvent"]:::module
                SBE["BookBorrowedEvent"]:::module
                SRE["BookReturnedEvent"]:::module
                URE["UserRegisteredEvent"]:::module
            end

            EventBus["Event Bus"]:::infra
        end

        subgraph "Database Container"
            Database["Relational Database"]:::infra
        end
    end

    Clients -->|"HTTP Request"| JwtFilter
    JwtFilter --> UC1
    JwtFilter --> UC2
    JwtFilter --> BC
    JwtFilter --> TC
    JwtFilter --> AC

    UC1 --> US
    UC2 --> US
    US --> UR
    US -.implements.-> UMA
    US -->|ModuleAPI| BAPI
    US -->|publishes UserRegisteredEvent| EventBus

    BC --> BS
    BS --> BR
    BS -.implements.-> BAPI
    BS -->|publishes BookAddedEvent| EventBus

    TC --> TS
    TS --> TR
    TS -.implements.-> TAPI
    TS -->|ModuleAPI| BAPI
    TS -->|ModuleAPI| UMA
    TS -->|publishes BookBorrowedEvent & BookReturnedEvent| EventBus

    AC --> AS
    AS -->|implements| AAPI
    AS -->|subscribes to events| EventBus

    EventBus --> AS
    EventBus --> BS
    EventBus --> TS

    UR --> Database
    BR --> Database
    TR --> Database

    click UC1 "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/AuthController.java"
    click UC2 "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/UserController.java"
    click US "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/UserService.java"
    click UMA "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/UserModuleAPI.java"
    click UR "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/UserRepository.java"
    click SC "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/SecurityConfig.java"
    click JF "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/JwtAuthenticationFilter.java"
    click JU "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/users/JwtUtils.java"

    click BC "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/books/BookController.java"
    click BS "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/books/BookService.java"
    click BAPI "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/books/BookModuleAPI.java"
    click BR "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/books/BookRepository.java"
    click BE "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/books/Book.java"

    click TC "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/transactions/TransactionController.java"
    click TS "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/transactions/TransactionService.java"
    click TAPI "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/transactions/TransactionModuleAPI.java"
    click TR "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/transactions/TransactionRepository.java"
    click TE "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/transactions/Transaction.java"

    click AC "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/analytics/AnalyticsController.java"
    click AS "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/analytics/AnalyticsService.java"
    click AAPI "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/analytics/AnalyticsModuleAPI.java"
    click AD "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/analytics/AnalyticsDashboardDto.java"

    click SAE "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/shared/events/BookAddedEvent.java"
    click SBE "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/shared/events/BookBorrowedEvent.java"
    click SRE "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/shared/events/BookReturnedEvent.java"
    click URE "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/shared/events/UserRegisteredEvent.java"
    click Database "https://github.com/gurudath-s/library-management-modulith/blob/main/docker-compose.yml"
    click EventBus "https://github.com/gurudath-s/library-management-modulith/tree/main/src/main/java/com/library/shared"
    click Database "https://github.com/gurudath-s/library-management-modulith/blob/main/src/main/java/com/library/LibraryModulithApplication.java"
```
