# kimh4nkyul/coffee-shop architecture

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

- Interactive diagram: https://gitdiagram.com/kimh4nkyul/coffee-shop
- Repository: https://github.com/kimh4nkyul/coffee-shop

## Overview

##### Project Type and Purpose
- This is a backend service – a Spring Boot-based coffee shop ordering system.
- Its purpose is to manage operations such as placing orders, managing user points (charging, point transactions), retrieving menus (including popular menus), and ensuring consistency even under high concurrency.
- It also integrates with external platforms for data collection via Kafka and leverages Redis for caching to improve performance.

##### Analyzing the File Structure
- Top-level directories and files indicate a standard Gradle-based Spring Boot project.
- The main application code is located under src/main/java with clearly divided packages:
- common: contains shared components like exception handling, Kafka message publishing, distributed locks, and transactional handling.
- menu, order, user: separate bounded contexts handling your core business areas.
- The presence of configuration files (e.g., application.yml, SwaggerConfig, QueryDslConfig) implies API documentation (via Swagger) and custom query configuration.
- Additional build and deployment files (Dockerfile, GitHub Actions workflows, gradle wrapper) suggest CI/CD and containerization aspects.
- SQL scripts (ddl.sql, init_menu.sql) indicate that there is a standardized database schema initialization and migration process.

##### Components and Their Interactions
a. Main Components to Include:
- Client/API Layer:
- Represented by REST controllers (e.g., MenuController, OrderController, UserController).
- An entry point for API consumers documented by Swagger.
- Service / Business Logic Layer:
- Contains service classes (MenuService, OrderService, UserPointService) that encapsulate business logic.
- Implements functionality for order processing, menu retrieval, and point transactions.
- Data Access Layer:
- JPA repositories (MenuRepository, OrderRepository, UserRepository, etc.) connecting to a MySQL database.
- SQL initialization scripts ensure proper schema setup.
- Event Processing:
- Kafka integration for publishing order events (e.g., OrderCreatedEvent, KafkaMessagePublisher).
- Utilizes @TransactionalEventListener to publish only after database transactions have committed.
- Caching Layer:
- Redis is used to cache frequently accessed data such as popular menu queries.
- Concurrency & Transaction Management:
- Use of distributed locks (seen in DistributedLockAop) and transaction handlers ensures data consistency under concurrent order submissions.
- Error Handling & Cross-Cutting Concerns:
- Global exception handling (ControllerAdvice) ensures consistent API responses.
- Custom exception classes for domain-specific error responses.

b. Relationships and Interactions:
- API calls from clients enter through controllers and are routed to service layers.
- Services interact with the database via repositories; for read-heavy operations, they also interact with Redis for caching.
- After successful order transactions, an event is published via Kafka to external systems for real-time data collection.
- Distributed locks and transaction handlers enforce consistency, especially in scenarios where simultaneous orders might affect points balance.
- The configuration modules (e.g., SwaggerConfig, QueryDslConfig) tie into everything by providing cross-cutting settings.

c. Architectural Patterns and Design Principles:
- Layered Architecture: The project follows a clear separation between controllers, services, and repositories.
- Domain-Driven Design: Division into modules such as order, menu, and user reflects separation of business concerns.
- Event-driven Architecture: Using Kafka for asynchronous event processing once transactions are completed.
- Transactional Integrity: Use of transactional event listeners and distributed locks to manage concurrent operations.

