# four-uncles/saramara-community-server architecture

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

- Interactive diagram: https://gitdiagram.com/four-uncles/saramara-community-server
- Repository: https://github.com/four-uncles/saramara-community-server

## Overview

##### Project type and purpose
- This is a Spring-Boot backend monolith (“사라마라 서버”) providing REST APIs for a community platform where users can post “boards,” comment, vote, and upload files.
- Key domain modules: board (게시글), comment (댓글), vote (투표), member (회원), bucket (파일 업로드).

##### File structure
- Standard Gradle/Spring-Boot layout under src/main/java/com/kakao/saramaracommunity.
- Top-level packages:
- board/… (controller, service, repository, entity, exception, DTOs)
- comment/…
- vote/…
- member/…
- bucket/… implements hexagonal pattern (controller-port, service-port, infrastructure adapters: AwsS3Uploader, MinioUploader)
- common/… (shared DTOs, base entities, global exception handler, ApiResponse, TokenDto)
- config/… (Spring beans: AWS/Minio configs, JPA, security, CORS, Swagger)
- filter/, handler/ (Spring‐Security filters & auth handlers)
- util/ (file validators)
- Infrastructure/config files: application.yml, Dockerfile, docker-compose.yml, build.gradle.

##### README for additional insights
- Confirms purpose: a backend service for “사라마라” community sharing purchase decisions.

a. Main components
- Clients (Web/Mobile)
- HTTP/API Layer: Spring-Security filters → Controllers
- Business Layer: Service interfaces & implementations
- Persistence Layer: JPA Repositories → Relational Database (e.g., PostgreSQL/MySQL)
- Object Storage: AWS S3 or Minio (selectable via config)
- Cross-cutting: GlobalExceptionHandler, DTO converters, Swagger-UI

b. Relationships & interactions
- Client → Load Balancer (if any) → API endpoint
- API calls flow through CorsConfig → SecurityConfig → custom filters → controllers
- Controller receives RequestDTO → invokes Service
- Service implements business logic, may call:
- Repositories for CRUD on Board, Comment, Vote, Member
- BucketService → ObjectStorageClient → S3/Minio
- Service returns ServiceResponse DTO → Controller maps to ResponseDTO → ApiResponse → JSON to client
- GlobalExceptionHandler captures and wraps errors into consistent error responses

c. Architectural patterns & design principles
- Layered architecture (Controller → Service → Repository)
- Hexagonal/Ports & Adapters for bucket (abstract ObjectStorageClient, two adapter implementations)
- DTO segregation by layer (API vs. business)
- Configuration via Spring beans, profiles to switch between AWS S3 & Minio
- Filters for authentication (session or JWT), custom success handler
- Usage of Swagger for API documentation

d. Technologies, frameworks & libraries
- Java + Spring-Boot + Spring-Data-JPA + Hibernate
- Object storage: AWS SDK S3, Minio
- Security: Spring-Security, custom filters
- Build: Gradle
- Containerization: Docker & docker-compose
- API docs: Springfox/Swagger
- Testing: JUnit, Mockito, integration tests (with fake & real S3/Minio), architecture tests

