Skip to main content

id: architecture

TON Arcana Architecture

Overview​

TON Arcana is a blockchain-based tarot reading platform that combines AI-powered interpretations with TON blockchain integration, delivered through a Telegram bot interface.

Core Technologies​

  • Framework: NestJS (Node.js)
  • Database: PostgreSQL with MikroORM
  • Message Queue: BullMQ
  • API Layer: GraphQL (Apollo Server)
  • Bot Framework: grammY
  • AI Integration: OpenAI, Ollama
  • Blockchain: TON (via TonWeb)

Key Components​

1. Telegram Bot Interface​

  • Location: src/telegram/
  • Features:
    • User interaction handling
    • Token-related commands
    • Reading requests
    • Admin commands

2. Token Management​

  • Location: src/token/
  • Features:
    • TON blockchain interactions
    • Balance tracking
    • Token transfers
    • Push operations

3. Tarot Reading System​

  • Location: src/reading/
  • Components:
    • Reading service
    • Card selection
    • Spread generation
    • AI interpretation

4. AI Integration​

  • Location: src/ai/
  • Features:
    • OpenAI integration
    • Ollama local processing
    • Reading interpretation
    • Response formatting

Infrastructure​

1. Database Management​

  • MikroORM for ORM
  • Migration system
  • Entity management
  • Multi-environment support

2. Queue Management​

  • BullMQ for job processing
  • Bull Board monitoring
  • Worker module
  • Background tasks

NEXT_TASK: Implement comprehensive queue monitoring system with Bull Board integration and worker performance tracking

3. API Layer​

  • GraphQL with Apollo
  • REST endpoints
  • Swagger documentation
  • Type safety

4. Authentication & Security​

  • Basic Auth support
  • Passport integration
  • Environment configuration
  • Access control

Development​

Testing​

  • Jest for unit testing
  • E2E test support
  • Coverage reporting
  • Test environments

Deployment​

  • Dokku configuration
  • Node.js v22 runtime
  • PNPM package manager
  • Environment management

Development Tools​

  • ESLint configuration
  • Prettier formatting
  • TypeScript setup
  • Hot reload support

Common Utilities​

Shared Components (@kaido/utils)​

  • Admin utilities
  • Environment helpers
  • Formatting utilities
  • Example templates

Security​

Access Control​

  • Admin authentication
  • Protected routes
  • Environment-based auth
  • Token validation

Error Prevention​

  • Input validation
  • Rate limiting
  • Safe message handling
  • Error logging