d. Relevant Technologies:
- Spring Boot with Java 17, JPA, and MySQL for core backend.
- Redis for caching selected queries.
- Kafka for event messaging.
- Swagger for API documentation.
- Gradle for build automation and Docker for containerization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client (API Consumer)"]:::external

    %% API Layer
    subgraph "API Layer"
        MenuAPI["MenuController"]:::apiLayer
        OrderAPI["OrderController"]:::apiLayer
        UserAPI["UserController"]:::apiLayer
        ControllerAdvice["ControllerAdvice"]:::apiLayer
    end

    Client --> MenuAPI
    Client --> OrderAPI
    Client --> UserAPI

    %% Business Logic Layer
    subgraph "Business Logic"
        MenuService["MenuService"]:::serviceLayer
        OrderService["OrderService"]:::serviceLayer
        PopularMenuService["PopularMenuService"]:::serviceLayer
        UserPointService["UserPointService"]:::serviceLayer
    end

    MenuAPI --> MenuService
    OrderAPI --> OrderService
    UserAPI --> UserPointService

    %% Concurrency & Transaction Management
    subgraph "Concurrency & Transaction Management"
        DistributedLock["DistributedLock"]:::concurrency
        DistributedLockAop["DistributedLockAop"]:::concurrency
        TransactionHandler["TransactionHandler"]:::concurrency
    end

    OrderService --> DistributedLock
    OrderService --> DistributedLockAop
    OrderService --> TransactionHandler
    UserPointService --> TransactionHandler

    %% Data Access Layer
    subgraph "Data Access Layer"
        MenuRepo["MenuRepository"]:::repositoryLayer
        OrderRepo["OrderRepository"]:::repositoryLayer
        UserRepo["UserRepository"]:::repositoryLayer
        PointTransRepo["PointTransactionRepository"]:::repositoryLayer
    end

    MenuService --> MenuRepo
    OrderService --> OrderRepo
    UserPointService --> UserRepo
    UserPointService --> PointTransRepo

    %% External Integrations: Database and Caching
    subgraph "External Integrations"
        MySQL["MySQL Database"]:::database
        RedisCache["Redis Cache"]:::external
    end

    MenuRepo --> MySQL
    OrderRepo --> MySQL
    UserRepo --> MySQL
    PointTransRepo --> MySQL

    %% Event Processing Subsystem
    subgraph "Event Processing"
        KafkaPublisher["KafkaMessagePublisher"]:::eventProcessing
        Kafka["Kafka Cluster"]:::eventProcessing
        OrderCreatedListener["OrderCreatedEventListener"]:::eventProcessing
        OrderCreatedEvent["OrderCreatedEvent"]:::eventProcessing
    end

    OrderService -->|"publishes"| KafkaPublisher
    KafkaPublisher --> Kafka
    Kafka --> OrderCreatedListener
    OrderCreatedListener --> OrderCreatedEvent

    %% Caching Interaction
    PopularMenuService --> RedisCache

    %% Configuration & Auxiliary
    subgraph "Configuration & Auxiliary"
        SwaggerConfig["SwaggerConfig"]:::config
        QueryDslConfig["QueryDslConfig"]:::config
        DDLScript["ddl.sql"]:::database
        MenuInitScript["init_menu.sql"]:::database
        RedisTestContainer["Redis TestContainer"]:::external
    end

    %% Error Handling Components
    ControllerAdvice --> CoffeeShopException["CoffeeShopException"]:::errorHandling
    ControllerAdvice --> CoffeeShopBadRequestException["CoffeeShopBadRequestException"]:::errorHandling
    ControllerAdvice --> CoffeeShopErrors["CoffeeShopErrors"]:::errorHandling

    %% Database Script Connections
    MySQL --> DDLScript
    MySQL --> MenuInitScript

    %% Configuration impacts API and Repositories
    SwaggerConfig --> MenuAPI
    SwaggerConfig --> OrderAPI
    SwaggerConfig --> UserAPI

    QueryDslConfig --> MenuRepo
    QueryDslConfig --> OrderRepo
    QueryDslConfig --> UserRepo

    %% Click Events
    click MenuAPI "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/menu/controller/MenuController.java"
    click OrderAPI "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/order/controller/OrderController.java"
    click UserAPI "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/user/controller/UserController.java"
    click MenuService "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/menu/application/MenuService.java"
    click OrderService "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/order/application/OrderService.java"
    click PopularMenuService "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/order/application/PopularMenuService.java"
    click UserPointService "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/user/application/UserPointService.java"
    click MenuRepo "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/menu/domain/MenuRepository.java"
    click OrderRepo "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/order/domain/OrderRepository.java"
    click UserRepo "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/user/domain/UserRepository.java"
    click PointTransRepo "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/user/domain/PointTransactionRepository.java"
    click KafkaPublisher "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/KafkaMessagePublisher.java"
    click OrderCreatedEvent "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/order/event/OrderCreatedEvent.java"
    click OrderCreatedListener "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/order/event/OrderCreatedEventListener.java"
    click DistributedLock "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/aop/DistributedLock.java"
    click DistributedLockAop "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/aop/DistributedLockAop.java"
    click TransactionHandler "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/TransactionHandler.java"
    click ControllerAdvice "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/advice/ControllerAdvice.java"
    click CoffeeShopException "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/CoffeeShopException.java"
    click CoffeeShopBadRequestException "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/CoffeeShopBadRequestException.java"
    click CoffeeShopErrors "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/common/CoffeeShopErrors.java"
    click SwaggerConfig "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/config/SwaggerConfig.java"
    click QueryDslConfig "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/main/java/com/sample/coffeeshop/config/QueryDslConfig.java"
    click DDLScript "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/sql/ddl.sql"
    click MenuInitScript "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/sql/init_menu.sql"
    click RedisTestContainer "https://github.com/kimh4nkyul/coffee-shop/blob/develop/src/test/java/com/sample/coffeeshop/common/RedisTestContainer.java"

    %% Styles
    classDef apiLayer fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef serviceLayer fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef repositoryLayer fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef eventProcessing fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef concurrency fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
    classDef config fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef errorHandling fill:#f5d6d1,stroke:#a71d2a,stroke-width:2px;
```
