Skip to content

architecture.md

Latest commit

 

History

History
105 lines (94 loc) · 5.7 KB

architecture.md

File metadata and controls

105 lines (94 loc) · 5.7 KB

DCC Token Scanner Bot — Architecture

Overview

A production-grade Telegram-native token intelligence platform for the DecentralChain ecosystem. Users scan token/asset IDs, inspect analytics, deployer history, wallet activity, pools, liquidity, swaps, risk scores, trending tokens, and group alpha caller performance — all inside Telegram.

High-Level Architecture

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│  Telegram    │     │  Telegram   │     │   Admin      │
│  Bot         │     │  Mini App   │     │   Console    │
│  (Telegraf)  │     │  (Next.js)  │     │   (Next.js)  │
└──────┬───────┘     └──────┬──────┘     └──────┬───────┘
       │                    │                    │
       └────────────┬───────┴────────────────────┘
                    │
            ┌───────▼────────┐
            │  Scanner API   │
            │  (Fastify)     │
            └───────┬────────┘
                    │
       ┌────────────┼────────────────────┐
       │            │                    │
┌──────▼──┐  ┌─────▼──────┐  ┌──────────▼──────┐
│ Market   │  │   Risk     │  │  Chart          │
│ Data Svc │  │   Engine   │  │  Service        │
└──────┬───┘  └─────┬──────┘  └──────────┬──────┘
       │            │                    │
       └────────────┼────────────────────┘
                    │
            ┌───────▼────────┐
            │  Chain Indexer  │
            │  (node-api-js) │
            └───────┬────────┘
                    │
            ┌───────▼────────┐
            │  DecentralChain│
            │  Node(s)       │
            └────────────────┘

Cross-cutting:
  ┌────────┐  ┌───────┐  ┌────────────┐
  │ Redis  │  │ BullMQ│  │ PostgreSQL │
  └────────┘  └───────┘  └────────────┘

Monorepo Structure

/
├── apps/
│   ├── chain-indexer/         # Real-time block/tx ingestion
│   ├── market-data-service/   # Price, volume, trending computation
│   ├── risk-engine/           # Token risk scoring
│   ├── scanner-api/           # Unified REST/WS API gateway
│   ├── telegram-bot/          # Telegraf-based Telegram bot
│   ├── telegram-miniapp/      # Next.js Telegram Mini App
│   ├── admin-console/         # Admin dashboard (Next.js)
│   ├── alerts-engine/         # User alert processing & delivery
│   └── chart-service/         # OHLCV candle aggregation
│
├── packages/
│   ├── blockchain-client/     # Central DecentralChain adapter layer
│   ├── shared-sdk/            # Shared types, DTOs, event definitions
│   ├── db/                    # Prisma schema, migrations, client
│   ├── config/                # Env loading & validation (Zod)
│   ├── logger/                # Pino-based structured logging
│   ├── telegram-ui/           # Telegram message/keyboard builders
│   └── risk-rules/            # Pluggable risk rule framework
│
├── docker/                    # Dockerfiles per service
├── docker-compose.yml
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── package.json
└── architecture.md

Data Flow

  1. Chain Indexer connects to DecentralChain node via node-api-js, polls/streams new blocks
  2. Parses blocks/txs using marshall, ts-types, transactions libraries
  3. Normalizes into internal events (TOKEN_CREATED, SWAP_EXECUTED, etc.)
  4. Persists to PostgreSQL, publishes to Redis/BullMQ
  5. Market Data Service consumes events, computes rolling metrics, caches in Redis
  6. Risk Engine consumes events + queries DB, produces risk scores per token
  7. Chart Service aggregates swap events into OHLCV candles
  8. Alerts Engine monitors events against user alert rules, delivers via Telegram
  9. Scanner API serves all data to consumers (bot, miniapp, admin)
  10. Telegram Bot handles commands, auto-detects asset IDs, calls Scanner API
  11. Telegram Mini App provides rich UI with charts, holders, risk badges

Key Design Decisions

  • Adapter pattern: All DecentralChain SDK access isolated in blockchain-client
  • Event-driven: Indexer publishes normalized events; downstream services subscribe
  • BigNumber everywhere: No floating-point for token/financial math
  • Idempotent ingestion: Indexer supports replay from any height
  • Pluggable risk rules: Each rule is a self-contained module
  • Redis for hot data: Trending, prices, recent scans all cached
  • BullMQ for jobs: Alert evaluation, metric computation, backfill tasks
  • Zod at boundaries: All API input/output validated with Zod schemas
  • Structured logging: Pino with request tracing across all services
  • Prometheus metrics: Every service exposes /metrics endpoint