# bellwin98/be-pinup architecture

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

- Interactive diagram: https://gitdiagram.com/bellwin98/be-pinup
- Repository: https://github.com/bellwin98/be-pinup

## Overview

##### Project type and purpose
- This is a Java Spring Boot–based RESTful backend for “PIN UP,” a map-centric private social network. It exposes HTTP APIs for a frontend/mobile client, handles authentication (OAuth2 + JWT + Redis), stores domain data (places, reviews, bookmarks, friends, alarms), and integrates with external services (Kakao Map API, OAuth providers, AWS S3).

##### File structure
- Top-level artifacts:
- Dockerfile, docker-compose.yml, GitHub workflows → containerization & CI/CD
- build.gradle, gradlew → Gradle build
- src/main/java/com/pinup: layered by domain feature (alarm, article, bookmark, friend, home, member, place, review) plus global/config/exception/response.
- src/main/resources/application.yml, data.sql → DB & infra config
- src/test → unit tests for core domains
- Architectural patterns:
- Layered MVC-style (Controller → Service → Repository → Entity)
- External integration modules under global/config (Kakao, S3, Redis, JWT)
- SSE for real-time alarms
- QueryDSL for advanced queries

##### Key insights from README
- Uses: MariaDB (primary RDBMS), Redis (caching & token store), AWS S3 (image storage), Kakao Map API (place lookup), OAuth2 social login, Swagger for docs.
- CI/CD: Docker, GitHub Actions → automated build & deploy

