# dahoon7151/qpbe-library-task architecture

> Architecture diagram of the GitHub repository dahoon7151/qpbe-library-task, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dahoon7151/qpbe-library-task
- Repository: https://github.com/dahoon7151/qpbe-library-task

## Overview

##### Project type and purpose
- This is a **backend-only, Spring Boot REST API** for an **online library management system**.
- Core features: JWT-based authentication, book CRUD + tagging, loan management, Redis caching with Pub/Sub for cache consistency, CI/CD via GitHub Actions, containerized with Docker.

##### File structure
- Top-level artifacts:
- Dockerfile, docker-compose.yml → container build & orchestration
- build.gradle.kts, settings.gradle.kts → Gradle build
- .github/workflows/cicd.yml → CI/CD pipeline
- docs/ → JMeter test plans, performance/consistency reports, Swagger JSON
- src/main/java/com/dahoon/qpbetask:
- book, loan, user packages → Controllers, DTOs, Services, Repositories, Entities
- common/config → RedisConfig, SecurityConfig, SwaggerConfig
- common/cache → CacheInvalidationPublisher/Subcriber
- common/GlobalExceptionHandler
- src/test → Controller integration tests with SpringBootTest

##### Key architecture pointers from README
- Layered MVC: Controller → Service → Repository
- Spring Security filter chain with JwtAuthenticationFilter → JwtTokenProvider
- JPA for MySQL persistence
- Redis for caching (Read-Aside + Write-Around) + Pub/Sub for multi-instance invalidation
- CI/CD: build → test → Docker image → push → deploy via docker-compose

##### Components
A. External Clients
- Web/Mobile apps (or Postman/JMeter) invoking REST endpoints
B. API Layer (Spring Boot Application)
- **Entry point**: QpbetaskApplication → Actuator health check
- **Security**: SecurityConfig, JwtAuthenticationFilter, JwtAuthenticationEntryPoint
- **Controllers**: UserController, BookController, LoanController
C. Business Layer
- **Services**: UserService, BookService, LoanService
- **Cache Layer**:
- Redis Cache (Read-Aside for GETs)
- CacheInvalidationPublisher (on POST/PATCH/DELETE)
- CacheInvalidationSubscriber (listening on Redis Pub/Sub channel)
D. Persistence Layer
- **Repositories**: UserRepository, BookRepository, TagRepository, BookTagRepository, LoanRepository
- **Database**: MySQL
- **Entities**: User, Book, Tag, BookTag, Loan
E. Infrastructure/DevOps
- **CI/CD**: GitHub Actions → Gradle build, SpringBootTest + containerized MySQL/Redis services
- **Containerization**: Dockerfile for app image, docker-compose.yml to spin up app + MySQL + Redis
- **Monitoring/Docs**: Swagger UI, Actuator, JMeter test plans under docs/

##### Relationships & interactions
- Client → (HTTPS + JWT) → Security Filter Chain → Controllers
- Controllers ↔ Services ↔ Repositories ↔ MySQL
- Services ↔ Redis Cache (check cache before DB read, populate on cache miss)
- Write operations → Services call CacheInvalidationPublisher → Redis Pub/Sub channel → other instances’ CacheInvalidationSubscriber clears stale keys
- CI/CD pipeline → builds Docker image → pushes to registry → docker-compose deploys all containers → health check via /actuator/health

