# pp8817/chukchuk-haksa_server architecture

> Architecture diagram of the GitHub repository pp8817/chukchuk-haksa_server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pp8817/chukchuk-haksa_server
- Repository: https://github.com/pp8817/chukchuk-haksa_server

## Overview

The 척척학사 Backend project is clearly designed as a Spring Boot-based back-end service that supports a student academic management system. Its purpose is to let students check, compare, and manage their academic records (such as credits, course records, graduation requirements) by connecting with the school portal and synchronizing academic data in real time. The ELK configuration files hint at built-in logging and monitoring support (using Elasticsearch, Logstash, and Kibana), which further refines the backend’s operational observability.

##### Main Components
- Application Server: Represent the Spring Boot application (entry point is ChukchukHaksaApplication.java) which handles all business logic.
- API Layer (Controllers): Several controllers reside in the “domain” packages such as AcademicRecordController, GraduationController, StudentController, UserController, etc. These controllers manage incoming REST API requests.
- Service Layer (Application & Domain Services): Each domain has its associated service classes (e.g., DashboardService, AcademicRecordService, GraduationService, StudentService, etc.) that encapsulate business logic.
- Persistence Layer (Repositories): The repository interfaces (e.g., StudentRepository, SemesterAcademicRecordRepository, etc.) implement data access for the various domain models.
- Domain Models: There is a rich set of domain objects (entities like Student, Course, Department, GraduationRequirement, etc.) that are the core of the business logic.
- Security Components: Contains security configuration (SecurityConfig, JwtAuthenticationFilter, CustomUserDetails, etc.) to manage authentication and authorization.
- Global Configurations & Exception Handling: Classes for configuration (OpenApiConfig, logging via logback.xml) and global exception handling.
- External Integrations & Infrastructure:
- The project integrates with external systems such as the school’s academic portal for real-time synchronization of academic data.
- ELK Stack Components (via elk-config folder): These are deployed using Docker (docker-compose.yml, multiple Dockerfiles for Elasticsearch, Kibana, and Logstash) to handle logging and monitoring.
- Swagger API docs via the swagger.json and swagger.yaml files provide interactive API documentation.

##### Relationships and Interactions
- The REST controllers receive requests from clients (e.g., front-end applications or external systems) and invoke methods in the Service layer.
- Service layers then orchestrate domain logic and call repository interfaces to persist or retrieve data from a relational database (database details, while not directly visible, are assumed to be managed in configuration files external to the provided tree).
- Security filters and configurations sit at the API entry points to secure and authorize incoming requests before they reach the business logic.
- Global configurations (including OpenAPI settings) help expose the API documentation for client developers.
- Simultaneously, the ELK stack containers process and display log data generated by the application to monitor operations and diagnose issues.

##### Architectural Patterns and Design Principles
- Layered Architecture: The project is structured into clear layers – controllers (presentation/API), services (business logic), repositories (persistence), and domain models – following the standard Spring Boot application design.
- Domain-Driven Design (DDD): The domain packages (academic, course, student, graduation, professor, user, etc.) indicate that business concerns are modularized based on domain concepts.
- Security & Exception Handling: Dedicated components for global exception handling and security ensure that cross-cutting concerns are isolated.
- Containerization for Monitoring and Logging: The ELK configuration uses Docker to containerize the logging components.

##### Detailing Essential Architectural Elements
- The underlying Gradle-based build and configuration management (you may note that the project is built with Gradle).
- The division between business functionalities (academic records, graduation, student, etc.) and cross-cutting concerns (security, logging, API documentation).
- The role of Dockerized services in the ELK stack to provide logging and monitoring support.

## Diagram (Mermaid)

