# carbon-forked/carbon-backend architecture

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

- Interactive diagram: https://gitdiagram.com/carbon-forked/carbon-backend
- Repository: https://github.com/carbon-forked/carbon-backend

## Overview

##### Project Type and Purpose
- This is a modular monolithic backend service built with NestJS.
- Purpose: ingest and process on-chain events from Carbon smart contracts, store them in TimescaleDB, cache in Redis, expose a versioned REST API, and send notifications via Telegram. Includes optional Python simulator and developer tools (ERD generator, DB seeder).

##### Main Components
A. Clients and Tools
- Web or CLI clients consuming the REST API
- Python Simulator (src/simulator)
- Developer Scripts (generate-erd, seed)
B. API Layer
- NestJS HTTP Server with v1 controllers (src/v1/*)
- Global interceptors (cache.interceptor), middleware (logging)
C. Core Business Modules
- Ingestion Modules: harvester, deployment, event modules (each event type under src/events)
- Domain Modules: activity, pair, token, quote, tvl, volume, strategy, historic-quote, codex, updater
- Notification Module: notification.controller, notification.service, TelegramService
D. Data Layer
- TimescaleDB (PostgreSQL) accessed via TypeORM entities and migrations (src/migrations, src/*.entity.ts)
- Redis Cache (src/redis/redis.module.ts)
E. External Integrations
- Blockchain RPC endpoints & Multicall contracts (src/abis)
- CoinGecko API (src/quote/coingecko.service.ts)
- CoinMarketCap API (src/coinmarketcap)
- Codex API (src/codex)
- Google Cloud Tasks (notifications queue)
- Telegram Bot API

##### Relationships and Data Flows
- Clients → HTTP REST API → Controllers → Services
- Ingestion (Harvester/Deployment) → RPC Endpoints → Event Modules → DB
- Business Services → TypeORM → TimescaleDB
- Business Services ↔ Redis Cache (via CacheInterceptor)
- Quote/CoinMarketCap/Codex Services → External APIs
- Notification Service → Google Cloud Tasks → TelegramService → Telegram API
- Python Simulator → can read from DB or call API (optional path)
- Developer Scripts → read entities → generate ERD / seed DB

##### Architectural Patterns and Principles
- Modular Monolith: NestJS modules encapsulate bounded contexts.
- Event-driven ingestion: dedicated modules per blockchain event.
- Repository pattern via TypeORM.
- Separation of read (v1 analytics) vs. write (event ingestion) flows.
- Caching with interceptors to improve performance.
- Asynchronous notification workflow via Cloud Tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Clients and Tools
    subgraph "Clients and Tools"
        direction TB
        BrowserCLI["Web/CLI Clients"]:::external
        Simulator["Python Simulator"]:::tools
        ERD["ERD Generator Script"]:::tools
        Seeder["DB Seeder Script"]:::tools
    end

    %% Layer 2: API Gateway
    subgraph "API Layer (NestJS HTTP Server)" 
        direction TB
        MainTS["main.ts"]:::nestjs
        AppModule["AppModule"]:::nestjs
        V1Module["v1 Module"]:::nestjs
        V1Controller["v1 Controller"]:::nestjs
        CacheInterceptor["CacheInterceptor"]:::nestjs
        LoggingMW["LoggingMiddleware"]:::nestjs
    end

    %% Layer 3: Core Modules
    subgraph "Core Business Modules"
        direction TB
        subgraph "Ingestion"
            direction TB
            Harvester["Harvester Module"]:::nestjs
            Deployment["Deployment Module"]:::nestjs
            Events["Event Modules"]:::nestjs
        end
        subgraph "Domain Services"
            direction TB
            Activity["Activity"]:::nestjs
            Pair["Pair"]:::nestjs
            Token["Token"]:::nestjs
            Quote["Quote"]:::nestjs
            TVL["TVL"]:::nestjs
            Volume["Volume"]:::nestjs
            Strategy["Strategy"]:::nestjs
            HistoricQuote["HistoricQuote"]:::nestjs
            Codex["Codex"]:::nestjs
            Updater["Updater"]:::nestjs
        end
        subgraph "Notification"
            direction TB
            NotificationController["NotificationController"]:::nestjs
            NotificationService["NotificationService"]:::nestjs
            TelegramService["TelegramService"]:::nestjs
        end
    end

    %% Layer 4: Data Stores
    subgraph "Data Layer"
        direction TB
        TimescaleDB["TimescaleDB"]:::datastore
        RedisCache["Redis Cache"]:::datastore
    end

    %% Layer 5: External Services
    subgraph "External Integrations"
        direction TB
        RPC["Blockchain RPC & Multicall"]:::external
        CoinGeckoAPI["CoinGecko API"]:::external
        CMCAPI["CoinMarketCap API"]:::external
        CodexAPI["Codex API"]:::external
        CloudTasks["Google Cloud Tasks"]:::external
        TelegramAPI["Telegram Bot API"]:::external
    end

    %% Developer Tools Off to the Side
    BrowserCLI -.HTTP.-> V1Controller
    Simulator -.call/read.-> V1Controller
    Simulator -.read.-> TimescaleDB
    ERD -.reads.-> AppModule
    Seeder -.writes.-> TimescaleDB

    %% API Layer Links
    MainTS --> AppModule
    AppModule --> V1Module
    V1Module --> V1Controller
    V1Controller -->|HTTP| Activity
    V1Controller -->|HTTP| Pair
    V1Controller -->|HTTP| Token
    V1Controller -->|HTTP| Quote
    V1Controller -->|HTTP| TVL
    V1Controller -->|HTTP| Volume
    V1Controller -->|HTTP| Strategy
    V1Controller -->|HTTP| HistoricQuote
    V1Controller -->|HTTP| Codex
    V1Controller -->|HTTP| Updater
    V1Controller -->|HTTP| NotificationController

    CacheInterceptor -.applies.-> V1Controller
    LoggingMW -.applies.-> V1Controller

    %% Core Modules Data Flow
    Harvester -->|JSON-RPC| RPC
    Deployment -->|JSON-RPC| RPC
    Events -->|TypeORM| TimescaleDB

    Activity -->|TypeORM| TimescaleDB
    Pair -->|TypeORM| TimescaleDB
    Token -->|TypeORM| TimescaleDB
    Quote -->|TypeORM| TimescaleDB
    TVL -->|TypeORM| TimescaleDB
    Volume -->|TypeORM| TimescaleDB
    Strategy -->|TypeORM| TimescaleDB
    HistoricQuote -->|TypeORM| TimescaleDB
    Codex -->|TypeORM| TimescaleDB
    Updater -->|TypeORM| TimescaleDB

    Activity <-->|"Redis commands"| RedisCache
    Pair <-->|"Redis commands"| RedisCache
    Token <-->|"Redis commands"| RedisCache
    Quote <-->|"Redis commands"| RedisCache
    TVL <-->|"Redis commands"| RedisCache
    Volume <-->|"Redis commands"| RedisCache
    Strategy <-->|"Redis commands"| RedisCache
    HistoricQuote <-->|"Redis commands"| RedisCache
    Codex <-->|"Redis commands"| RedisCache
    Updater <-->|"Redis commands"| RedisCache

    Quote -->|HTTPS| CoinGeckoAPI
    CMCAPI -->|HTTPS| Quote
    CodexAPI -->|HTTPS| Codex

    NotificationService -->|Cloud Tasks| CloudTasks
    CloudTasks -->|invokes| TelegramService
    TelegramService -->|HTTPS| TelegramAPI

    %% Click Events
    click Simulator "https://github.com/carbon-forked/carbon-backend/tree/main/src/simulator"
    click ERD "https://github.com/carbon-forked/carbon-backend/blob/main/src/scripts/generate-erd.ts"
    click Seeder "https://github.com/carbon-forked/carbon-backend/blob/main/src/scripts/seed.js"
    click MainTS "https://github.com/carbon-forked/carbon-backend/blob/main/src/main.ts"
    click AppModule "https://github.com/carbon-forked/carbon-backend/blob/main/src/app.module.ts"
    click V1Controller "https://github.com/carbon-forked/carbon-backend/blob/main/src/v1/v1.controller.ts"
    click V1Module "https://github.com/carbon-forked/carbon-backend/blob/main/src/v1/v1.module.ts"
    click CacheInterceptor "https://github.com/carbon-forked/carbon-backend/blob/main/src/cache.interceptor.ts"
    click LoggingMW "https://github.com/carbon-forked/carbon-backend/blob/main/src/logging.middleware.ts"
    click Harvester "https://github.com/carbon-forked/carbon-backend/blob/main/src/harvester/harvester.module.ts"
    click Deployment "https://github.com/carbon-forked/carbon-backend/blob/main/src/deployment/deployment.module.ts"
    click Events "https://github.com/carbon-forked/carbon-backend/tree/main/src/events"
    click Activity "https://github.com/carbon-forked/carbon-backend/blob/main/src/activity/activity.module.ts"
    click Pair "https://github.com/carbon-forked/carbon-backend/blob/main/src/pair/pair.module.ts"
    click Token "https://github.com/carbon-forked/carbon-backend/blob/main/src/token/token.module.ts"
    click Quote "https://github.com/carbon-forked/carbon-backend/blob/main/src/quote/quote.module.ts"
    click TVL "https://github.com/carbon-forked/carbon-backend/blob/main/src/tvl/tvl.module.ts"
    click Volume "https://github.com/carbon-forked/carbon-backend/blob/main/src/volume/volume.module.ts"
    click Strategy "https://github.com/carbon-forked/carbon-backend/blob/main/src/strategy/strategy.module.ts"
    click HistoricQuote "https://github.com/carbon-forked/carbon-backend/blob/main/src/historic-quote/historic-quote.module.ts"
    click Codex "https://github.com/carbon-forked/carbon-backend/blob/main/src/codex/codex.module.ts"
    click Updater "https://github.com/carbon-forked/carbon-backend/blob/main/src/updater/updater.module.ts"
    click NotificationController "https://github.com/carbon-forked/carbon-backend/blob/main/src/notification/notification.controller.ts"
    click NotificationService "https://github.com/carbon-forked/carbon-backend/blob/main/src/notification/notification.service.ts"
    click TelegramService "https://github.com/carbon-forked/carbon-backend/blob/main/src/notification/telegram.service.ts"
    click TimescaleDB "https://github.com/carbon-forked/carbon-backend/blob/main/src/typeorm.config.ts"
    click RedisCache "https://github.com/carbon-forked/carbon-backend/blob/main/src/redis/redis.module.ts"
    click RPC "https://github.com/carbon-forked/carbon-backend/tree/main/src/abis"
    click CMCAPI "https://github.com/carbon-forked/carbon-backend/blob/main/src/coinmarketcap/coinmarketcap.module.ts"

    %% Styles
    classDef nestjs fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef datastore fill:#dff0d8,stroke:#3c763d,color:#000;
    classDef external fill:#fcf8e3,stroke:#8a6d3b,color:#000;
    classDef tools fill:#eeeeee,stroke:#999,color:#000;
```
