# emi-arcioni/cocos-backend-challenge architecture

> Architecture diagram of the GitHub repository emi-arcioni/cocos-backend-challenge, 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/emi-arcioni/cocos-backend-challenge
- Repository: https://github.com/emi-arcioni/cocos-backend-challenge

## Overview

##### Main Components
- NestJS Application: Represented by the main entry point (src/main.ts) and the NestJS modules.
- Modules (each as separate components):
- Orders Module: Handles order creation, cancellation, and order validation. Contains controllers, services, DTOs, entities, and repositories.
- Portfolios Module: Manages portfolio recalculations, positions, and balances.
- Instruments Module: Handles retrieval and validation of financial instruments.
- Market Data Module: Provides market data entities and services for real-time or stored market information.
- Users Module: Manages user-related operations, such as validations (e.g., user existence) and user repository management.
- Common Module: Contains shared configurations (e.g., database config), enums, migrations, and scripts for synchronization and migrations.
- External Dependencies:
- PostgreSQL: The primary database system that holds orders, portfolios, instruments, and user data.
- Docker Compose: Optional service for running the Postgres database.

##### Relationships and Interactions
- API Flow:
- Incoming REST API requests (e.g., placing orders, retrieving portfolios, fetching instruments) are routed via controllers.
- Controllers delegate to their corresponding services, which contain business logic (for example, order validation including balance calculations and applying pessimistic locking via query runner transactions).
- Services interact with repository components to perform CRUD operations on the PostgreSQL database.
- Data Flow:
- Bidirectional communication where appropriate, such as controllers receiving processed data back from services.
- Migration and Synchronization:
- “scripts” component where database migrations and portfolio synchronization occurs, as part of the development and deployment process.

##### Architectural Patterns and Design Principles
- Module-Based Architecture: Each main entity (orders, portfolios, instruments, market data, users) is encapsulated in its own module, promoting separation of concerns and maintainability.
- MVC-like Flow: Controllers handle the HTTP layer, services implement business logic, and repositories interact with the database.
- Transaction Management & Locking: Emphasize the pessimistic locking strategy used in the orders service to prevent race conditions during order creation.
- Configuration & Shared Utilities: The “common” directory centralizes database configuration, enums, and migration scripts.
- Code Quality & Testing: Note the presence of ESLint/Prettier configurations and separate directories for unit and end-to-end tests.

