# cow-dev/ddingdong-fe architecture

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

- Interactive diagram: https://gitdiagram.com/cow-dev/ddingdong-fe
- Repository: https://github.com/cow-dev/ddingdong-fe

## Overview

##### Project type and purpose
- This is a full‑stack web application built with Next.js v13 (TypeScript).
- Its goal is to provide a unified “club platform” for students (public site) and club administrators (admin portal), consuming backend REST APIs for data.

##### Core components and layers
a. Client layer
- Web browsers (students & admins) interacting with the Next.js app.
- Next.js handles SSR/SSG, client‑side routing, and hydration.

b. Presentation layer (Next.js frontend)
- pages/…: Defines public routes (`/`, `/club/[id]`, `/apply/[id]`, `/notice`, etc.) and admin routes (`/admin/**`).
- components/: Reusable UI pieces (common, club, apply, feed, fixzone, report, score, modals, etc.).
- styles/, public/: Static assets, global CSS, JSON animations.

c. Application logic
- src/apis/index.ts: Centralized API client (fetch wrappers, presigned‑URL logic).
- src/hooks/api/*: Custom React hooks (e.g., useAllClubs, useNewReport) encapsulating fetch/mutation logic per resource.
- src/hooks/common: Utilities for modals, SSE subscriptions, form handling.
- src/store: Zustand stores for auth, club context, uploads.
- middleware.ts: Edge middleware for auth checks and route protection.
- next.config.js, tsconfig.json, PostCSS/Tailwind configs.

d. External services
- Backend REST API(s): `/api/club`, `/api/apply`, `/api/feed`, `/api/document`, `/api/fixzone`, etc.
- Sentry: Client/Server/Edge error monitoring (sentry.*.config.ts).
- Google Analytics: gtag integration (lib/gtag.ts).
- SSE endpoint (utils/subscribeToSSE.tsx) for real‑time updates (optional).
- Object storage (S3 or similar) via presigned URLs for file/image uploads.

e. Data persistence (not in repo)
- Backend databases (likely PostgreSQL/Mongo) behind the REST API.
- File storage for uploaded documents, images.

##### Relationships and data flow
1. User → Browser
2. Browser → Next.js App (SSR/CSR)
3. Next.js App → `src/apis` → fetch → Backend REST API
4. Backend → Database / Storage → Backend → Response → Next.js → Browser
5. Sentry and Analytics capture errors & metrics throughout

##### Architectural patterns & principles
- Component‑based architecture: Separation of concerns by domain (apply, club, feed, etc.).
- Hooks for data fetching: Encapsulate API details and caching strategies.
- Middleware for cross‑cutting concerns (auth guard, redirects).
- State management via lightweight stores (Zustand).
- Static assets & CDN: `public/`, Next.js static optimization.
- Error monitoring (Sentry) and analytics (gtag) integrated at multiple layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Web Browser (Student/Admin)"]:::frontend
    end

    %% Next.js Application
    subgraph "Next.js App" 
        direction TB
        NextServer["Next.js Server (SSR/CSR)"]:::frontend
        subgraph "Presentation Layer"
            direction TB
            Pages["Pages (Public & Admin)"]:::frontend
            Components["UI Components"]:::frontend
            Styles["Styles & Static Assets"]:::frontend
            PublicAssets["Public Assets"]:::frontend
        end
        subgraph "Application Logic"
            direction TB
            APIClient["API Client (fetch wrappers)"]:::frontend
            HooksAPI["Resource Hooks"]:::frontend
            HooksCommon["Common Hooks"]:::frontend
            Store["Zustand Stores"]:::frontend
            Middleware["Edge Middleware (Auth/Route Guard)"]:::frontend
        end
    end

    %% Backend Services
    subgraph "Backend Services" 
        RESTAPI["REST API Endpoints"]:::api
    end

    %% Data Stores
    subgraph "Data Persistence"
        direction TB
        DB["Database (Postgres/Mongo)"]:::database
        Storage["Object Storage (S3)"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Sentry["Sentry (Error Monitoring)"]:::external
        Analytics["Google Analytics (gtag)"]:::external
        SSE["SSE Endpoint"]:::external
    end

    %% Data Flow
    Browser -->|"Request (SSR/CSR)"| NextServer
    NextServer -->|"/api calls"| APIClient
    APIClient -->|HTTP| RESTAPI
    RESTAPI -->|Reads/Writes| DB
    RESTAPI -->|Presigned URL| Storage
    RESTAPI -->|SSE Stream| SSE
    Browser -->|SSE Stream| SSE
    Browser -->|gtag Events| Analytics
    NextServer -->|Error Logs| Sentry
    Browser -->|Error Logs| Sentry

    %% Subgraph Connections
    NextServer --> Pages
    NextServer --> Components
    NextServer --> Styles
    NextServer --> PublicAssets
    NextServer --> APIClient
    NextServer --> HooksAPI
    NextServer --> HooksCommon
    NextServer --> Store
    NextServer --> Middleware

    %% Click Events
    click Pages "https://github.com/cow-dev/ddingdong-fe/tree/main/src/pages/"
    click Components "https://github.com/cow-dev/ddingdong-fe/tree/main/src/components/"
    click Styles "https://github.com/cow-dev/ddingdong-fe/tree/main/src/styles/"
    click PublicAssets "https://github.com/cow-dev/ddingdong-fe/tree/main/public/"
    click APIClient "https://github.com/cow-dev/ddingdong-fe/blob/main/src/apis/index.ts"
    click HooksAPI "https://github.com/cow-dev/ddingdong-fe/tree/main/src/hooks/api/"
    click HooksCommon "https://github.com/cow-dev/ddingdong-fe/tree/main/src/hooks/common/"
    click Store "https://github.com/cow-dev/ddingdong-fe/tree/main/src/store/"
    click Middleware "https://github.com/cow-dev/ddingdong-fe/blob/main/middleware.ts"
    click Analytics "https://github.com/cow-dev/ddingdong-fe/blob/main/src/lib/gtag.ts"
    click SSE "https://github.com/cow-dev/ddingdong-fe/blob/main/src/utils/subscribeToSSE.tsx"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef api fill:#E1BEE7,stroke:#4A148C,color:#4A148C
    classDef database fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef external fill:#ECEFF1,stroke:#37474F,color:#37474F
```
