# ultron-ai-labs/firmament architecture

> Architecture diagram of the GitHub repository ultron-ai-labs/firmament, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ultron-ai-labs/firmament
- Repository: https://github.com/ultron-ai-labs/firmament

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    Frontend["Firmament UI"]:::api

    %% API Layer
    subgraph "API Layer"
        AdminWeb["Admin-Web<br/>(Spring Boot REST API)"]:::api
    end

    %% Business Layer
    subgraph "Business Layer"
        AdminBiz["Admin-Biz<br/>(Services & Orchestration)"]:::biz
        CommonAPI["Common-API<br/>(Shared HTTP client)"]:::service
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        AdminDAL["Admin-DAL<br/>(MongoDB DAOs & Repositories)"]:::dao
        MongoDB["MongoDB"]:::db
    end

    %% Side Services
    subgraph "Support Services"
        ExchangeBinance["Binance Connector"]:::external
        ExchangeOKX["OKX Connector"]:::external
        Indicator["Indicator Engine<br/>(Ta4j)"]:::service
        AIChat["AI Chat Service"]:::external
        Alarm["Alarm Framework"]:::external
    end

    %% External Systems
    subgraph "External Systems"
        ExtBinanceAPI["Binance API"]:::extsys
        ExtOKXAPI["OKX API"]:::extsys
        AIMLModel["AI Model Endpoint"]:::extsys
        DingDing["DingDing"]:::extsys
        Feishu["Feishu"]:::extsys
        WeChat["WeChat"]:::extsys
        Docker["Docker / Deployment"]:::extsys
    end

    %% Connections
    Frontend -->|HTTP REST| AdminWeb
    AdminWeb -->|calls| AdminBiz
    AdminBiz -->|uses| CommonAPI
    AdminBiz -->|fetch market data| ExchangeBinance
    AdminBiz -->|fetch market data| ExchangeOKX
    ExchangeBinance -->|HTTP REST| ExtBinanceAPI
    ExchangeOKX -->|HTTP REST| ExtOKXAPI
    AdminBiz -->|compute indicators| Indicator
    Indicator -->|results| AdminBiz
    AdminBiz -->|decision via| AIChat
    AIChat -->|invoke| AIMLModel
    AdminBiz -->|save orders & logs| AdminDAL
    AdminDAL -->|MongoDB Driver| MongoDB
    AdminBiz -->|trigger alarms| Alarm
    Alarm -->|notify| DingDing
    Alarm -->|notify| Feishu
    Alarm -->|notify| WeChat
    Docker -.->|deployment| AdminWeb
    Docker -.->|deployment| AdminBiz
    Docker -.->|deployment| AdminDAL

    %% Click Events
    click AdminWeb "https://github.com/ultron-ai-labs/firmament/tree/master/admin/admin-web"
    click AdminBiz "https://github.com/ultron-ai-labs/firmament/tree/master/admin/admin-biz"
    click AdminDAL "https://github.com/ultron-ai-labs/firmament/tree/master/admin/admin-dal"
    click ExchangeBinance "https://github.com/ultron-ai-labs/firmament/tree/master/exchange-api/binance"
    click ExchangeOKX "https://github.com/ultron-ai-labs/firmament/tree/master/exchange-api/okx"
    click Indicator "https://github.com/ultron-ai-labs/firmament/tree/master/support/indicator"
    click AIChat "https://github.com/ultron-ai-labs/firmament/tree/master/aichat"
    click Alarm "https://github.com/ultron-ai-labs/firmament/tree/master/alarm"
    click CommonAPI "https://github.com/ultron-ai-labs/firmament/tree/master/common-api"
    click Docker "https://github.com/ultron-ai-labs/firmament/tree/master/Dockerfile"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef biz fill:#90EE90,stroke:#333,stroke-width:1px
    classDef service fill:#98FB98,stroke:#333,stroke-width:1px
    classDef dao fill:#FFA500,stroke:#333,stroke-width:1px
    classDef db fill:#FFD700,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef extsys fill:#E6E6FA,stroke:#333,stroke-width:1px
```
