How carbon-forked/carbon-backend works
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.