# jjinbbang-web/jjinbbang_be architecture

> Architecture diagram of the GitHub repository jjinbbang-web/jjinbbang_be, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jjinbbang-web/jjinbbang_be
- Repository: https://github.com/jjinbbang-web/jjinbbang_be

## Overview

##### Project Type and Purpose
- From the file structure and minimal README (“GipNU_BE”), it’s clear this is a Spring Boot–based backend service (no separate “frontend” folder).
- It’s a modular monolith serving APIs for domains like Building, User, Map, and Common (reports, campuses, universities), plus global cross-cutting concerns (JWT auth, mailing, OCR, OpenAI, Slack, Google Sheets).

##### High-Level File Structure Analysis
- src/main/java/JJinBBang/app/domain/* : Four main bounded contexts—building, common, map, user—each with its own controller, service, repository, DTOs, entities, exceptions.
- src/main/java/JJinBBang/app/global/* : Cross-cutting modules—security, JWT, mail, OCR, OpenAI, Slack, Google Sheets, error handling, template responses, configuration classes.
- Configuration & infra: application.yml, S3Config, RedisConfig, QuerydslConfig, external-client wrappers (VWorldApiClientImpl).
- Persistence: Spring Data JPA repositories, QueryDSL custom repos, multiple Redis/In-Memory implementations for tokens and pending users.
- Testing: JUnit tests in src/test.

##### Key Architectural Patterns
- Layered architecture (Controllers → Services → Repositories → Database).
- Modular packaging by feature/domain (bounded contexts).
- External API clients abstracted behind interfaces (e.g., VWorldApiClient, OcrService, MailSendService).
- Cross-cutting concerns centralized under “global” (security filters, exception handlers, JWT, mail, OCR, OpenAI, Slack).
- Use of Spring’s dependency injection, configuration classes, and properties for external services.

A. External Clients & Services
- VWorld Map API
- OAuth2 providers (Google, Kakao, Naver)
- AWS S3 (for file uploads via S3Service)
- SMTP mail server (MailSendService)
- OCR provider (Clova OCR)
- OpenAI Verification API
- Google Sheets & Slack endpoints
B. Authentication & Security
- JWT generation & verification (JwtService, RefreshTokenRepository, JwtAuthenticationFilter)
- OAuth2 flow (CustomOAuth2UserService, AuthController)
- Security filters / handlers (VerificationStatusFilter, CustomAccessDeniedHandler)
C. API Layer
- HTTP entry points: Controllers in each domain (BuildingController, UsersController, MapController, CampusesController, etc.)
D. Business Logic Layer
- Services per domain (BuildingServiceImpl, UsersServiceImpl, MapServiceImpl, CampusesServiceImpl, etc.)
- Cross-cutting services (MailAuthService, OcrService, OpenaiVerificationService, SlackService, GoogleSheetsService)
E. Data Layer
- Spring Data JPA Repositories (e.g., BuildingsRepository, UsersRepository, ReportRepository)
- Custom QueryDSL repositories for complex queries
- Redis/In-Memory stores for pending users, email codes, refresh tokens
- Primary relational database (e.g., PostgreSQL or MySQL instance)

##### Relationships and Data Flow
1. HTTP requests → Security Filter Chain (JWT + OAuth2) → Controller
2. Controller invokes Service → Service may:
- Talk to Repository → Database
- Call external client bean → External API
- Publish or listen to application events (e.g., CertificateUploadEvent)
- Interact with Redis/In-Memory caches
3. Service returns DTO → Controller wraps in ResTemplate → HTTP response
4. Global exception handler (ControllerAdvice) intercepts and formats errors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    A("Browser/Mobile"):::external
    B("API Gateway / Load Balancer"):::external
    A --> B

    subgraph "Application Monolith"
        direction TB

        subgraph "API Layer"
            direction TB
            AuthController["AuthController"]:::controller
            BuildingController["BuildingController"]:::controller
            UsersController["UsersController"]:::controller
            MapController["MapController"]:::controller
            CampusesController["CampusesController"]:::controller
            UniversityController["UniversityController"]:::controller
            ReportController["ReportController"]:::controller
        end

        subgraph "Service Layer"
            direction TB
            BuildingService["BuildingServiceImpl"]:::service
            BookmarkService["BookmarkServiceImpl"]:::service
            ReviewService["ReviewServiceImpl"]:::service
            UsersService["UsersServiceImpl"]:::service
            MapService["MapServiceImpl"]:::service
            CampusesService["CampusesServiceImpl"]:::service

            MailAuthService["MailAuthService"]:::service
            MailSendService["MailSendService"]:::service
            OcrService["OcrService"]:::service
            OpenaiVerificationService["OpenaiVerificationService"]:::service
            GoogleSheetsService["GoogleSheetsService"]:::service
            SlackService["SlackService"]:::service

            JwtService["JwtService"]:::service
            JwtAuthFilter["JwtAuthenticationFilter"]:::service
            CustomOAuth2UserService["CustomOAuth2UserService"]:::service
        end

        subgraph "Data Layer"
            direction TB
            BuildingsRepo["BuildingsRepository"]:::repo
            UsersRepo["UsersRepository"]:::repo
            CampusesRepo["CampusesRepository"]:::repo
            ReportRepo["ReportRepository"]:::repo

            RefreshTokenRepo["RefreshTokenRepository"]:::repo
            RedisPendingUserRepo["RedisPendingUserRepository"]:::repo
            InMemoryPendingUserRepo["InMemoryPendingUserRepository"]:::repo
            EmailAuthCodeRepo["RedisEmailAuthCodeRepository"]:::repo
        end

        %% Flows within Application
        B --> AuthController
        B --> BuildingController
        B --> UsersController
        B --> MapController
        B --> CampusesController
        B --> UniversityController
        B --> ReportController

        AuthController -->|"calls"| JwtService
        AuthController -->|"calls"| CustomOAuth2UserService
        AuthController -->|"calls"| UsersService

        BuildingController -->|"calls"| BuildingService
        BuildingController -->|"calls"| BookmarkService
        BuildingController -->|"calls"| ReviewService

        UsersController -->|"calls"| UsersService
        MapController -->|"calls"| MapService
        CampusesController -->|"calls"| CampusesService
        UniversityController -->|"calls"| CampusesService
        ReportController -->|"calls"| CampusesService

        JwtService -->|"stores tokens"| RefreshTokenRepo
        JwtAuthFilter -->|"validates JWT"| JwtService

        BuildingService -->|"queries"| BuildingsRepo
        BookmarkService -->|"queries"| BuildingsRepo
        ReviewService -->|"queries"| BuildingsRepo
        UsersService -->|"queries"| UsersRepo
        CampusesService -->|"queries"| CampusesRepo
        CampusesService -->|"queries"| ReportRepo

        UsersService -->|"uses"| RedisPendingUserRepo
        UsersService -->|"uses"| InMemoryPendingUserRepo

        MailAuthService -->|"uses"| EmailAuthCodeRepo
        MailSendService -->|"connects to"| SMTPServer["SMTP Mail Server"]:::external
        OcrService -->|"calls"| OCRProvider["Clova OCR"]:::external
        OpenaiVerificationService -->|"calls"| OpenAIAPI["OpenAI Verification API"]:::external
        GoogleSheetsService -->|"calls"| SheetsAPI["Google Sheets API"]:::external
        SlackService -->|"calls"| SlackAPI["Slack API"]:::external

        BuildingService -->|"calls"| VWorldAPI["VWorld Map API"]:::external

        subgraph "External Configurations"
            direction TB
            S3Config["S3Config"]:::config
            RedisConfig["RedisConfig"]:::config
            QuerydslConfig["QuerydslConfig"]:::config
        end

        %% Click Events
        click BuildingController "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/building/controller/BuildingController.java"
        click UsersController "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/user/controller/UsersController.java"
        click MapController "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/map/controller/MapController.java"
        click CampusesController "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/common/controller/CampusesController.java"
        click UniversityController "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/common/controller/UniversityController.java"
        click ReportController "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/common/controller/ReportController.java"
        click AuthController "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/user/controller/AuthController.java"

        click VWorldAPI "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/building/infra/VWorldApiClient.java"
        click S3Config "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/domain/common/config/S3Config.java"
        click MailSendService "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/mail/service/MailSendService.java"
        click MailAuthService "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/mail/service/MailAuthService.java"
        click OcrService "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/ocr/service/OcrService.java"
        click OpenaiVerificationService "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/openai/service/OpenaiVerificationService.java"
        click GoogleSheetsService "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/sheets/service/GoogleSheetsService.java"
        click SlackService "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/slack/service/SlackService.java"
        click JwtAuthFilter "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/jwt/JwtAuthenticationFilter.java"
        click JwtService "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/jwt/service/JwtService.java"
        click RefreshTokenRepo "https://github.com/jjinbbang-web/jjinbbang_be/blob/develop/src/main/java/JJinBBang/app/global/jwt/repository/RefreshTokenRepository.java"

    end

    %% Databases
    subgraph "External Data Stores"
        direction TB
        PrimaryDB["Primary Relational DB"]:::db
        RedisCluster["Redis Cluster"]:::db
    end

    BuildingsRepo --> PrimaryDB
    UsersRepo --> PrimaryDB
    CampusesRepo --> PrimaryDB
    ReportRepo --> PrimaryDB
    RefreshTokenRepo --> RedisCluster
    RedisPendingUserRepo --> RedisCluster
    EmailAuthCodeRepo --> RedisCluster

    %% Class Definitions
    classDef controller fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef service fill:#90EE90,stroke:#000,stroke-width:1px
    classDef repo fill:#FFD580,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef db fill:#FFFACD,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#FFE4B5,stroke:#000,stroke-width:1px
```
