# archan0621/seulchuksaeng_be architecture

> Architecture diagram of the GitHub repository archan0621/seulchuksaeng_be, 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/archan0621/seulchuksaeng_be
- Repository: https://github.com/archan0621/seulchuksaeng_be

## Overview

##### Project type and purpose
- This is a full-stack club-management web application, focused on backend services implemented in Spring Boot.
- Purpose: automate membership, attendance, fee management for a university soccer club.

##### Main components (to include
A. Frontend layer
- PHP web server (outside VPC) hosting HTML/JS, HighCharts for admin dashboards
B. Load-Balancer
- Nginx on its own Ubuntu instance (round-robin)
C. Backend application tier
- Two identical Spring Boot instances (Docker containers) behind the LB
- Exposed REST endpoints handled by Controllers, secured by Spring Security + JWT
D. Persistence tier
- MySQL database on its own instance
- Spring Data JPA Repositories
E. Caching
- Spring Cache (e.g., Redis or in-memory depending on config) via CacheConfig
F. Scheduler
- Spring’s @Scheduled and dynamic one-off schedulers for penalty assignment
G. Cross-cutting services
- AOP aspects (SlowResponseAspect, LogExecutionTime)
- Annotations for AdminAuthorize, UserAuthorize
H. External integrations
- Naver Map API (geo-coding, distance calculation)
- Discord Webhook (notifications)
- Slack Webhook (alerts from Prometheus)
I. Observability & monitoring
- Pinpoint APM server (transaction tracing)
- Prometheus & Grafana server (metrics collection & dashboards)

##### Relationships and data-flow
1. User (Browser)
→ requests frontend PHP → HTML/JS (HighCharts dashboards)
→ issues REST calls to api.example.com
2. Nginx Load-Balancer
→ dispatches to one of two Spring Boot backend instances
3. Spring Boot instance
a. Authentication & Authorization (JwtAuthenticationFilter → SecurityConfig → TokenProvider)
b. Controller layer (EventController, MemberController, etc.)
c. Service layer (MemberService, EventService, MemberEventService)
d. Repository layer (MemberRepository, EventRepository, MemberEventRepository)
e. Domain objects (Member, Event, Attendance, MemberEvent)
f. Scheduler tasks (PenaltyScheduler, PenaltyGrantTask)
g. AOP intercepts for logging / slow-response measurement
h. Cache reads/writes via CacheConfig
i. External HTTP calls:
- NaverMapApiProvider (to look up lat/long)
- DiscordWebhookSender (to send notifications)
4. Database
← JPA reads/writes, commit/rollback
5. Observability
- Pinpoint agent in each backend container → Pinpoint server collects traces
- Spring Boot metrics exposed → scraped by Prometheus → displayed in Grafana; alerts via Slack webhook

##### Architectural patterns & design principles
- Layered MVC (Controller → Service → Repository)
- Separation of concerns (Controllers handle HTTP, Services handle business logic, Repos handle data access)
- AOP for cross-cutting concerns (logging, performance monitoring)
- JWT stateless authentication (no session affinity)
- N-to-N relationship resolved with MemberEvent join entity
- Externalized configuration & Dockerized deployment for horizontal scaling
- Scheduled batch processing for penalties
- Single-responsibility for each micro-instance: app tier, DB, LB, monitoring

