# hunmin-dev/hunmin-backend architecture

> Architecture diagram of the GitHub repository hunmin-dev/hunmin-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hunmin-dev/hunmin-backend
- Repository: https://github.com/hunmin-dev/hunmin-backend

## Overview

##### Project Type and Purpose
- This is a Kotlin-based, multi-module backend server following a hexagonal (ports-and-adapters) architecture.
- It provides RESTful APIs (hunmin-api), business logic (hunmin-application), domain modeling (hunmin-domain), persistence (hunmin-persistence), external adapters (hunmin-adapter), shared utilities (hunmin-common), and a scheduled batch job (hunmin-batch).

##### Main Architectural Layers & Modules
a. API Layer (hunmin-api)
- Components: REST controllers (AuthController, CategoryController, TodayIssueController), DTOs, request/response models, global exception handlers, Swagger config.
- Entry point for HTTP clients.

b. Application Layer (hunmin-application)
- Components: AuthService, CategoryService, TodayIssueService, DomainEventInterceptor.
- Implements use cases defined in the domain ports (hunmin-domain). Coordinates transactions, security, events.

c. Domain Layer (hunmin-domain)
- Components: Domain entities (Auth, Category, TodayIssue), domain events, port interfaces (inbound/outbound), commands, value objects.
- Pure business logic and rules. No framework dependencies.

d. Persistence Layer (hunmin-persistence)
- Components: JPA entities, Spring Data repositories, mappers, config (persistence, auditing, QueryDSL).
- Implements the outbound ports (RepositoryPort) defined in the domain.

e. Adapter Layer (hunmin-adapter)
- Components: Adapters for auth encryption (Jasypt), adapter implementations of domain ports (AuthRepositoryAdapter, CategoryRepositoryAdapter, TodayIssueRepositoryAdapter).
- Bridges domain ports to persistence or external services.

f. Common Library (hunmin-common)
- Components: Cross-cutting concerns—authentication interceptors, JWT token provider, exception and logging utilities, global config.

g. Batch Module (hunmin-batch)
- Components: Scheduled Spring Batch job (TodayIssuesJobConfiguration), batch config classes.
- Periodically triggers domain/application services to generate today’s issues.

