# f-lab-edu/off-coupon architecture

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

- Interactive diagram: https://gitdiagram.com/f-lab-edu/off-coupon
- Repository: https://github.com/f-lab-edu/off-coupon

## Overview

##### Main Components
- Client/API Layer: Represent the external entry points for HTTP clients (i.e. REST endpoints exposed via controllers like CouponIssueController, MemberController, etc.). This layer also includes security components (CustomAuthentication providers, handlers, and user detail service) for authentication/authorization.
- Application/Service Layer: This is where the core business logic resides. Separate components here include:
- Coupon issuance services (both synchronous and asynchronous flows)
- Order and coupon use management (OrderService, CouponUse logic)
- Member management (MemberService)
- Statistics and MyPage services for reporting and user interactions
- Scheduling components (DynamicScheduler, ScheduleRunner, etc.) for periodic tasks such as coupon issuing jobs.
- Integration & Asynchronous Processing:
- Messaging components using RabbitMQ (Producer, MessageQueueCountChecker, various coupon issue consumers, etc.)
- Distributed lock components using different strategies: NamedLock, Lettuce (Redis), and Redisson (look in the “component/lock” package and corresponding tests).
- Persistence/Repository Layer:
- MySQL repositories (implemented via MyBatis mappers and repository interfaces for Coupon, Member, Event, etc.)
- Redis repositories (and caching components for coupon and event caches)
- External Systems & Infrastructure:
- MySQL database (the main persistent store)
- Redis instance (for caching and distributed locking)
- RabbitMQ (for asynchronous messaging and queuing)
- Docker-based deployments and load-test setups indicate containerization and performance testing capabilities.

##### Relationships and Data Flows
- Controllers calling the service layer and from there the flow splitting to either synchronous coupon issuance or asynchronous operations via RabbitMQ.
- That services interact with distributed lock modules to ensure consistency before accessing the MySQL backend.
- Service layer interacting with persistence layers (MyBatis mappers, repositories).
- Scheduled tasks as separate components that trigger service methods at predetermined intervals.
- Optionally, mark the testing & CICD components (Jenkins pipelines, Docker, Gradle build scripts) as supporting infrastructure around the main system.

##### Architectural Patterns and Technologies
- Layered (or n-tier) architecture: Clearly separate Controllers, Services, Repositories, and External Integrations.
- Use of distributed locking patterns with multiple implementations (Lettuce, Redisson, MySQL NamedLock) to address high concurrency.
- Asynchronous processing via RabbitMQ and scheduled tasks indicating event-driven design.
- Technologies: Java 17, Spring Boot (core framework), MySQL, MyBatis for ORM, Redis for caching and locking, RabbitMQ for messaging, Docker for containerization, Gradle as the build tool.
- Distributed systems concerns are addressed with high-availability patterns and robust exception handling (check exception packages for coupon, member, event, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["HTTP Clients"]:::external

    %% API and Security Layer
    APICtrls["API Controllers\n(CouponIssueController, MemberController, etc.)"]:::api
    Security["Security Module\n(Authentication providers, handlers, etc.)"]:::api

    %% Service/Application Layer
    CouponSync["Coupon Issuance Service (Sync)"]:::service
    CouponAsync["Coupon Issuance Service (Async)"]:::service
    OrderCoupon["Order & Coupon Use Management"]:::service
    MemberMgmt["Member Management"]:::service
    Statistics["Statistics Service"]:::service
    MyPage["MyPage Service"]:::service
    Scheduler["Scheduler"]:::service

    %% Distributed Lock Manager
    DistLock["Distributed Lock Manager\n(Lettuce, NamedLock, Redisson)"]:::lock

    %% Persistence/Repository Layer
    MysqlRepo["MySQL Repositories"]:::repository
    RedisRepo["Redis Repositories & Cache"]:::repository

    %% Messaging Components
    RabbitMQMsg["RabbitMQ Messaging"]:::messaging
    RedisMsg["Redis Messaging"]:::messaging

    %% External Systems & Infrastructure
    MysqlDB["MySQL Database"]:::external
    RedisInst["Redis Instance"]:::external
    RabbitMQBroker["RabbitMQ Broker"]:::external
    DockerCont["Docker/Containerization"]:::container
    RabbitMQSetup["RabbitMQ Container Setup"]:::container

    %% Data Flows
    Clients -->|"HTTP Request"| APICtrls
    APICtrls -->|"auth"| Security

    APICtrls -->|"initiate"| CouponSync
    APICtrls -->|"initiate"| CouponAsync
    APICtrls -->|"initiate"| OrderCoupon
    APICtrls -->|"initiate"| MemberMgmt

    CouponSync -->|"lock-check"| DistLock
    DistLock -->|"persist lock"| MysqlRepo
    DistLock -->|"persist lock"| RedisRepo

    CouponAsync -->|"send async msg"| RabbitMQMsg
    RabbitMQMsg -->|"publish"| RabbitMQBroker

    %% Service calls to persistence
    CouponSync -->|"repo call"| MysqlRepo
    OrderCoupon -->|"repo call"| MysqlRepo
    MemberMgmt -->|"repo call"| MysqlRepo
    Statistics -->|"repo call"| MysqlRepo
    MyPage -->|"repo call"| MysqlRepo
    CouponSync -->|"cache access"| RedisRepo

    %% Scheduler triggers
    Scheduler -->|"trigger"| CouponSync
    Scheduler -->|"trigger"| OrderCoupon
    Scheduler -->|"trigger"| MemberMgmt

    %% Redis Messaging to external Redis
    RedisMsg -->|"publish"| RedisInst

    %% Repository external links
    MysqlRepo -->|"stores data"| MysqlDB
    RedisRepo -->|"stores cache"| RedisInst

    %% External container relation
    RabbitMQSetup -->|"configures"| RabbitMQBroker

    %% Click Events
    click APICtrls "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/controller"
    click Security "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/config/security"
    click CouponSync "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/service/coupon_issue/sync"
    click CouponAsync "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/service/coupon_issue/async"
    click OrderCoupon "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/service/coupon_use"
    click MemberMgmt "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/service"
    click Statistics "https://github.com/f-lab-edu/off-coupon/blob/develop/src/main/java/com/flab/offcoupon/service/StatisticsService.java"
    click MyPage "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/service/mypage"
    click Scheduler "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/component/scheduler"
    click RabbitMQMsg "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/component/rabbitmq"
    click RedisMsg "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/component/redis"
    click DistLock "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/component/lock"
    click MysqlRepo "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/repository/mysql"
    click RedisRepo "https://github.com/f-lab-edu/off-coupon/tree/develop/src/main/java/com/flab/offcoupon/repository/redis"
    click RabbitMQSetup "https://github.com/f-lab-edu/off-coupon/blob/develop/rabbitmq/docker-compose.yaml"

    %% Styles
    classDef api fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef service fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef repository fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef messaging fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef lock fill:#ffdead,stroke:#333,stroke-width:2px;
    classDef external fill:#e0ffff,stroke:#333,stroke-width:2px;
    classDef container fill:#f0e68c,stroke:#333,stroke-width:2px;
```