```mermaid
graph TD
    client["External Clients"]:::external
    app["Application Server"]:::application
    client -->|"sends request"| app

    subgraph "API Layer"
        ctrl1["AcademicRecordController"]:::controller
        ctrl2["GraduationController"]:::controller
        ctrl3["StudentController"]:::controller
        ctrl4["UserController"]:::controller
        ctrl5["DashboardController"]:::controller
    end

    subgraph "Service Layer"
        svc1["DashboardService"]:::service
        svc2["AcademicRecordService"]:::service
        svc3["SemesterAcademicRecordService"]:::service
        svc4["StudentAcademicRecordService"]:::service
        svc5["StudentCourseService"]:::service
        svc6["GraduationService"]:::service
        svc7["StudentService"]:::service
        svc8["UserService"]:::service
    end

    subgraph "Persistence Layer"
        repo1["SemesterAcademicRecordRepository"]:::repository
        repo2["StudentAcademicRecordRepository"]:::repository
        repo3["StudentCourseRepository"]:::repository
        repo4["GraduationQueryRepository"]:::repository
        repo5["StudentRepository"]:::repository
        repo6["UserRepository"]:::repository
    end

    subgraph "Domain Models"
        dm1["Academic Models"]:::domain
        dm2["Course Models"]:::domain
        dm3["Department Models"]:::domain
        dm4["Graduation Models"]:::domain
        dm5["Professor Models"]:::domain
        dm6["Student Models"]:::domain
        dm7["User Model"]:::domain
    end

    subgraph "Security Components"
        sec1["SecurityConfig"]:::security
        sec2["JwtAuthenticationFilter"]:::security
        sec3["CustomUserDetails"]:::security
        sec4["CustomUserDetailsService"]:::security
        sec5["Additional Security Services"]:::security
    end

    subgraph "Global Configuration"
        conf1["OpenApiConfig"]:::config
        conf2["Global Exception Handling"]:::config
        conf3["logback.xml"]:::config
    end

    subgraph "External Integrations"
        ext1["School Portal Sync"]:::external
        ext2["ELK Stack"]:::external
        ext3["Swagger API Docs"]:::external
    end

    %% Connections from Application Server to API Layer
    app -->|"routes to"| ctrl1
    app -->|"routes to"| ctrl2
    app -->|"routes to"| ctrl3
    app -->|"routes to"| ctrl4
    app -->|"routes to"| ctrl5

    %% API Controllers calling corresponding Services
    ctrl1 -->|"calls"| svc2
    ctrl2 -->|"calls"| svc6
    ctrl3 -->|"calls"| svc7
    ctrl4 -->|"calls"| svc8
    ctrl5 -->|"calls"| svc1

    %% Services interacting with Persistence Layer
    svc2 -->|"queries"| repo1
    svc4 -->|"queries"| repo2
    svc5 -->|"queries"| repo3
    svc6 -->|"queries"| repo4
    svc7 -->|"queries"| repo5
    svc8 -->|"queries"| repo6

    %% Persistence Layer mapping to Domain Models
    repo1 -->|"maps"| dm1
    repo2 -->|"maps"| dm1
    repo3 -->|"maps"| dm1
    repo4 -->|"maps"| dm4
    repo5 -->|"maps"| dm6
    repo6 -->|"maps"| dm7

    %% Services using Domain Models
    svc2 -->|"uses"| dm1
    svc4 -->|"uses"| dm1
    svc5 -->|"uses"| dm1
    svc6 -->|"uses"| dm4
    svc7 -->|"uses"| dm6
    svc8 -->|"uses"| dm7

    %% Security Components securing API Layer
    sec1 ---|"secures"| ctrl1
    sec1 ---|"secures"| ctrl2
    sec1 ---|"secures"| ctrl3
    sec1 ---|"secures"| ctrl4
    sec1 ---|"secures"| ctrl5

    %% Global Configuration interactions
    conf1 -->|"exposes"| ext3
    app -->|"handled by"| conf2
    conf3 -->|"logs to"| ext2

    %% External Integrations interactions
    svc2 -->|"syncs"| ext1
    svc7 -->|"syncs"| ext1
    app -->|"sends logs"| ext2

    %% Click Events
    click app "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/ChukchukHaksaApplication.java"
    click ctrl1 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/controller/AcademicRecordController.java"
    click ctrl2 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/graduation/controller/GraduationController.java"
    click ctrl3 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/student/controller/StudentController.java"
    click ctrl4 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/user/controller/UserController.java"
    click ctrl5 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/application/dashboard/DashboardController.java"
    
    click svc1 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/application/dashboard/DashboardService.java"
    click svc2 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/service/AcademicRecordService.java"
    click svc3 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/service/SemesterAcademicRecordService.java"
    click svc4 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/service/StudentAcademicRecordService.java"
    click svc5 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/service/StudentCourseService.java"
    click svc6 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/graduation/service/GraduationService.java"
    click svc7 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/student/service/StudentService.java"
    click svc8 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/user/service/UserService.java"
    
    click repo1 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/repository/SemesterAcademicRecordRepository.java"
    click repo2 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/repository/StudentAcademicRecordRepository.java"
    click repo3 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/academic/record/repository/StudentCourseRepository.java"
    click repo4 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/graduation/repository/GraduationQueryRepository.java"
    click repo5 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/student/repository/StudentRepository.java"
    click repo6 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/user/repository/UserRepository.java"
    
    click dm1 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/domain/academic/record/model/"
    click dm2 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/domain/course/model/"
    click dm3 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/domain/department/model/"
    click dm4 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/domain/graduation/model/"
    click dm5 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/domain/professor/model/"
    click dm6 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/domain/student/model/"
    click dm7 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/domain/user/model/User.java"
    
    click sec1 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/global/security/SecurityConfig.java"
    click sec2 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/global/security/filter/JwtAuthenticationFilter.java"
    click sec3 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/global/security/CustomUserDetails.java"
    click sec4 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/global/security/service/CustomUserDetailsService.java"
    click sec5 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/global/security/service/"
    
    click conf1 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/java/com/chukchuk/haksa/global/config/OpenApiConfig.java"
    click conf2 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/global/exception/"
    click conf3 "https://github.com/pp8817/chukchuk-haksa_server/blob/main/src/main/resources/logback.xml"
    
    click ext2 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/elk-config/"
    click ext3 "https://github.com/pp8817/chukchuk-haksa_server/tree/main/src/main/java/com/chukchuk/haksa/global/swagger/"

    %% Styles
    classDef application fill:#fcd5b4,stroke:#333,stroke-width:2px;
    classDef controller fill:#d1e8ff,stroke:#333,stroke-width:2px;
    classDef service fill:#d4f5d4,stroke:#333,stroke-width:2px;
    classDef repository fill:#f9d6d5,stroke:#333,stroke-width:2px;
    classDef domain fill:#ffe2c1,stroke:#333,stroke-width:2px;
    classDef security fill:#e8d1ff,stroke:#333,stroke-width:2px;
    classDef config fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#c1f0ff,stroke:#333,stroke-width:2px;
```
