# gyumong/chukchuk-haksa architecture

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

- Interactive diagram: https://gitdiagram.com/gyumong/chukchuk-haksa
- Repository: https://github.com/gyumong/chukchuk-haksa

## Overview

##### Project Type & Purpose
- This is a full-stack application designed to help students manage and verify their academic progress and graduation requirements by syncing data directly from the school portal.
- The project integrates real-time academic data synchronization, user authentication, and data crawling from external sources (e.g., using Playwright in the suwon-scrape module).

##### File Structure
- Notice the clear separation between the frontend (in the “app” directory with various route groups like (funnel), (landing), (main), (setting)) and backend logic (API endpoints in “app/api” paired with a robust server organization in the “server” folder).
- The “server” folder is structured following a clean or hexagonal architecture pattern with distinct layers:
- Application layer (use cases and services)
- Domain layer (models, repositories, and business rules)
- Infrastructure layer (implementations for external services like portal integrations and Supabase repositories)
- In addition, the “lib” folder centralizes shared libraries for authentication, crawling, and Supabase integration.
- Configuration files (e.g., next.config.mjs, tsconfig.json) and development tooling (ESLint, Prettier, GitHub workflows) are also present, ensuring quality and build automation.

##### Review README for Additional Insights
- The README confirms that the core functionalities include syncing academic data from the school portal and comparing it against graduation requirements.
- It also lists the technology stack where Next.js with React and TypeScript is used for the frontend, Node.js with Supabase (PostgreSQL) for the backend, and Playwright for data crawling.
- The project also involves deployment and monitoring via Docker, AWS ECS, Vercel, and Sentry.

a. Main Components to Include:
- Client / Browser: Users access the service through a web application.
- Frontend Application: The Next.js based React application, which manages various route segments (funnel, landing, main, setting) and UI components (found in directories like “components/ui” and “app/(main)/components”).
- API Layer: The Next.js API routes under “app/api” that expose endpoints for fetching academic data, dashboard information, graduation progress, and more.
- Server / Business Logic:
- Application Layer: Located in “server/application”, with use cases for student management, academic records synchronization, and user-related operations.
- Domain Layer: Consisting of models and repository interfaces in “server/domain/…”, encapsulating core business rules.
- Infrastructure Layer: Implementation details (Supabase integration, portal scraping integration) found in “server/infrastructure” provide bridges to data sources.
- External Services & Data Sources:
- Supabase/PostgreSQL: As the database backend and for authentication (noted in “lib/supabase” and server/infrastructure).
- School Portal & Crawling Services: External endpoints accessed via the “suwon-scrape” modules and crawling libraries (Playwright usage).
- Third-party Auth Services: Integration with providers like Kakao, as seen from files in “lib/auth” and “components/KakaoProvider.tsx”.
- Monitoring & Error Handling: Sentry configuration files for logging and error monitoring (sentry.*.config.ts).

b. Relationships and Data Flows:
- User actions in the browser pass through the React-based UI which communicates with the API endpoints (data fetching, user authentication, etc.).
- API endpoints translate these requests into business operations by invoking use cases in the application layer.
- The application layer interacts with the domain layer to enforce business rules, and then persists or retrieves data using the infrastructure layer which talks to Supabase/PostgreSQL.
- For dynamic academic data, the system triggers external crawling processes that connect to the school portal to update academic records.
- Authentication requests are routed through modules in both the frontend (via authentication components) and backend (through the domain and infrastructure auth services).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client/Browser"]:::client

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Next.js Frontend"]:::frontend
        KakaoUI["Kakao Provider (UI)"]:::frontend
    end

    %% API Layer
    API["API Endpoints"]:::api

    %% Backend (Clean Architecture)
    subgraph "Backend (Clean Architecture)"
        AppLayer["Application Layer (server/application)"]:::backend
        DomainLayer["Domain Layer (server/domain)"]:::backend
        InfraLayer["Infrastructure Layer (server/infrastructure)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        Supabase["Supabase/PostgreSQL"]:::external
        SchoolPortal["School Portal (Crawling)"]:::external
        AuthProviders["Authentication Providers"]:::external
        Sentry["Monitoring & Error Handling (Sentry)"]:::external
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        LibSupabase["lib/supabase"]:::library
        LibAuth["lib/auth"]:::library
        LibCrawling["lib/crawling"]:::library
    end

    %% Additional Crawling Integration Node
    ScrapingAPI["Portal Scraping API (app/api/suwon-scrape)"]:::api

    %% Data Flow Connections
    Client -->|"accesses"| FE
    FE -->|"calls"| API
    FE -->|"integrates_with"| KakaoUI
    KakaoUI -->|"connects_to"| AuthProviders

    API -->|"invokes"| AppLayer
    API -->|"triggers"| ScrapingAPI
    ScrapingAPI -->|"uses"| LibCrawling

    AppLayer -->|"coordinates"| DomainLayer
    DomainLayer -->|"interacts_with"| InfraLayer
    AppLayer -->|"utilizes"| LibSupabase

    InfraLayer -->|"connects_to"| Supabase
    InfraLayer -->|"fetches_from"| SchoolPortal
    InfraLayer -->|"handles_auth"| AuthProviders
    InfraLayer -->|"reports_to"| Sentry

    FE -->|"uses"| LibAuth

    %% Styles
    classDef client fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef frontend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef api fill:#cfc,stroke:#333,stroke-width:2px;
    classDef backend fill:#fc9,stroke:#333,stroke-width:2px;
    classDef external fill:#f99,stroke:#333,stroke-width:2px;
    classDef library fill:#cff,stroke:#333,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/gyumong/chukchuk-haksa/tree/main/app"
    click API "https://github.com/gyumong/chukchuk-haksa/tree/main/app/api"
    click AppLayer "https://github.com/gyumong/chukchuk-haksa/tree/main/server/application"
    click DomainLayer "https://github.com/gyumong/chukchuk-haksa/tree/main/server/domain"
    click InfraLayer "https://github.com/gyumong/chukchuk-haksa/tree/main/server/infrastructure"
    click LibSupabase "https://github.com/gyumong/chukchuk-haksa/tree/main/lib/supabase"
    click LibAuth "https://github.com/gyumong/chukchuk-haksa/tree/main/lib/auth"
    click KakaoUI "https://github.com/gyumong/chukchuk-haksa/blob/main/components/KakaoProvider.tsx"
    click LibCrawling "https://github.com/gyumong/chukchuk-haksa/tree/main/lib/crawling"
    click ScrapingAPI "https://github.com/gyumong/chukchuk-haksa/tree/main/app/api/suwon-scrape"
    click Sentry "https://github.com/gyumong/chukchuk-haksa/blob/main/sentry.client.config.ts"
```
