# nnminh-sam/competitive-contest-utils-server architecture

> Architecture diagram of the GitHub repository nnminh-sam/competitive-contest-utils-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nnminh-sam/competitive-contest-utils-server
- Repository: https://github.com/nnminh-sam/competitive-contest-utils-server

## Overview

This project is a backend application built using the NestJS framework in TypeScript. The file tree and README indicate that it’s a modular, server-side application designed following the NestJS patterns, and it includes multiple features such as authentication, contest management, mailing, and more.

##### Overall Project Type and Purpose
- Recognize that this is a NestJS-based server-side application.
- The project uses a modular architecture with clearly defined modules (auth, contest, contestant, affiliation, team, mailing) that encapsulate specific domains.
- It integrates with external services like Redis (used in the database provider) and is containerized (docker-compose.yml is present), indicating a production-ready, scalable back-end system.

##### Breakdown of the File Structure
- The top-level directories/files include configuration files (e.g., .eslintrc.js, .prettierrc, docker-compose.yml), project metadata (README.md, package.json), and TypeScript configuration files (tsconfig.json, tsconfig.build.json).
- The application’s core resides in the src directory:
○ src/main.ts – the entry point.
○ src/app.module.ts – the root module where all other modules are imported.
- Various feature modules exist under src/modules (affiliation, auth, contest, contestant, mailing, team), each containing its own controller, service, and DTOs.
- There is a “common” directory which includes decorators, DTOs, filters, guards, interceptors, and pipes that provide cross-cutting concerns.
- The “database” directory shows how the application interacts with the persistence layer, including a custom Redis provider.
- Directories like “environment” help manage configuration and environmental variables.

##### Components to Highlight
a. Core Application Setup:
– An “Entry Point” or “Bootstrap Layer” showing src/main.ts initializing the NestJS application.
– The “App Module” as the central hub, which imports all feature modules.
b. Feature Modules:
– Separate modules such as:
- Auth Module: Handling user authentication with controllers, services, DTOs, and strategies (JWT & Local).
- Contest Module: Managing contest-related functionalities.
- Contestant Module: Handling registrations and contestant data.
- Affiliation Module: Managing affiliations.
- Team Module: Managing team data.
- Mailing Module: Responsible for email integrations.
c. Common/Shared Components:
– Shared functionalities (e.g., decorators, pipes, filters, interceptors) that provide standardized behavior across modules.
d. Infrastructure/External Services:
– Database Layer: Illustrate the “database” module, highlighting Redis integration.
– Environment Module: Show how application configuration is handled.
– Docker Compose: Indicate that the application is containerized and can interact with other services via Docker.

##### Relationships & Interactions
– The entry point (main.ts) initializes the App Module.
– The App Module imports and wires together all other modules.
– Controllers in each module interact with their corresponding services.
– Business logic resides in services, which may communicate with the database (Redis via redis.provider.ts, redis.service.ts).
– Shared middleware and guards (like JWT.guard.ts and local.guard.ts in the auth module) intercept and secure request flows.

##### Architectural Patterns and Technologies
- Modular approach inherent to NestJS — each domain (module) encapsulates its own controllers, services, and DTOs.
- Separation of concerns with common utilities (decorators, pipes) abstracted in a “common” folder.
- How dependency injection is used throughout the application.
- Use of microservices concepts if applicable (or simply distinct modules that can be scaled or refactored independently).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Application Setup
    A["Entry Point (src/main.ts)"]:::core
    B["App Module (src/app.module.ts)"]:::core
    A -->|"init"| B

    %% Feature Modules Subgraph
    subgraph "Feature Modules"
        M1["Auth Module"]:::module
        M2["Contest Module"]:::module
        M3["Contestant Module"]:::module
        M4["Affiliation Module"]:::module
        M5["Team Module"]:::module
        M6["Mailing Module"]:::module
    end

    %% App Module imports Feature Modules
    B -->|"imports"| M1
    B -->|"imports"| M2
    B -->|"imports"| M3
    B -->|"imports"| M4
    B -->|"imports"| M5
    B -->|"imports"| M6

    %% Common/Shared Components
    C["Common Components"]:::common
    M1 -->|"uses"| C
    M2 -->|"uses"| C
    M3 -->|"uses"| C
    M4 -->|"uses"| C
    M5 -->|"uses"| C
    M6 -->|"uses"| C

    %% Database & External Services Subgraph
    subgraph "Database & External Services"
        D1["Redis Provider"]:::external
        D2["Redis Service"]:::external
    end
    B -->|"db"| D1
    B -->|"db"| D2

    %% Environment Configuration and Docker Containerization
    E["Environment Configuration"]:::config
    F["Docker Containerization"]:::container
    B -->|"config"| E
    B -->|"containerized"| F

    %% Click Events
    click A "https://github.com/nnminh-sam/competitive-contest-utils-server/blob/main/src/main.ts"
    click B "https://github.com/nnminh-sam/competitive-contest-utils-server/blob/main/src/app.module.ts"
    click M1 "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/modules/auth"
    click M2 "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/modules/contest"
    click M3 "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/modules/contestant"
    click M4 "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/modules/affiliation"
    click M5 "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/modules/team"
    click M6 "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/modules/mailing"
    click C "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/common"
    click D1 "https://github.com/nnminh-sam/competitive-contest-utils-server/blob/main/src/database/provider/redis.provider.ts"
    click D2 "https://github.com/nnminh-sam/competitive-contest-utils-server/blob/main/src/database/redis.service.ts"
    click E "https://github.com/nnminh-sam/competitive-contest-utils-server/tree/main/src/environment"
    click F "https://github.com/nnminh-sam/competitive-contest-utils-server/blob/main/docker-compose.yml"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef module fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef common fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef container fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
