# pgkwon1/ocowan_api architecture

> Architecture diagram of the GitHub repository pgkwon1/ocowan_api, 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/pgkwon1/ocowan_api
- Repository: https://github.com/pgkwon1/ocowan_api

## Overview

##### Project type and purpose
- This is a NestJS-based backend application (no UI/front-end code present), structured as a monolithic server with multiple feature modules.

##### File structure
- Top level:
- src/main.ts: application entry point
- src/app.module.ts: root module wiring all feature modules
- src/common, decorators, interceptors, exception handlers: cross-cutting concerns
- src/modules: each folder under modules is a domain (e.g. auth, users, team, til, levels…)
- config files: nest-cli.json, tsconfig.json, package.json, CI in .github/workflows
- Each module typically has:
- Module file (.module.ts)
- Controller(s)
- Service(s)
- Entities/Models: database ORM definitions
- Guards, strategies, util services (e.g. JWT)

##### Key insights from README
- It’s a standard NestJS project scaffold, configurable via npm scripts for dev/prod/test.

a. Main components:
1. NestJS Application (single process)
- Main Module
- Feature Modules (auth, users, team, til, levels, bigthree, ocowan, storage, azure, external-api, redis, winston)
2. Database (e.g., PostgreSQL/MySQL – implied by entities/models)
3. Redis Cache
4. External Services:
- Azure (via Azure Service module)
- Generic External API
- GitHub (for exception handling or data fetch?)
5. Clients/Consumers:
- REST clients (web/mobile) calling controllers
- CLI/cron jobs (if any)
b. Relationships/Interactions:
- Controllers expose HTTP endpoints → call Services
- Services orchestrate business logic, access Repositories (ORM) → Database
- Caching layer: Services may read/write to Redis via Redis Module
- Auth Module issues JWTs & protects routes via Guards/Interceptors
- External API Module & Azure Module call out to third-party endpoints
- Winston Module captures logs across Services/Controllers
- Common/Exception/Interceptors provide cross-cutting AOP bits
c. Architectural patterns:
- Modular monolith with clear bounded contexts
- Dependency Injection (Nest’s DI container)
- Layered pattern: Controller → Service → Repository/ORM
- Decorator-based guards, exception filters, interceptors
d. Key technologies/frameworks:
- NestJS framework (Modules, Controllers, Providers)
- TypeScript
- TypeORM or Sequelize (entities/models)
- Redis client (nestjs-redis)
- Azure SDK
- Winston logger

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    RESTClients["REST Clients"]:::client
    CLIJobs["CLI/Cron Jobs"]:::client

    %% External Systems
    DB[(Database)]:::db
    Redis[(Redis Cache)]:::db
    Azure["Azure Services"]:::external
    ExternalAPI["External API"]:::external

    %% NestJS Application
    subgraph "NestJS Application"
        direction TB

        %% Cross-Cutting Concerns
        subgraph "Cross-Cutting Concerns"
            direction TB
            BaseService["BaseService"]:::cross
            GenericService["GenericService"]:::cross
            CommonCatch["Common Exception Filter"]:::cross
            JwtDecorator["JWT Decorator"]:::cross
            GithubException["GithubException"]:::cross
            OcowanException["OcowanException"]:::cross
            ResponseInterceptor["Response Interceptor"]:::cross
        end

        %% Feature Modules
        subgraph "Feature Modules"
            direction TB
            AuthModule["Auth Module"]:::module
            UsersModule["Users Module"]:::module
            TeamModule["Team Module"]:::module
            TILModule["TIL Module"]:::module
            LevelsModule["Levels Module"]:::module
            BigthreeModule["Bigthree Module"]:::module
            OcowanModule["Ocowan Module"]:::module
            StorageModule["Storage Module"]:::module
            AzureModule["Azure Integration Module"]:::module
            ExternalApiModule["External API Module"]:::module
            RedisModule["Redis Module"]:::module
            WinstonModule["Winston Logging Module"]:::module
        end
    end

    %% Relationships
    RESTClients -->|"HTTP Requests"| AuthModule
    RESTClients -->|"HTTP Requests"| UsersModule
    RESTClients -->|"HTTP Requests"| TeamModule
    RESTClients -->|"HTTP Requests"| TILModule
    RESTClients -->|"HTTP Requests"| LevelsModule
    RESTClients -->|"HTTP Requests"| BigthreeModule
    RESTClients -->|"HTTP Requests"| OcowanModule
    RESTClients -->|"HTTP Requests"| StorageModule

    AuthModule -->|"Read/Write"| DB
    UsersModule -->|"Read/Write"| DB
    TeamModule -->|"Read/Write"| DB
    TILModule -->|"Read/Write"| DB
    LevelsModule -->|"Read/Write"| DB
    BigthreeModule -->|"Read/Write"| DB
    OcowanModule -->|"Read/Write"| DB
    StorageModule -->|"Read/Write"| DB

    AuthModule -->|"Cache Aside"| Redis
    UsersModule -->|"Cache Aside"| Redis
    TeamModule -->|"Cache Aside"| Redis

    AzureModule -->|"Outbound Calls"| Azure
    ExternalApiModule -->|"Outbound Calls"| ExternalAPI

    WinstonModule -->|"Logs From"| AuthModule
    WinstonModule -->|"Logs From"| UsersModule
    WinstonModule -->|"Logs From"| TeamModule
    WinstonModule -->|"Logs From"| TILModule
    WinstonModule -->|"Logs From"| LevelsModule
    WinstonModule -->|"Logs From"| BigthreeModule
    WinstonModule -->|"Logs From"| OcowanModule
    WinstonModule -->|"Logs From"| StorageModule

    CLIJobs -->|Cron/Batch| TILModule
    CLIJobs -->|Cron/Batch| LevelsModule

    %% Click Events
    click RESTClients "https://github.com/pgkwon1/ocowan_api/blob/master/src/main.ts"
    click BaseService "https://github.com/pgkwon1/ocowan_api/blob/master/src/common/base.service.ts"
    click GenericService "https://github.com/pgkwon1/ocowan_api/blob/master/src/common/generic.service.ts"
    click CommonCatch "https://github.com/pgkwon1/ocowan_api/blob/master/src/common/common.catch.ts"
    click JwtDecorator "https://github.com/pgkwon1/ocowan_api/blob/master/src/decorators/jwt.decorator.ts"
    click GithubException "https://github.com/pgkwon1/ocowan_api/blob/master/src/exception/GithubException.ts"
    click OcowanException "https://github.com/pgkwon1/ocowan_api/blob/master/src/exception/OcowanException.ts"
    click ResponseInterceptor "https://github.com/pgkwon1/ocowan_api/blob/master/src/interceptors/response.interceptor.ts"
    click AuthModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/auth/auth.module.ts"
    click UsersModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/users/users.module.ts"
    click TeamModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/team/team.module.ts"
    click TILModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/til/til.module.ts"
    click LevelsModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/levels/levels.module.ts"
    click BigthreeModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/bigthree/bigthree.module.ts"
    click OcowanModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/ocowan/ocowan.module.ts"
    click StorageModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/storage/stroage.module.ts"
    click AzureModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/azure/azure.module.ts"
    click ExternalApiModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/external-api/external-api.module.ts"
    click RedisModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/redis/redis.module.ts"
    click WinstonModule "https://github.com/pgkwon1/ocowan_api/blob/master/src/modules/winston/winston.module.ts"
    click RESTClients "https://github.com/pgkwon1/ocowan_api/blob/master/src/app.controller.ts"
    click CLIJobs "https://github.com/pgkwon1/ocowan_api/blob/master/src/app.service.ts"

    %% Styles
    classDef module fill:#e0f7fa,stroke:#006064,color:#006064;
    classDef cross fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a,stroke-dasharray: 5 5,stroke-width:1px,rx:5,ry:5;
    classDef db fill:#fff3e0,stroke:#e65100,color:#e65100,shape:cylinder;
    classDef external fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32,shape:cloud;
    classDef client fill:#fce4ec,stroke:#880e4f,color:#880e4f,rx:10,ry:10;
```