- API Client: Represent external clients (or Postman) interacting with the system.
- NestJS App: A container for the application that includes:
- Orders Module (with its controller, service, DTOs, entities, and repository)
- Portfolios Module (with its controller, service, and repository)
- Instruments Module (with its controller, service, validations, DTOs, entities, etc.)
- Market Data Module (with its service and repository)
- Users Module (with its controller, service, validations, and repository)
- Common Configurations & Shared Scripts/Migrations
- PostgreSQL Database: Represent as a separate component that the repository layer interacts with.
- Docker Compose (optional) for database provisioning.
- Use another for business logic (services) and controllers.
- Differentiate repositories and external systems (like the database) with separate visual markers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    API_Client("API Client"):::api
    Postman("Postman Collection"):::external
    Docker("Docker Compose"):::external
    DB("PostgreSQL Database"):::external

    %% NestJS Application Container
    subgraph "NestJS Application"
        ME("Main Entry (NestJS Bootstrap)"):::nest
        MM("Main Module"):::nest

        %% Orders Module
        subgraph "Orders Module"
            OModule("Orders Module"):::nest
            OController("Orders Controller"):::controller
            OService("Orders Service (pessimistic locking)"):::service
            ORepo("Orders Repository"):::repository
        end

        %% Portfolios Module
        subgraph "Portfolios Module"
            PModule("Portfolios Module"):::nest
            PController("Portfolios Controller"):::controller
            PService("Portfolios Service"):::service
            PRepo("Portfolios Repository"):::repository
        end

        %% Instruments Module
        subgraph "Instruments Module"
            IModule("Instruments Module"):::nest
            IController("Instruments Controller"):::controller
            IService("Instruments Service"):::service
            IRepo("Instruments Repository"):::repository
        end

        %% Market Data Module
        subgraph "Market Data Module"
            MModule("Market Data Module"):::nest
            MService("Market Data Service"):::service
            MRepo("Market Data Repository"):::repository
        end

        %% Users Module
        subgraph "Users Module"
            UModule("Users Module"):::nest
            UService("Users Service"):::service
            URepo("Users Repository"):::repository
        end

        %% Common Module
        subgraph "Common Module"
            CommonConfig("DB Config"):::common
            Migrations("Migrations & DB Scripts"):::common
            Scripts("Shared Scripts"):::common
        end
    end

    %% Connections from External API to Controllers
    API_Client -->|"calls"| OController
    API_Client -->|"calls"| PController
    API_Client -->|"calls"| IController
    API_Client -->|"calls"| MService

    %% Main Entry to Main Module and Modules
    ME -->|"bootstraps"| MM
    MM -->|"loads"| OModule
    MM -->|"loads"| PModule
    MM -->|"loads"| IModule
    MM -->|"loads"| MModule
    MM -->|"loads"| UModule
    MM -->|"loads"| CommonConfig

    %% Internal Module Flows
    %% Orders Module Flow
    OController -->|"delegates"| OService
    OService -->|"invokes"| ORepo

    %% Portfolios Module Flow
    PController -->|"delegates"| PService
    PService -->|"invokes"| PRepo

    %% Instruments Module Flow
    IController -->|"delegates"| IService
    IService -->|"invokes"| IRepo

    %% Market Data Module Flow
    MService -->|"invokes"| MRepo

    %% Users Module Flow
    UModule --> UService
    UService -->|"invokes"| URepo

    %% Repository interactions with Database
    ORepo -->|"CRUD operations"| DB
    PRepo -->|"CRUD operations"| DB
    IRepo -->|"CRUD operations"| DB
    MRepo -->|"CRUD operations"| DB
    URepo -->|"CRUD operations"| DB

    %% Common Module interactions with Database
    Migrations -->|"migrates"| DB
    Scripts -->|"syncs data"| DB

    %% External Docker Compose to Database
    Docker -->|"provisions"| DB

    %% External Postman Collection (API testing tool)
    Postman --- API_Client

    %% Click Events
    click ME "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/main.ts"
    click MM "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/app/app.module.ts"
    click OModule "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/orders/orders.module.ts"
    click OController "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/orders/orders.controller.ts"
    click OService "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/orders/orders.service.ts"
    click ORepo "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/orders/order.repository.ts"
    click PModule "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/portfolios/portfolios.module.ts"
    click PController "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/portfolios/portfolios.controller.ts"
    click PService "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/portfolios/portfolios.service.ts"
    click PRepo "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/portfolios/portfolio.repository.ts"
    click IModule "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/instruments/instruments.module.ts"
    click IController "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/instruments/instruments.controller.ts"
    click IService "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/instruments/instruments.service.ts"
    click IRepo "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/instruments/instrument.repository.ts"
    click MModule "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/market-data/market-data.module.ts"
    click MService "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/market-data/market-data.service.ts"
    click MRepo "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/market-data/market-data.repository.ts"
    click UModule "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/users/users.module.ts"
    click UService "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/users/users.service.ts"
    click URepo "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/users/user.repository.ts"
    click CommonConfig "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/src/common/config/dbconfig.ts"
    click Migrations "https://github.com/emi-arcioni/cocos-backend-challenge/tree/main/src/common/migrations"
    click Scripts "https://github.com/emi-arcioni/cocos-backend-challenge/tree/main/src/common/scripts"
    click Docker "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/docker-compose.yml"
    click Postman "https://github.com/emi-arcioni/cocos-backend-challenge/blob/main/Cocos_Backend_Challenge.postman_collection.json"

    %% Styles
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef nest fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef controller fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef repository fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef common fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
```