##### Diagramming recommendations
- Use clear labels for each component: e.g., “Nginx LB”, “Spring Boot App #1”, “MySQL DB”
- User → PHP Frontend → LB → App → DB
- App → Naver Map API
- App → Discord Webhook
- App’s /actuator/metrics → Prometheus → Grafana
- App’s Pinpoint agent → Pinpoint Server
- Green: User-facing/frontend
- Blue: Application tier
- Orange: Persistence
- Purple: External third-party APIs
- Gray: Monitoring & Observability
- Clouds for external services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Users and Frontend
    User["User (Browser)"]:::frontend
    PHP["PHP Web Server"]:::frontend

    %% Load Balancer
    LB["Nginx Load-Balancer\n(round-robin)"]:::app

    %% Application Tier Cluster
    subgraph "Spring Boot App Instances" 
        direction TB
        App1["Spring Boot App #1"]:::app
        App2["Spring Boot App #2"]:::app
    end

    %% Inside a Spring Boot App
    subgraph "Spring Boot App Components"
        direction TB
        Controllers["Controllers"]:::app
        Services["Service Layer"]:::app
        Repositories["Repository Layer"]:::app
        Domain["Domain Models"]:::app
        Security["Security & JWT"]:::app
        Cache["CacheConfig"]:::app
        Scheduler["Scheduling"]:::app
        AOP["AOP Aspects"]:::app
        HTTPProvider["External HTTP Providers"]:::app
    end

    %% Persistence
    DB["MySQL Database\n(3306)"]:::db

    %% External Services
    subgraph "External APIs"
        direction TB
        NaverAPI["Naver Map API"]:::ext
        Discord["Discord Webhook"]:::ext
        Slack["Slack Webhook"]:::ext
    end

    %% Observability
    subgraph "Monitoring & Observability"
        direction TB
        PinpointServer["Pinpoint APM Server"]:::monitor
        Prometheus["Prometheus"]:::monitor
        Grafana["Grafana"]:::monitor
    end

    %% Connections
    User -->|"HTTP"| PHP
    PHP -->|"REST calls to api.example.com"| LB
    LB --> App1
    LB --> App2

    App1 --> Controllers
    App1 --> Services
    App1 --> Repositories
    App1 --> Domain
    App1 --> Security
    App1 --> Cache
    App1 --> Scheduler
    App1 --> AOP
    App1 --> HTTPProvider

    Controllers --> Services
    Services --> Repositories
    Repositories --> DB
    Services --> Domain

    HTTPProvider --> NaverAPI
    HTTPProvider --> Discord

    %% Observability flows
    App1 -->|"Pinpoint agent"| PinpointServer
    App1 -->|"Metrics (actuator)"| Prometheus
    Prometheus --> Grafana
    Prometheus --> Slack

    %% Click Events - Controllers
    click Controllers "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/controller/EventController.java"
    click Controllers "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/controller/MemberController.java"
    click Controllers "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/controller/MemberEventController.java"
    click Controllers "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/controller/HomeController.java"

    %% Click Events - Services
    click Services "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/service/EventService.java"
    click Services "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/service/MemberService.java"
    click Services "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/service/MemberEventService.java"

    %% Click Events - Repositories
    click Repositories "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/repository/EventRepository.java"
    click Repositories "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/repository/MemberRepository.java"
    click Repositories "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/repository/MemberEventRepository.java"

    %% Click Events - Domain Models
    click Domain "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/domain/Member.java"
    click Domain "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/domain/Event.java"
    click Domain "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/domain/Attendance.java"
    click Domain "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/domain/MemberEvent.java"

    %% Click Events - Security
    click Security "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/security/JwtAuthenticationFilter.java"
    click Security "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/security/SecurityConfig.java"
    click Security "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/security/TokenProvider.java"
    click Security "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/security/Crypto.java"
    click Security "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/security/impl/CryptoImpl.java"
    click Security "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/security/CustomAccessDeniedHandler.java"

    %% Click Events - Cache
    click Cache "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/config/CacheConfig.java"

    %% Click Events - Scheduler
    click Scheduler "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/scheduler/PenaltyScheduler.java"
    click Scheduler "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/scheduler/PenaltyGrantTask.java"

    %% Click Events - AOP & Annotations
    click AOP "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/aop/SlowResponseAspect.java"
    click AOP "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/annotation/AdminAuthorize.java"
    click AOP "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/annotation/UserAuthorize.java"
    click AOP "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/annotation/LogExecutionTime.java"

    %% Click Events - HTTP Providers
    click HTTPProvider "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/httpProvider/NaverMapApiProvider.java"
    click HTTPProvider "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/httpProvider/resp/AddressResponse.java"
    click HTTPProvider "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/httpProvider/resp/LocationResponse.java"
    click HTTPProvider "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/httpProvider/DiscordWebhookSender.java"

    %% Click Event - Application Entry Point
    click App1 "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/SeulChukSaengWebApplication.java"
    click App2 "https://github.com/archan0621/seulchuksaeng_be/blob/main/src/main/java/kr/co/seulchuksaeng/seulchuksaengweb/SeulChukSaengWebApplication.java"

    %% Styles
    classDef frontend fill:#a2d5f2,stroke:#077b8a,color:#000;
    classDef app fill:#cfe0c3,stroke:#2f5233,color:#000;
    classDef db fill:#f7c59f,stroke:#a65f14,color:#000;
    classDef ext fill:#d3c0eb,stroke:#5a3e85,color:#000;
    classDef monitor fill:#e3e3e3,stroke:#666,color:#000;
```
