# jjikky/cs-hub-be architecture

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

- Interactive diagram: https://gitdiagram.com/jjikky/cs-hub-be
- Repository: https://github.com/jjikky/cs-hub-be

## Overview

##### Project Type and Purpose
- This is a backend API server built with NestJS following a modular, layered (Domain-Driven) monolithic architecture.
- Purpose: Provide RESTful endpoints for CS Hub features—authentication (with JWT and Kakao OAuth), user management, quizzes, point tracking, and ranking.
- Data persistence with PostgreSQL via TypeORM, deployable with Docker/PM2, supporting seed scripts and e2e tests.

##### File-Structure Analysis
- Top-level config: Dockerfile, docker-compose.yml, ecosystem.config.js (PM2), GitHub workflows.
- src/app.module.ts wires submodules.
- common/: shared constants, DTOs, decorators, middleware, interceptors.
- config/: configuration modules (app, auth, swagger).
- database/: TypeORM data-source, config, seed modules.
- modules/: one folder per domain (auth, user, quiz, point, ranking), each following subfolders:
- presentation (controllers)
- application (services)
- domain (entities, value objects, repository interfaces)
- infrastructure (TypeORM entities, repository implementations, external clients)
- utils/: config validation.
- test/: e2e tests.

##### Key Architectural Patterns
- Modular Monolith: each feature as its own module.
- Layered Architecture: presentation → application (use-cases) → domain → infrastructure (data access).
- Dependency Injection via NestJS.
- External OAuth integration (Kakao).
- Configuration management with @nestjs/config.
- Database seeding pipeline.

##### Main Components & Interactions
A. Client
- Web or mobile frontend, or any HTTP client.
B. API Gateway (NestJS Server)
- HTTP Controllers receive requests.
- Middleware (logger), Guards (JWT), Interceptors (transform responses).
- Module Boundaries: auth, user, quiz, point, ranking.
C. Application Layer
- Business logic encapsulated in Services.
D. Domain Layer
- Core entities, value-objects, domain rules, repository interfaces.
E. Infrastructure Layer
- TypeORM entities & repositories → PostgreSQL.
- External HTTP client for Kakao OAuth.
F. Data Store
- PostgreSQL database.
G. Deployment/DevOps
- Docker container, Docker Compose network, PM2 process manager.
- CI/CD pipeline via GitHub Actions.

