# sosow0212/2024-pop-cloud architecture

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

- Interactive diagram: https://gitdiagram.com/sosow0212/2024-pop-cloud
- Repository: https://github.com/sosow0212/2024-pop-cloud

## Overview

##### Project Type and Purpose
- This is a full-stack platform that consolidates popup store information and personal exhibition data. It provides a map-based recommendation service, authentication (via OAuth, e.g., Kakao), and is built to later integrate payment capabilities.
- The project is divided between a frontend (built with Next.js and various UI components) and a robust backend (Java, built with Gradle, split into multiple modules). The backend itself is organized into several logically separated modules – API, batch processing, common utilities, domain logic, and infrastructure.

##### Analyzing the File Structure
- Top-level directories include:
- Frontend: Contains Next.js application code (pages, components, hooks, etc.), configuration (next.config.mjs, tailwind.config.ts), and storybook setups.
- Backend: Contains multiple Gradle projects:
- pcloud-api: The main API server containing controllers, service layers, auth modules, map, show, exhibition, popups, and recommendation functionalities.
- pcloud-batch: A batch processing module to handle scheduled tasks (e.g., handling exhibition caches, popping notifications, etc.).
- pcloud-common: Shared utilities and configurations (like auth token providers, custom exceptions, event configurations).
- pcloud-domain: Contains the domain model, entity definitions, domain-specific services, and integration with persistence (repositories, query modules) for members, shows, exhibitions, popups, and recommendations.
- pcloud-infrastructure: This module holds infrastructure-related configurations such as Redis and distribution/lock management, integration with external services (S3, Slack), and exception handling for distributed environments.
- Notice that there are several directories dedicated to testing (unit and integration) and configuration files (application.yml, build.gradle, etc.), reinforcing a well-layered architecture.

##### Key Architectural Components and Their Interactions
- Frontend Component:
- Built using Next.js with a clear separation of pages, layouts, UI components, and state management (using stores and hooks).
- Communicates with backend services through defined API endpoints (e.g., authentication endpoints, map/search APIs, show addition, etc.).
- Backend API (pcloud-api):
- Acts as the main entry point for HTTP requests coming from the frontend.
- Contains controllers (handling REST endpoints), service layers (application logic like AuthService, MapQueryService, ShowQueryService, etc.), and presentation layers.
- Implements features such as OAuth authentication (with dedicated configurations and implementations for Kakao), map-based recommendations, and handling of show-related data.
- Batch Processing Module (pcloud-batch):
- Runs scheduled jobs (batch processes) to handle background tasks such as cache clearing or updating recommendations.
- Uses specific batch services and publishers to trigger events that are later processed by the API or domain layers.
- Domain and Common Modules (pcloud-domain and pcloud-common):
- Business logic and core domain models (entities like Member, Exhibition, Popups, etc.) along with rules, events, exceptions, and shared utilities.
- Infrastructure Module (pcloud-infrastructure):
- Provides integration with external services – for instance, configuring Redis caches, setting up S3 for file/image storage, managing locking and idempotency for distributed or batch tasks.
- Contains aspects and utilities for ensuring distributed locking (e.g., distribution locks) and smooth integration with external APIs.

##### Final Elements
- Labels for each component (e.g., “Frontend (Next.js)”, “API Gateway / pcloud-api”, “Domain Logic”, “Batch Processing”, “Infrastructure Integrations”).
- Annotations showing technologies used (e.g., Gradle, Spring Boot, Redis, OAuth) and key configuration points (e.g., authentication processing, external API interactions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Frontend (Next.js)"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        B["Backend API Module (pcloud-api)"]:::backend
        C["Authentication & OAuth"]:::backendAuth
        B -->|"contains"| C
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        D["Domain Layer"]:::domain
        E["Common Utilities"]:::common
        F["Infrastructure Module"]:::infrastructure
    end

    %% Batch Processing Layer
    subgraph "Batch Processing"
        G["Batch Processing Module (pcloud-batch)"]:::batch
    end

    %% External Services
    subgraph "External Services"
        H["OAuth Provider (Kakao)"]:::external
        I["Redis"]:::external
        J["S3"]:::external
        K["Slack"]:::external
    end

    %% Connections between layers
    A -->|"HTTP_API"| B
    B -->|"calls"| D
    B -->|"calls"| E
    B -->|"calls"| F
    C -->|"OAuth_flow"| H
    G -->|"updates"| D
    G -->|"integrates"| F
    F -->|"integrates"| I
    F -->|"integrates"| J
    F -->|"integrates"| K

    %% Click Events
    click A "https://github.com/sosow0212/2024-pop-cloud/tree/develop/frontend/"
    click B "https://github.com/sosow0212/2024-pop-cloud/tree/develop/backend/pcloud-api/"
    click C "https://github.com/sosow0212/2024-pop-cloud/tree/develop/backend/pcloud-api/src/main/java/com/api/auth/"
    click G "https://github.com/sosow0212/2024-pop-cloud/tree/develop/backend/pcloud-batch/"
    click E "https://github.com/sosow0212/2024-pop-cloud/tree/develop/backend/pcloud-common/"
    click D "https://github.com/sosow0212/2024-pop-cloud/tree/develop/backend/pcloud-domain/"
    click F "https://github.com/sosow0212/2024-pop-cloud/tree/develop/backend/pcloud-infrastructure/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef backendAuth fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef domain fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef common fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef batch fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef external fill:#F08080,stroke:#000,stroke-width:2px;
```
