# cucchi10/cocos-challenge-backend architecture

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

- Interactive diagram: https://gitdiagram.com/cucchi10/cocos-challenge-backend
- Repository: https://github.com/cucchi10/cocos-challenge-backend

## Overview

##### Project Type and Purpose
- This is a backend API project built using NestJS. It serves as the API layer for a financial platform (as indicated by “COCOS CAPITAL”) and is designed to manage assets, portfolios, transactions, orders, instruments, market data, and user data.
- The README highlights database setup via Docker (using PostgreSQL and PG Admin), API documentation via Swagger UI, and the overall modularized structure of the project.

##### Analyzing the File Structure
- The top-level directories and files reveal the following:
- Configuration: Files like .env.example, docker-compose.yml, nest-cli.json, and various configuration files under src/config.
- Documentation: The docs folder holds details about the database, Docker, Swagger, and Postman collection.
- Source Code: The src directory is organized by modules – for example, “broker” (which itself subdivides into assets, portfolio, transactions, useCase), “instruments”, “marketdata”, “orders”, and “users”. Also present are common shared utilities (common) and the database module.
- Testing: The test folder contains basic tests and mocks.
- The detailed modular separation (controllers, services, dtos, strategies, interfaces) within src indicates the use of NestJS’s modular design and possible implementation of patterns like MVC or use-case driven components.

- API Layer (NestJS Server):
- Modules:
- Broker Module – showing submodules for assets, portfolio, and transactions (which include strategy patterns for different transaction types like buy, sell, cancel).
- Instruments Module – handling instrument-related entities and DTOs.
- MarketData, Orders, and Users Modules – each representing a part of the system’s core business domain.
- Common Module – with shared constants, utilities, pipes, and decorators.
- Config Module – for environment-specific configurations.
- Database Module – handling database connectivity and ORM (or direct SQL scripts from docs) which interacts with PostgreSQL.
- External/Supporting Services:
- PostgreSQL Database (launched via docker-compose) with PG Admin as a database management tool.
- Swagger UI for API documentation (noted to be accessible at /api/v1/doc).
- Docker infrastructure – indicating how containers (e.g., the database) are spun up.
- Additional Deployment/Development Tools:
- Docker environment (docker-compose.yml setups) and environment management (.env file).

##### Relationships and Interactions
- Controllers interact with their corresponding service layers, which might invoke use case logic (like in the broker/useCase) and strategies (e.g., in transaction strategies).
- The services then interact with the database via the database module.
- Configuration components provide environment-specific settings for database connections, API routes, and more.
- External tools such as PG Admin manage the database and Swagger serves as interactive API documentation.

##### Architectural Patterns and Design Principles
- Modular Structure: Each business function (broker, instruments, marketdata, etc.) is encapsulated in separate modules.
- Use of Dependency Injection and Inversion of Control (a hallmark of NestJS).
- Strategy Pattern: Evident from the transactions module (transaction-strategy.factory.ts and defined strategies for buy, sell, cancel transactions).
- Clear Separation of Concerns: Configuration, common shared utilities, and domain logic are separated into distinct directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level External Client
    Client["Client"]:::external

    %% API Layer
    APIGateway["API Gateway (NestJS Server)"]:::apiLayer

    %% Business Modules Subgraph
    subgraph "Business Modules"
        %% Broker Module Subgraph
        subgraph "Broker Module"
            BrokerAssets["Assets"]:::business
            BrokerPortfolio["Portfolio"]:::business
            BrokerTransactions["Transactions & Strategies"]:::business
            BrokerUseCases["Use Cases"]:::business
        end
        InstrumentsModule["Instruments Module"]:::business
        MarketDataModule["MarketData Module"]:::business
        OrdersModule["Orders Module"]:::business
        UsersModule["Users Module"]:::business
        CommonModule["Common Module"]:::business
        ConfigModule["Configuration Module"]:::business
    end

    %% Infrastructure Layer
    DatabaseModule["Database Module"]:::infra
    PostgreSQL["((PostgreSQL Database))"]:::infra

    %% External Services Subgraph
    subgraph "External Services"
        DockerEnv["Docker & Environment Setup"]:::external
        SwaggerUI["Swagger UI"]:::external
    end

    %% Connections
    Client -->|"HTTP Request"| APIGateway
    APIGateway -->|"Routes"| BrokerAssets
    APIGateway -->|"Routes"| BrokerPortfolio
    APIGateway -->|"Routes"| BrokerTransactions
    APIGateway -->|"Routes"| BrokerUseCases
    APIGateway -->|"Routes"| InstrumentsModule
    APIGateway -->|"Routes"| MarketDataModule
    APIGateway -->|"Routes"| OrdersModule
    APIGateway -->|"Routes"| UsersModule
    APIGateway -->|"Routes"| CommonModule
    APIGateway -->|"Routes"| ConfigModule

    %% Modules interact with Database Module
    BrokerAssets -->|"DB Query"| DatabaseModule
    BrokerPortfolio -->|"DB Query"| DatabaseModule
    BrokerTransactions -->|"DB Query"| DatabaseModule
    BrokerUseCases -->|"DB Query"| DatabaseModule
    InstrumentsModule -->|"DB Query"| DatabaseModule
    MarketDataModule -->|"DB Query"| DatabaseModule
    OrdersModule -->|"DB Query"| DatabaseModule
    UsersModule -->|"DB Query"| DatabaseModule
    CommonModule -->|"DB Query"| DatabaseModule
    ConfigModule -->|"Configures"| DatabaseModule

    DatabaseModule -->|"SQL Commands"| PostgreSQL

    %% External Services Connections
    APIGateway -->|"Docs Access"| SwaggerUI
    DockerEnv -->|"Hosts"| APIGateway
    DockerEnv -->|"Hosts"| DatabaseModule

    %% Click Events
    click APIGateway "https://github.com/cucchi10/cocos-challenge-backend/blob/main/src/main.ts"
    click BrokerAssets "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/broker/assets"
    click BrokerPortfolio "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/broker/portfolio"
    click BrokerTransactions "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/broker/transactions"
    click BrokerUseCases "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/broker/useCase"
    click InstrumentsModule "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/instruments"
    click MarketDataModule "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/marketdata"
    click OrdersModule "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/orders"
    click UsersModule "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/users"
    click CommonModule "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/common"
    click ConfigModule "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/config"
    click DatabaseModule "https://github.com/cucchi10/cocos-challenge-backend/tree/main/src/database"
    click DockerEnv "https://github.com/cucchi10/cocos-challenge-backend/blob/main/docker-compose.yml"
    click SwaggerUI "https://github.com/cucchi10/cocos-challenge-backend/tree/main/docs/swagger"

    %% Styles
    classDef apiLayer fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef business fill:#ADD8E6,stroke:#1E90FF,stroke-width:2px;
    classDef infra fill:#90EE90,stroke:#228B22,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
```