##### Diagramming Conventions
- Labels: Clearly name each module/component.
- API / Controllers – blue rectangles
- Application Services – green rectangles
- Domain & Ports – yellow rectangles
- Adapters – orange rectangles
- Batch – purple rectangle
- Common utilities – separate small grey rectangle

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Browser["Browser / Mobile Clients"]:::external

    %% API Layer
    subgraph "hunmin-api (API Layer)"
        direction TB
        AuthController["AuthController"]:::api
        CategoryController["CategoryController"]:::api
        TodayIssueController["TodayIssueController"]:::api
        DTOs["DTOs (request/response)"]:::api
        GlobalConfig["Global Config & Exceptions"]:::api
        AuthController -->|HTTP| AuthService
        CategoryController -->|HTTP| CategoryService
        TodayIssueController -->|HTTP| TodayIssueService
        Browser -->|REST| AuthController
        Browser -->|REST| CategoryController
        Browser -->|REST| TodayIssueController
    end

    %% Application Layer
    subgraph "hunmin-application (Application Layer)"
        direction TB
        AuthService["AuthService"]:::app
        CategoryService["CategoryService"]:::app
        TodayIssueService["TodayIssueService"]:::app
        DomainEventInterceptor["DomainEventInterceptor"]:::app
        AuthService -->|uses| DomainLayer
        CategoryService -->|uses| DomainLayer
        TodayIssueService -->|uses| DomainLayer
    end

    %% Domain Layer
    subgraph "hunmin-domain (Domain Layer)"
        direction TB
        subgraph "Entities & Events"
            AuthEntity["Auth"]:::domain
            CategoryEntity["Category"]:::domain
            TodayIssueEntity["TodayIssue"]:::domain
            TodayIssuesEntity["TodayIssues"]:::domain
        end
        subgraph "Ports"
            direction TB
            UseCasePorts["Inbound Ports (UseCases)"]:::domain
            OutboundPorts["Outbound Ports"]:::domain
        end
        AuthEntity -->|events| UseCasePorts
        CategoryEntity -->|events| UseCasePorts
        TodayIssueEntity -->|events| UseCasePorts
        UseCasePorts -->|calls| OutboundPorts
    end

    %% Adapter & Persistence Layers
    subgraph "External Adapters & Persistence"
        direction TB
        subgraph "hunmin-adapter (Adapters)" 
            direction TB
            AuthRepoAdapter["AuthRepositoryAdapter"]:::adapter
            PasswordEncryptAdapter["SecurityPasswordEncryptAdapter"]:::adapter
            CategoryRepoAdapter["CategoryRepositoryAdapter"]:::adapter
            TodayIssueRepoAdapter["TodayIssueRepositoryAdapter"]:::adapter
            TodayIssuesRepoAdapter["TodayIssuesRepositoryAdapter"]:::adapter
            AdapterConfig["AdapterConfig"]:::adapter
        end
        subgraph "hunmin-persistence (Persistence)"
            direction TB
            JPAEntities["JPA Entities"]:::persist
            Repositories["Spring Data Repositories"]:::persist
            Mappers["Persistence Mappers"]:::persist
            Configs["Persistence Config & Auditing"]:::persist
        end
        OutboundPorts -->|implemented by| AuthRepoAdapter
        OutboundPorts -->|implemented by| CategoryRepoAdapter
        OutboundPorts -->|implemented by| TodayIssueRepoAdapter
        OutboundPorts -->|implemented by| TodayIssuesRepoAdapter
        AuthRepoAdapter -->|maps to| JPAEntities
        CategoryRepoAdapter -->|maps to| JPAEntities
        TodayIssueRepoAdapter -->|maps to| JPAEntities
        TodayIssuesRepoAdapter -->|maps to| JPAEntities
        JPAEntities --> Repositories
        Repositories --> Database
        Mappers --> JPAEntities
        Configs --> Repositories
    end

    %% Database
    Database["Database (PostgreSQL/MySQL)"]:::db

    %% Batch Module
    subgraph "hunmin-batch (Batch Scheduler)" 
        direction TB
        BatchConfig["BatchConfig"]:::batch
        TodayIssuesJob["TodayIssuesJobConfiguration"]:::batch
        TodayIssuesJob -->|triggers| TodayIssueService
        BatchConfig --> TodayIssuesJob
    end

    %% Common Utilities
    Common["hunmin-common (Common Utilities)"]:::common
    Common -->|intercepts| AuthController
    Common -->|provides JWT| AuthService

    %% Click Events for Component Mapping
    click AuthController "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-api/src/main/kotlin/com/api/auth/in/AuthController.kt"
    click CategoryController "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-api/src/main/kotlin/com/api/category/in/CategoryController.kt"
    click TodayIssueController "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-api/src/main/kotlin/com/api/todayissue/in/TodayIssueController.kt"
    click DTOs "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-api/src/main/kotlin/com/api/auth/in/request"
    click DTOs "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-api/src/main/kotlin/com/api/auth/in/response"
    click DTOs "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-api/src/main/kotlin/com/api/category/in/request"
    click DTOs "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-api/src/main/kotlin/com/api/category/in/response"
    click DTOs "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-api/src/main/kotlin/com/api/todayissue/in/response"
    click GlobalConfig "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-api/src/main/kotlin/com/api/global/config/SwaggerConfig.kt"
    click GlobalConfig "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-api/src/main/kotlin/com/api/global/config/AuthConfig.kt"
    click GlobalConfig "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-api/src/main/kotlin/com/api/global/exceptions/GlobalExceptionAdvice.kt"
    click AuthService "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-application/src/main/kotlin/com/application/auth/AuthService.kt"
    click CategoryService "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-application/src/main/kotlin/com/application/category/CategoryService.kt"
    click TodayIssueService "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-application/src/main/kotlin/com/application/todayissue/TodayIssueService.kt"
    click DomainEventInterceptor "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-application/src/main/kotlin/com/application/interceptor/DomainEventInterceptor.kt"
    click AuthEntity "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-domain/src/main/kotlin/com/domain/auth/Auth.kt"
    click CategoryEntity "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-domain/src/main/kotlin/com/domain/category/Category.kt"
    click TodayIssueEntity "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-domain/src/main/kotlin/com/domain/todayissue/TodayIssue.kt"
    click TodayIssuesEntity "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-domain/src/main/kotlin/com/domain/todayissue/TodayIssues.kt"
    click DomainLayer "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-domain/src/main/kotlin/com/domain"
    click UseCasePorts "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-domain/src/main/kotlin/com/domain/**/port/in"
    click OutboundPorts "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-domain/src/main/kotlin/com/domain/**/port/out"
    click JPAEntities "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-persistence/src/main/kotlin/com/persistence"
    click AuthRepoAdapter "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-adapter/src/main/kotlin/com/adapter/AuthRepositoryAdapter.kt"
    click PasswordEncryptAdapter "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-adapter/src/main/kotlin/com/adapter/SecurityPasswordEncryptAdapter.kt"
    click AdapterConfig "https://github.com/hunmin-dev/hunmin-backend/blob/develop/hunmin-adapter/src/main/kotlin/com/adapter/AdapterConfig.kt"
    click Common "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-common/src/main/kotlin/com/common/global"
    click Database "https://github.com/hunmin-dev/hunmin-backend/tree/develop/hunmin-persistence/src/main/kotlin/com/persistence"
    
    %% Styles
    classDef external fill:#e1f5fe,stroke:#0288d1,color:#000
    classDef api fill:#bbdefb,stroke:#0d47a1,color:#000
    classDef app fill:#c8e6c9,stroke:#2e7d32,color:#000
    classDef domain fill:#fff9c4,stroke:#f9a825,color:#000
    classDef adapter fill:#ffe0b2,stroke:#ef6c00,color:#000
    classDef persist fill:#eceff1,stroke:#455a64,color:#000
    classDef db fill:#cfd8dc,stroke:#37474f,color:#000,shape:cylinder
    classDef batch fill:#e1bee7,stroke:#6a1b9a,color:#000
    classDef common fill:#f5f5f5,stroke:#9e9e9e,color:#000
```