##### Essential architectural elements to capture
- Authentication & token flow (OAuth2 → JWT → Redis)
- Lookup & clustering logic (Kakao → DB → QueryDSL)
- Notification pipeline (Service → SSE emitter → Client)
- Image storage flow (Client → API → S3 → DB)
- Data persistence boundaries (JPA → MariaDB; Redis as cache & store)
- DevOps pipeline (GitHub Actions → Docker image → Deployment)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        WebMobile["Web/Mobile Client"]:::client
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        AlarmCtrl["AlarmController"]:::api
        NotificationCtrl["NotificationController (SSE)"]:::api
        ArticleCtrl["ArticleController"]:::api
        BookmarkCtrl["BookMarkController"]:::api
        FriendReqCtrl["FriendRequestController"]:::api
        FriendShipCtrl["FriendShipController"]:::api
        HomeCtrl["HomeController"]:::api
        AuthCtrl["AuthController"]:::api
        MemberCtrl["MemberController"]:::api
        PlaceCtrl["PlaceController"]:::api
        ReviewCtrl["ReviewController"]:::api
    end

    %% Services Layer
    subgraph "Service Layer" 
        direction TB
        AuthService["AuthService"]:::service
        JwtFilter["JwtTokenFilter/Provider"]:::service
        RedisSvc["RedisService/Config"]:::service
        SecurityCfg["SecurityConfig"]:::service

        AlarmSvc["AlarmService"]:::service
        NotificationSvc["NotificationService"]:::service
        ArticleSvc["ArticleService"]:::service
        BookmarkSvc["BookMarkService"]:::service
        FriendReqSvc["FriendRequestService"]:::service
        FriendShipSvc["FriendShipService"]:::service
        MemberSvc["MemberService"]:::service
        PlaceSvc["PlaceService"]:::service
        ClusteringSvc["PlaceClusteringService"]:::service
        ReviewSvc["ReviewService"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence" 
        direction TB
        MariaDB[(MariaDB)]:::database
        RedisCache[(Redis Cache & Token Store)]:::database
        JPARepo["JPA Repositories"]:::database
        QueryDslCfg["QueryDslConfig"]:::database
        QueryDslRepo["QueryDsl Repositories"]:::database
        EmitterRepo["EmitterRepository/EventCacheRepository"]:::database
    end

    %% External Integrations
    subgraph "External Services" 
        direction TB
        KakaoAPI["Kakao Map API"]:::external
        OAuthProviders["OAuth2 Providers"]:::external
        S3["AWS S3"]:::external
        Swagger["Swagger Docs"]:::external
    end

    %% CI/CD & Infra
    subgraph "CI/CD & Infra" 
        direction TB
        GitHubActions["GitHub Actions"]:::infra
        DockerImage["Docker / Docker Compose"]:::infra
        AppConfig["application.yml / data.sql"]:::infra
    end

    %% Connections
    WebMobile -->|"HTTPS Request"| AlarmCtrl
    WebMobile --> NotificationCtrl
    WebMobile --> ArticleCtrl
    WebMobile --> BookmarkCtrl
    WebMobile --> FriendReqCtrl
    WebMobile --> FriendShipCtrl
    WebMobile --> HomeCtrl
    WebMobile --> AuthCtrl
    WebMobile --> MemberCtrl
    WebMobile --> PlaceCtrl
    WebMobile --> ReviewCtrl

    AlarmCtrl --> AlarmSvc
    NotificationCtrl --> NotificationSvc
    ArticleCtrl --> ArticleSvc
    BookmarkCtrl --> BookmarkSvc
    FriendReqCtrl --> FriendReqSvc
    FriendShipCtrl --> FriendShipSvc
    HomeCtrl --> MemberSvc
    AuthCtrl --> AuthService
    MemberCtrl --> MemberSvc
    PlaceCtrl --> PlaceSvc
    ReviewCtrl --> ReviewSvc

    AuthService --> JwtFilter
    AuthService --> RedisSvc
    AuthService --> SecurityCfg

    AlarmSvc --> EmitterRepo
    NotificationSvc --> EmitterRepo

    ArticleSvc --> JPARepo
    BookmarkSvc --> JPARepo
    FriendReqSvc --> JPARepo
    FriendShipSvc --> JPARepo
    MemberSvc --> JPARepo
    PlaceSvc --> JPARepo
    ReviewSvc --> JPARepo

    JPARepo --> MariaDB
    QueryDslCfg --> QueryDslRepo
    QueryDslRepo --> MariaDB
    RedisSvc --> RedisCache

    PlaceSvc -->|"Lookup"| KakaoAPI
    PlaceSvc --> QueryDslRepo
    ClusteringSvc --> QueryDslRepo

    AuthService --> OAuthProviders
    ArticleSvc --> S3
    BookmarkSvc --> S3

    Swagger --> AuthCtrl

    GitHubActions --> DockerImage
    DockerImage --> AppConfig

    %% Click Events
    click AlarmCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/alarm/controller/AlarmController.java"
    click NotificationCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/alarm/controller/NotificationController.java"
    click ArticleCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/article/controller/ArticleController.java"
    click BookmarkCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/bookmark/controller/BookMarkController.java"
    click FriendReqCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/friend/controller/FriendRequestController.java"
    click FriendShipCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/friend/controller/FriendShipController.java"
    click HomeCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/home/HomeController.java"
    click AuthCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/member/controller/AuthController.java"
    click MemberCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/member/controller/MemberController.java"
    click PlaceCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/place/controller/PlaceController.java"
    click ReviewCtrl "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/review/controller/ReviewController.java"

    click AuthService "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/member/service/AuthService.java"
    click JwtFilter "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/jwt/JwtTokenFilter.java"
    click JwtFilter "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/jwt/JwtTokenProvider.java"
    click RedisSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/redis/RedisService.java"
    click RedisSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/redis/RedisConfig.java"
    click SecurityCfg "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/security/SecurityConfig.java"

    click AlarmSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/alarm/service/AlarmService.java"
    click NotificationSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/alarm/service/NotificationService.java"
    click ArticleSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/article/service/ArticleService.java"
    click BookmarkSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/bookmark/service/BookMarkService.java"
    click FriendReqSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/friend/service/FriendRequestService.java"
    click FriendShipSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/friend/service/FriendShipService.java"
    click MemberSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/member/service/MemberService.java"
    click PlaceSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/place/service/PlaceService.java"
    click ClusteringSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/place/service/PlaceClusteringService.java"
    click ReviewSvc "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/review/service/ReviewService.java"

    click QueryDslCfg "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/querydsl/QueryDslConfig.java"
    click QueryDslRepo "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/bookmark/repository/querydsl/BookMarkRepositoryQueryDslImpl.java"
    click QueryDslRepo "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/place/repository/querydsl/PlaceRepositoryQueryDslImpl.java"
    click EmitterRepo "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/alarm/repository/EmitterRepository.java"
    click EmitterRepo "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/domain/alarm/repository/EventCacheRepository.java"

    click KakaoAPI "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/kakao/KakaoMapModule.java"
    click S3 "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/s3/S3Config.java"
    click S3 "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/s3/S3Service.java"
    click Swagger "https://github.com/bellwin98/be-pinup/blob/dev/src/main/java/com/pinup/global/config/swagger/SwaggerConfig.java"

    click GitHubActions "https://github.com/bellwin98/be-pinup/blob/dev/.github/workflows/deploy.yml"
    click DockerImage "https://github.com/bellwin98/be-pinup/blob/dev/docker-compose.yml"
    click AppConfig "https://github.com/bellwin98/be-pinup/blob/dev/src/main/resources/application.yml"
    click AppConfig "https://github.com/bellwin98/be-pinup/blob/dev/src/main/resources/data.sql"

    %% Styles
    classDef client fill:#E8F0FE,stroke:#1E88E5,color:#1E88E5;
    classDef api fill:#BBDEFB,stroke:#1976D2,color:#1976D2;
    classDef service fill:#C8E6C9,stroke:#388E3C,color:#388E3C;
    classDef database fill:#E0F7FA,stroke:#00838F,color:#00838F;
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#F57C00;
    classDef infra fill:#ECEFF1,stroke:#546E7A,color:#546E7A;
```