##### Architectural patterns & design principles
- Layered architecture (Controller-Service-Repository)
- Token-based stateless authentication (JWT + Spring Security)
- Cache-Aside + Write-Around strategy with Pub/Sub eventing for distributed cache consistency
- Transactional boundaries in services to maintain data integrity and avoid orphan entities
- Docker-Compose for local multi-container orchestration, GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "External Clients"
        Clients["Clients (Web/Mobile/Postman/JMeter)"]:::external
    end

    Clients -->|"HTTPS + JWT"| QpApp

    %% Spring Boot Application
    subgraph "Spring Boot App"
        direction TB
        QpApp["QpbetaskApplication"]:::app
        click QpApp "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/QpbetaskApplication.java"

        %% Security Layer
        subgraph "Security Layer"
            direction TB
            SecurityConfig["SecurityConfig"]:::config
            click SecurityConfig "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/common/config/SecurityConfig.java"
            JwtFilter["JwtAuthenticationFilter"]:::config
            click JwtFilter "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/user/component/JwtAuthenticationFilter.java"
            JwtEntry["JwtAuthenticationEntryPoint"]:::config
            click JwtEntry "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/user/component/JwtAuthenticationEntryPoint.java"
            JwtProvider["JwtTokenProvider"]:::config
            click JwtProvider "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/user/component/JwtTokenProvider.java"
        end

        QpApp --> SecurityConfig
        SecurityConfig --> JwtFilter
        SecurityConfig --> JwtEntry
        JwtFilter --> JwtProvider

        %% Controllers
        subgraph "Controllers" 
            direction TB
            UserController["UserController"]:::app
            click UserController "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/user/UserController.java"
            BookController["BookController"]:::app
            click BookController "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/book/BookController.java"
            LoanController["LoanController"]:::app
            click LoanController "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/loan/LoanController.java"
        end

        SecurityConfig --> UserController
        SecurityConfig --> BookController
        SecurityConfig --> LoanController

        %% Services
        subgraph "Business Services"
            direction TB
            UserService["UserService"]:::service
            click UserService "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/user/UserService.java"
            BookService["BookService"]:::service
            click BookService "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/book/BookService.java"
            LoanService["LoanService"]:::service
            click LoanService "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/loan/LoanService.java"
        end

        UserController --> UserService
        BookController --> BookService
        LoanController --> LoanService

        %% Cache Layer
        subgraph "Cache Layer"
            direction TB
            RedisCfg["RedisConfig"]:::config
            click RedisCfg "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/common/config/RedisConfig.java"
            Publisher["CacheInvalidationPublisher"]:::cache
            click Publisher "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/common/cache/CacheInvalidationPublisher.java"
            Subscriber["CacheInvalidationSubscriber"]:::cache
            click Subscriber "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/common/cache/CacheInvalidationSubscriber.java"
        end

        BookService --> RedisCfg
        LoanService --> RedisCfg
        Publisher -->|"on write ops"| Subscriber

        %% Exception Handler
        GlobalEx["GlobalExceptionHandler"]:::config
        click GlobalEx "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/common/GlobalExceptionHandler.java"
        QpApp --> GlobalEx

        %% Repositories
        subgraph "Repositories"
            direction TB
            UserRepo["UserRepository"]:::repo
            click UserRepo "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/user/UserRepository.java"
            BookRepo["BookRepository"]:::repo
            click BookRepo "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/book/repository/BookRepository.java"
            TagRepo["TagRepository"]:::repo
            click TagRepo "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/book/repository/TagRepository.java"
            BookTagRepo["BookTagRepository"]:::repo
            click BookTagRepo "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/book/repository/BookTagRepository.java"
            LoanRepo["LoanRepository"]:::repo
            click LoanRepo "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/loan/LoanRepository.java"
        end

        UserService --> UserRepo
        BookService --> BookRepo
        BookService --> TagRepo
        BookService --> BookTagRepo
        LoanService --> LoanRepo

        %% Entities are implicit within Repositories

    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MySQL["MySQL Database"]:::store
        RedisStore["Redis Cache"]:::store
    end

    BookRepo --> MySQL
    UserRepo --> MySQL
    LoanRepo --> MySQL
    TagRepo --> MySQL
    BookTagRepo --> MySQL

    RedisCfg --> RedisStore
    Publisher --> RedisStore
    RedisStore --> Subscriber
    Subscriber --> RedisStore

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        GHActions["GitHub Actions (cicd.yml)"]:::infra
        click GHActions "https://github.com/dahoon7151/qpbe-library-task/blob/main/.github/workflows/cicd.yml"
        DockerfileNode["Dockerfile"]:::infra
        click DockerfileNode "https://github.com/dahoon7151/qpbe-library-task/tree/main/Dockerfile"
        DockerCompose["docker-compose.yml"]:::infra
        click DockerCompose "https://github.com/dahoon7151/qpbe-library-task/blob/main/docker-compose.yml"
        SwaggerCfg["SwaggerConfig"]:::config
        click SwaggerCfg "https://github.com/dahoon7151/qpbe-library-task/blob/main/src/main/java/com/dahoon/qpbetask/common/config/SwaggerConfig.java"
        SwaggerJSON["Swagger JSON"]:::infra
        click SwaggerJSON "https://github.com/dahoon7151/qpbe-library-task/blob/main/docs/qpbe_swagger.json"
        JMeterPlans["JMeter Test Plans"]:::infra
        click JMeterPlans "https://github.com/dahoon7151/qpbe-library-task/blob/main/docs/QPBE_cache_consistency_test.jmx"
    end

    GHActions --> DockerfileNode
    DockerfileNode --> DockerCompose
    DockerCompose --> QpApp
    QpApp -->|"Health Check (/actuator/health)"| GHActions

    %% Styles
    classDef app fill:#D6E9FE,stroke:#4D8BF5;
    classDef config fill:#E8F4D9,stroke:#3C8031;
    classDef service fill:#B2E2D0,stroke:#2C7A5B;
    classDef cache fill:#FFF4D6,stroke:#E09F3E;
    classDef repo fill:#E8D2EF,stroke:#8E44AD;
    classDef external fill:#FFE2E2,stroke:#E04C4C;
    classDef store fill:#DFF0D8,stroke:#3C8031;
    classDef infra fill:#FDEBD0,stroke:#DC7633;
```
