How ultron-ai-labs/firmament works
Project Type and Purpose
• This is the backend of “苍穹 (Firmament)”: an AI-driven quantitative trading system.
• It is a modular, full-stack application (backend here) using Spring Boot, MongoDB, real-time exchange data, local indicator computation (Ta4j), AI model decisioning, and multi-channel alarm notifications.
High-Level File Structure Analysis
• Top-level Maven modules:
• admin (core backend):
– admin-web: Spring Boot REST API
– admin-biz: business logic and services
– admin-dal: data access layer (MongoDB DAOs)
• aichat: AI chat service wrapper/proxies for different providers
• alarm: notification framework (DingDing, Feishu, WeChat handlers)
• common-api: shared HTTP client & models
• exchange-api: connectors & parsers for Binance, OKX
• support/indicator: local technical indicator calculations
• Shared config: Dockerfile, code formatter, application.yml, logging.
Key README Insights
• Real-time data ingestion from exchanges → local indicator computation → AI model decision → order/account management
• Admin UI (separate project) communicates via REST to admin-web
• Notifications triggered via alarm module
• AI models plugged in through aichat module
• MongoDB persists orders, strategies, logs, users, etc.
Main Components
a. Frontend (firmament-ui)
b. Backend Layers:
• Admin-Web (SpringBoot API)
• Admin-Biz (Services & Orchestration)
• Admin-DAL (MongoDB DAOs & Repositories)
c. Support Services:
• Exchange Connectors (exchange-api: Binance, OKX)
• Indicator Engine (support/indicator: Ta4j calculations)
• AI Chat Service (aichat: various providers)
• Alarm Framework (alarm: DingDing, Feishu, WeChat)
• Common-API (shared HTTP client)
d. Infrastructure & External Systems:
• MongoDB Database
• External Exchange APIs (Binance, OKX)
• AI Model Endpoints (could be external or local)
• Notification Endpoints (DingDing, Feishu, WeChat)
• Docker / Deployment environment
Relationships & Data Flows
• Frontend → HTTP REST → Admin-Web
• Admin-Web → calls Service layer in Admin-Biz
• Admin-Biz orchestrates:
• fetch market data via exchange-api → indicator engine
• compute indicators → feed to AI Chat Service (aichat)
• receive AI decision → create/update orders via Admin-DAL → MongoDB
• log events → Admin-DAL → MongoDB
• trigger alarms → Alarm module → external notification channels
• Admin-DAL ↔ MongoDB
• Admin-Biz uses Common-API for any internal retryable HTTP calls
Architectural Patterns & Principles
• Layered architecture (Controller → Service → DAO)
• Modularization via Maven multi-module project
• Dependency inversion (Service interfaces in admin-biz, implementations hidden)
• Adapter pattern for exchange connectors, AI providers, alarm handlers
• Asynchronous or scheduled tasks for real-time data and queue-based processing
Essential Elements
• Dependencies and call directions
• External systems (exchanges, notification services)
• Modular boundaries (Maven modules)
• Metrics/storage (e.g., collections in MongoDB: orders, logs, strategies)