##### Architectural Patterns & Design Principles
- Single Responsibility per module.
- Clear separation of concerns: controllers (HTTP), services (business logic), repositories (data access).
- Dependency Inversion: modules depend on abstractions (interfaces) not implementations.
- Configuration injected at runtime via config modules.
- Use middleware/interceptors for cross-cutting concerns (logging, error handling).
- Seed data orchestration separate from main flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Context
    Client["Client (Web/Mobile)"]:::external -->|HTTP Request| NestJS["NestJS API Server"]:::server
    NestJS -->|SQL Queries| Postgres["PostgreSQL"]:::database
    AuthKakao["Kakao OAuth Service"]:::external
    AuthServiceInfra -->|OAuth Call| AuthKakao

    %% NestJS Server Container
    subgraph "NestJS API Server"
        direction TB

        %% Common & Config
        CommonUtils["Common Utilities"]:::common
        ConfigModules["Configuration Modules"]:::common

        %% Feature Modules
        subgraph "Auth Module"
            direction TB
            AuthController["AuthController"]:::presentation
            AuthService["AuthService"]:::application
            JwtGuard["JwtAuthGuard"]:::infrastructure
            JwtStrategy["JwtStrategy"]:::infrastructure
            AuthDomain["Auth Domain Interfaces"]:::domain
            AuthServiceInfra["KakaoAuthClient"]:::infrastructure
            AuthController -->|calls| AuthService
            AuthService -->|uses| AuthDomain
            AuthService -->|uses| AuthServiceInfra
            AuthService -->|protected by| JwtGuard
            JwtGuard -->|strategy| JwtStrategy
        end

        subgraph "User Module"
            direction TB
            UserController["UserController"]:::presentation
            UserService["UserService"]:::application
            UserDomain["User Domain Entities"]:::domain
            UserRepo["UserEntity (TypeORM)"]:::infrastructure
            UserController -->|calls| UserService
            UserService -->|uses| UserDomain
            UserService -->|CRUD| UserRepo
        end

        subgraph "Quiz Module"
            direction TB
            QuizController["QuizController"]:::presentation
            CategoryController["CategoryController"]:::presentation
            InterviewController["InterviewController"]:::presentation
            LikeController["LikeController"]:::presentation
            QuizService["QuizService"]:::application
            InterviewService["InterviewService"]:::application
            LikeService["LikeService"]:::application
            QuizAttemptService["QuizAttemptService"]:::application
            QuizDomain["Quiz Domain"]:::domain
            QuizRepo["Quiz Infrastructure (TypeORM)"]:::infrastructure
            QuizController -->|calls| QuizService
            CategoryController -->|calls| QuizService
            InterviewController -->|calls| InterviewService
            LikeController -->|calls| LikeService
            QuizService -->|uses| QuizDomain
            QuizService -->|CRUD| QuizRepo
            InterviewService -->|uses| QuizDomain
            LikeService -->|uses| QuizDomain
            QuizAttemptService -->|uses| QuizDomain
        end

        subgraph "Point Module"
            direction TB
            PointController["PointController"]:::presentation
            PointService["PointService"]:::application
            PointDomain["PointHistory VO"]:::domain
            PointRepo["PointHistoryEntity"]:::infrastructure
            PointController -->|calls| PointService
            PointService -->|uses| PointDomain
            PointService -->|CRUD| PointRepo
        end

        subgraph "Ranking Module"
            direction TB
            RankingController["RankingController"]:::presentation
            RankingService["RankingService"]:::application
            RankingDomain["Ranking Entity"]:::domain
            RankingRepo["RankingEntity"]:::infrastructure
            RankingController -->|calls| RankingService
            RankingService -->|uses| RankingDomain
            RankingService -->|CRUD| RankingRepo
        end

        %% Database & Seed
        subgraph "Database & Seeding"
            direction TB
            PostgresConfig["Postgres Config"]:::infrastructure
            DataSource["Data Source"]:::infrastructure
            SeedModule["Seed Module"]:::infrastructure
            RunSeed["Run Seed Script"]:::infrastructure
            CategorySeed["CategorySeedService"]:::infrastructure
            SeedModule --> RunSeed
            RunSeed --> CategorySeed
        end

        %% Entry Point
        Main["Entry Point (main.ts)"]:::infrastructure

        %% Wiring
        Main --> AppModule["AppModule"]:::infrastructure
        AppModule -->|imports| CommonUtils
        AppModule -->|imports| ConfigModules
        AppModule -->|imports| PostgresConfig
        AppModule -->|imports| DataSource
        AppModule -->|imports| SeedModule
        AppModule -->|imports| AuthController
        AppModule -->|imports| UserController
        AppModule -->|imports| QuizController
        AppModule -->|imports| PointController
        AppModule -->|imports| RankingController
    end

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#004080;
    classDef application fill:#DFFFD0,stroke:#408000;
    classDef domain fill:#FFF8C0,stroke:#A68F00;
    classDef infrastructure fill:#FFE0B0,stroke:#A85F00;
    classDef external fill:#E0E0E0,stroke:#666666,stroke-dasharray: 5 5;
    classDef database fill:#D0B0A0,stroke:#663300;
    classDef common fill:#F0D0FF,stroke:#800080;
    classDef server fill:#FFFFFF,stroke:#000000,stroke-width:2px;

    %% Click Events
    click Main "https://github.com/jjikky/cs-hub-be/blob/dev/src/main.ts"
    click AppModule "https://github.com/jjikky/cs-hub-be/blob/dev/src/app.module.ts"
    click CommonUtils "https://github.com/jjikky/cs-hub-be/tree/dev/src/common"
    click ConfigModules "https://github.com/jjikky/cs-hub-be/tree/dev/src/config/modules"
    click PostgresConfig "https://github.com/jjikky/cs-hub-be/blob/dev/src/database/config/postgres.config.ts"
    click DataSource "https://github.com/jjikky/cs-hub-be/blob/dev/src/database/data-source.ts"
    click SeedModule "https://github.com/jjikky/cs-hub-be/blob/dev/src/database/seed/seed.module.ts"
    click RunSeed "https://github.com/jjikky/cs-hub-be/blob/dev/src/database/seed/run-seed.ts"
    click CategorySeed "https://github.com/jjikky/cs-hub-be/blob/dev/src/database/seed/category/category-seed.service.ts"
    click AuthController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/auth/presentation/auth.controller.ts"
    click AuthService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/auth/application/auth.service.ts"
    click AuthDomain "https://github.com/jjikky/cs-hub-be/tree/dev/src/modules/auth/domain"
    click AuthServiceInfra "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/auth/infrastructure/external/kakao/kakao-auth.client.ts"
    click JwtGuard "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/auth/jwt-auth.guard.ts"
    click JwtStrategy "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/auth/strategy/jwt.strategy.ts"
    click UserController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/user/presentation/user.controller.ts"
    click UserService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/user/application/user.service.ts"
    click UserDomain "https://github.com/jjikky/cs-hub-be/tree/dev/src/modules/user/domain"
    click UserRepo "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/user/infrastructure/db/entity/user.entity.ts"
    click QuizController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/presentation/quiz.controller.ts"
    click CategoryController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/presentation/category.controller.ts"
    click InterviewController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/presentation/interview.controller.ts"
    click LikeController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/presentation/like.controller.ts"
    click QuizService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/application/quiz.service.ts"
    click InterviewService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/application/interview.service.ts"
    click LikeService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/application/like.service.ts"
    click QuizAttemptService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/quiz/application/quiz-attempt.service.ts"
    click QuizDomain "https://github.com/jjikky/cs-hub-be/tree/dev/src/modules/quiz/domain"
    click QuizRepo "https://github.com/jjikky/cs-hub-be/tree/dev/src/modules/quiz/infrastructure"
    click PointController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/point/presentation/point.controller.ts"
    click PointService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/point/application/point.service.ts"
    click PointDomain "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/point/domain/point-history.ts"
    click PointRepo "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/point/infrastructure/db/entity/point-history.entity.ts"
    click RankingController "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/ranking/presentation/ranking.controller.ts"
    click RankingService "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/ranking/application/ranking.service.ts"
    click RankingDomain "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/ranking/domain/ranking.ts"
    click RankingRepo "https://github.com/jjikky/cs-hub-be/blob/dev/src/modules/ranking/infrastructure/db/entity/ranking.entity.ts"
```