##### Details to capture
- GlobalExceptionHandler intercepting errors across controllers.
- Config components (e.g., JwtFilter, CorsConfig) upstream of controllers.
- Build & deploy artifacts (Docker image, docker-compose orchestrating DB + service).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        Web["Web/Mobile Clients"]:::external
    end

    Web -->|"REST API Call"| CorsConfig

    %% HTTP/API Layer
    subgraph "HTTP/API Layer"
        CorsConfig["CorsConfig"]:::cross
        SecurityConfig["SecurityConfig"]:::cross
        JwtFilter["LoginAuthenticationFilter"]:::cross
        AuthSuccess["CustomAuthenticationSuccessHandler"]:::cross
        SwaggerUI["Swagger UI"]:::cross
        GlobalException["GlobalExceptionHandler"]:::cross
    end

    CorsConfig --> SecurityConfig
    SecurityConfig --> JwtFilter
    JwtFilter --> AuthSuccess
    AuthSuccess --> BoardController
    JwtFilter --> CommentController
    JwtFilter --> VoteController
    JwtFilter --> MemberController
    JwtFilter --> BucketController
    SwaggerUI --> BoardController
    BoardController -->|"handles RequestDTO"| BoardService
    CommentController -->|"handles RequestDTO"| CommentService
    VoteController -->|"handles RequestDTO"| VoteService
    MemberController -->|"handles RequestDTO"| MemberService
    BucketController -->|"handles RequestDTO"| BucketService
    BoardController --> GlobalException
    CommentController --> GlobalException
    VoteController --> GlobalException
    MemberController --> GlobalException
    BucketController --> GlobalException

    %% Controllers
    BoardController["BoardController"]:::api
    CommentController["CommentController"]:::api
    VoteController["VoteController"]:::api
    MemberController["MemberController"]:::api
    BucketController["BucketController"]:::api

    %% Service Layer
    subgraph "Business Services"
        BoardService["BoardServiceImpl"]:::service
        CommentService["CommentServiceImpl"]:::service
        VoteService["VoteServiceImpl"]:::service
        MemberService["MemberServiceImpl"]:::service
        BucketService["BucketServiceImpl"]:::service
        ObjectStoragePort["ObjectStorageClient"]:::service
    end

    BoardService --> BoardRepository
    CommentService --> CommentRepository
    VoteService --> VoteRepository
    MemberService --> MemberRepository
    BucketService --> ObjectStoragePort
    ObjectStoragePort -->|Abstract Calls| AwsS3Adapter
    ObjectStoragePort -->|Abstract Calls| MinioAdapter

    %% Repository Layer
    BoardRepository["BoardRepository"]:::service
    CommentRepository["CommentRepository"]:::service
    VoteRepository["VoteRepository"]:::service
    MemberRepository["MemberRepository"]:::service

    BoardRepository -->|"JPA Query"| Database[(Relational DB)]:::external
    CommentRepository --> Database
    VoteRepository --> Database
    MemberRepository --> Database

    %% Object Storage Adapters
    AwsS3Adapter["AwsS3Uploader"]:::external
    MinioAdapter["MinioUploader"]:::external
    AwsS3Adapter -->|"S3 PUT/GET"| S3[(AWS S3)]:::external
    MinioAdapter -->|"Minio PUT/GET"| Minio[(Minio)]:::external

    %% Deployment & Config
    subgraph "Config & Deployment"
        AppEntry["SaramaraCommunityApplication"]:::service
        DockerImage["Docker Image"]:::external
        Compose["docker-compose"]:::external
        AppEntry --> DockerImage
        DockerImage --> Compose
        Compose --> Database
        Compose --> S3
        Compose --> Minio
    end

    %% Click Events
    click BoardController "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/board/controller/BoardController.java"
    click BoardService "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/board/service/BoardServiceImpl.java"
    click BoardRepository "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/board/repository/BoardRepository.java"
    click CommentController "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/comment/controller/CommentController.java"
    click CommentService "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/comment/service/CommentServiceImpl.java"
    click CommentRepository "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/comment/repository/CommentRepository.java"
    click VoteController "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/vote/controller/VoteController.java"
    click VoteService "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/vote/service/VoteServiceImpl.java"
    click VoteRepository "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/vote/repository/VoteRepository.java"
    click MemberController "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/member/controller/MemberController.java"
    click MemberService "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/member/service/MemberServiceImpl.java"
    click MemberRepository "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/member/repository/MemberRepository.java"
    click BucketController "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/bucket/controller/BucketController.java"
    click BucketService "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/bucket/service/BucketServiceImpl.java"
    click ObjectStoragePort "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/bucket/service/port/ObjectStorageClient.java"
    click AwsS3Adapter "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/bucket/infrastructure/AwsS3Uploader.java"
    click MinioAdapter "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/bucket/infrastructure/MinioUploader.java"
    click GlobalException "https://github.com/four-uncles/saramara-community-server/blob/main/src/main/java/com/kakao/saramaracommunity/common/exception/GlobalExceptionHandler.java"

    %% Styles
    classDef api fill:#c6e5ff,stroke:#006bb3,color:#000
    classDef service fill:#d4edda,stroke:#2e7d32,color:#000
    classDef external fill:#ffe5b4,stroke:#e65100,color:#000
    classDef cross fill:#e0e0e0,stroke:#757575,color:#000
```
