docs: rewrite architecture README with module references

2026-06-06 05:51:19 +08:00 · 2025-12-15 16:02:05 +08:00
parent 85cf8c4986
commit 0e4978002b
2 changed files with 253 additions and 1074 deletions
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -1,4 +1,4 @@
-# 🏗️ NOFX Architecture Documentation
+# NOFX Architecture Documentation

 **Language:** [English](README.md) | [中文](README.zh-CN.md)

@@ -6,570 +6,159 @@ Technical documentation for developers who want to understand NOFX internals.

 ---

-## 📋 Overview
+## Overview
+
+NOFX is a full-stack AI trading platform for cryptocurrency and US stock markets:

-NOFX is a full-stack AI trading platform with:
 - **Backend:** Go (Gin framework, SQLite)
 - **Frontend:** React/TypeScript (Vite, TailwindCSS)
- **Architecture:** Microservice-inspired modular design
+- **AI Models:** DeepSeek, Qwen, OpenAI (GPT-5.2), Claude, Gemini, Grok, Kimi
+- **Exchanges:** Binance, Bybit, OKX, Hyperliquid, Aster, Lighter

 ---

-## 📁 Project Structure
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              NOFX Platform                                  │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐│
+│  │  Strategy   │  │  Backtest   │  │   Debate    │  │   Live Trading      ││
+│  │   Studio    │  │   Engine    │  │    Arena    │  │   (Auto Trader)     ││
+│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘│
+│         │                │                │                    │           │
+│         └────────────────┴────────────────┴────────────────────┘           │
+│                                    │                                        │
+│                          ┌─────────▼─────────┐                              │
+│                          │   Core Services   │                              │
+│                          │  - Market Data    │                              │
+│                          │  - AI Providers   │                              │
+│                          │  - Risk Control   │                              │
+│                          └─────────┬─────────┘                              │
+│                                    │                                        │
+│         ┌──────────────────────────┼──────────────────────────┐            │
+│         │                          │                          │            │
+│  ┌──────▼──────┐         ┌─────────▼─────────┐      ┌────────▼────────┐   │
+│  │  Exchanges  │         │     Database      │      │   Frontend UI   │   │
+│  │  (CEX/DEX)  │         │    (SQLite)       │      │   (React SPA)   │   │
+│  └─────────────┘         └───────────────────┘      └─────────────────┘   │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Module Documentation
+
+### Core Modules
+
+| Module | Description | Documentation |
+|--------|-------------|---------------|
+| **Strategy Studio** | Strategy configuration, coin selection, data assembly, AI prompts | [STRATEGY_MODULE.md](STRATEGY_MODULE.md) |
+| **Backtest Engine** | Historical simulation, performance metrics, AI decision replay | [BACKTEST_MODULE.md](BACKTEST_MODULE.md) |
+| **Debate Arena** | Multi-AI collaborative decision making with voting consensus | [DEBATE_MODULE.md](DEBATE_MODULE.md) |
+
+### Module Overview
+
+#### Strategy Module
+Complete strategy configuration system including:
+- Coin source selection (static list, AI500 pool, OI ranking)
+- Market data indicators (K-lines, EMA, MACD, RSI, ATR)
+- Prompt construction (system prompt, user prompt, sections)
+- AI response parsing and decision execution
+- Risk control enforcement
+
+**[Read Full Documentation →](STRATEGY_MODULE.md)**
+
+#### Backtest Module
+Historical trading simulation engine:
+- Multi-symbol, multi-timeframe backtesting
+- AI decision replay with caching
+- Performance metrics (Sharpe, drawdown, win rate)
+- Real-time progress streaming via SSE
+- Checkpoint and resume support
+
+**[Read Full Documentation →](BACKTEST_MODULE.md)**
+
+#### Debate Module
+Multi-AI collaborative decision system:
+- 5 AI personalities (Bull, Bear, Analyst, Contrarian, Risk Manager)
+- Multi-round debate with market context
+- Weighted voting and consensus algorithm
+- Auto-execution to live trading
+- Real-time SSE streaming
+
+**[Read Full Documentation →](DEBATE_MODULE.md)**
+
+---
+
+## Project Structure

 ```
 nofx/
-├── main.go                          # Program entry (multi-trader manager)
-├── config.json                      # ~~Multi-trader config~~ (Now via web interface)
-├── trading.db                       # SQLite database (traders, models, exchanges)
-│
-├── api/                            # HTTP API service
-│   └── server.go                   # Gin framework, RESTful API
-│
-├── trader/                         # Trading core
-│   ├── auto_trader.go              # Auto trading main controller
-│   ├── interface.go                # Unified trader interface
-│   ├── binance_futures.go          # Binance API wrapper
-│   ├── hyperliquid_trader.go       # Hyperliquid DEX wrapper
-│   └── aster_trader.go             # Aster DEX wrapper
-│
-├── manager/                        # Multi-trader management
-│   └── trader_manager.go           # Manages multiple trader instances
-│
-├── config/                         # Configuration & database
-│   └── database.go                 # SQLite operations and schema
-│
-├── auth/                           # Authentication
-│   └── jwt.go                      # JWT token management & 2FA
-│
-├── mcp/                            # Model Context Protocol - AI communication
-│   └── client.go                   # AI API client (DeepSeek/Qwen/Custom)
-│
-├── decision/                       # AI decision engine
-│   ├── engine.go                   # Decision logic with historical feedback
-│   └── prompt_manager.go           # Prompt template system
-│
-├── market/                         # Market data fetching
-│   └── data.go                     # Market data & technical indicators (TA-Lib)
-│   └── api_client.go               # Market data acquisition API
-│   └── websocket_client.go         # Market data acquisition WebSocket interface
-│   └── combined_streams.go         # Market data acquisition: Combined streaming (single link to subscribe to multiple cryptocurrencies)
-│   └── monitor.go                  # Market data cache
-│   └── types.go                    # market structure
-
-├── provider/                       # Data provider management
-│   └── data_provider.go            # AI500 + OI Top data provider
-│
-├── logger/                         # Logging system
-│   └── decision_logger.go          # Decision recording + performance analysis
-│
-├── decision_logs/                  # Decision log storage (JSON files)
-│   ├── {trader_id}/                # Per-trader logs
-│   └── {timestamp}.json            # Individual decisions
-│
-└── web/                            # React frontend
-    ├── src/
-    │   ├── components/             # React components
-    │   │   ├── EquityChart.tsx     # Equity curve chart
-    │   │   ├── ComparisonChart.tsx # Multi-AI comparison chart
-    │   │   └── CompetitionPage.tsx # Competition leaderboard
-    │   ├── lib/api.ts              # API call wrapper
-    │   ├── types/index.ts          # TypeScript types
-    │   ├── stores/                 # Zustand state management
-    │   ├── index.css               # Binance-style CSS
-    │   └── App.tsx                 # Main app
-    ├── package.json                # Frontend dependencies
-    └── vite.config.ts              # Vite configuration
+├── main.go                    # Entry point
+├── api/                       # HTTP API (Gin framework)
+├── trader/                    # Trading execution layer
+├── strategy/                  # Strategy engine
+├── backtest/                  # Backtest simulation engine
+├── debate/                    # Debate arena engine
+├── market/                    # Market data service
+├── mcp/                       # AI model clients
+├── store/                     # Database operations
+├── auth/                      # JWT authentication
+├── manager/                   # Multi-trader management
+└── web/                       # React frontend
+    ├── src/pages/             # Page components
+    ├── src/components/        # Shared components
+    └── src/lib/api.ts         # API client
 ```

 ---

-## 🔧 Core Dependencies
+## Core Dependencies

 ### Backend (Go)

-| Package | Purpose | Version |
-|---------|---------|---------|
-| `github.com/gin-gonic/gin` | HTTP API framework | v1.9+ |
-| `github.com/adshao/go-binance/v2` | Binance API client | v2.4+ |
-| `github.com/markcheno/go-talib` | Technical indicators (TA-Lib) | Latest |
-| `github.com/lib/pq` | PostgreSQL database driver | v1.10+ |
-| `github.com/golang-jwt/jwt/v5` | JWT authentication | v5.0+ |
-| `github.com/pquerna/otp` | 2FA/TOTP support | v1.4+ |
-| `golang.org/x/crypto` | Password hashing (bcrypt) | Latest |
+| Package | Purpose |
+|---------|---------|
+| `gin-gonic/gin` | HTTP API framework |
+| `adshao/go-binance` | Binance API client |
+| `markcheno/go-talib` | Technical indicators |
+| `golang-jwt/jwt` | JWT authentication |

-### Frontend (React + TypeScript)
+### Frontend (React)

-| Package | Purpose | Version |
-|---------|---------|---------|
-| `react` + `react-dom` | UI framework | 18.3+ |
-| `typescript` | Type safety | 5.8+ |
-| `vite` | Build tool | 6.0+ |
-| `recharts` | Charts (equity, comparison) | 2.15+ |
-| `swr` | Data fetching & caching | 2.2+ |
-| `zustand` | State management | 5.0+ |
-| `tailwindcss` | CSS framework | 3.4+ |
-| `lucide-react` | Icon library | Latest |
+| Package | Purpose |
+|---------|---------|
+| `react` | UI framework |
+| `recharts` | Charts and visualizations |
+| `swr` | Data fetching |
+| `zustand` | State management |
+| `tailwindcss` | CSS framework |

 ---

-## 🗂️ System Architecture
+## Quick Links

-### High-Level Overview
-
-```
-┌──────────────────────────────────────────────────────────────────┐
-│                      PRESENTATION LAYER                          │
-│    React SPA (Vite + TypeScript + TailwindCSS)                  │
-│    - Competition dashboard, trader management UI                 │
-│    - Real-time charts (Recharts), authentication pages           │
-└──────────────────────────────────────────────────────────────────┘
-                             ↓ HTTP/JSON API
-┌──────────────────────────────────────────────────────────────────┐
-│                      API LAYER (Gin Router)                      │
-│    /api/traders, /api/status, /api/positions, /api/decisions    │
-│    Authentication middleware (JWT), CORS handling                │
-└──────────────────────────────────────────────────────────────────┘
-                             ↓
-┌──────────────────────────────────────────────────────────────────┐
-│                      BUSINESS LOGIC LAYER                        │
-│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐ │
-│  │ TraderManager    │  │ DecisionEngine   │  │ MarketData     │ │
-│  │ - Multi-trader   │  │ - AI reasoning   │  │ - K-lines      │ │
-│  │   orchestration  │  │ - Risk control   │  │ - Indicators   │ │
-│  └──────────────────┘  └──────────────────┘  └────────────────┘ │
-└──────────────────────────────────────────────────────────────────┘
-                             ↓
-┌──────────────────────────────────────────────────────────────────┐
-│                      DATA ACCESS LAYER                           │
-│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐     │
-│  │ SQLite DB    │  │ File Logger  │  │ External APIs      │     │
-│  │ - Traders    │  │ - Decisions  │  │ - Binance          │     │
-│  │ - Models     │  │ - Performance│  │ - Hyperliquid      │     │
-│  │ - Exchanges  │  │   analysis   │  │ - Aster            │     │
-│  └──────────────┘  └──────────────┘  └────────────────────┘     │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-### Component Diagram
-
-*(Coming soon: detailed component interaction diagram)*
+- [Strategy Module](STRATEGY_MODULE.md) - How strategies work
+- [Backtest Module](BACKTEST_MODULE.md) - How backtesting works
+- [Debate Module](DEBATE_MODULE.md) - How AI debates work
+- [Getting Started](../getting-started/README.md) - Setup guide
+- [FAQ](../faq/README.md) - Frequently asked questions

 ---

-## 📚 Core Modules
-
-### 1. Trader System (`trader/`)
-
-**Purpose:** Trading execution layer with multi-exchange support
-
-**Key Files:**
- `auto_trader.go` - Main trading orchestrator (100+ lines)
- `interface.go` - Unified trader interface
- `binance_futures.go` - Binance API wrapper
- `hyperliquid_trader.go` - Hyperliquid DEX wrapper
- `aster_trader.go` - Aster DEX wrapper
-
-**Design Pattern:** Strategy pattern with interface-based abstraction
-
-**Example:**
-```go
-type ExchangeClient interface {
-    GetAccount() (*AccountInfo, error)
-    GetPositions() ([]*Position, error)
-    CreateOrder(*OrderParams) (*Order, error)
-    // ... more methods
-}
-```
-
---
-
-### 2. Decision Engine (`decision/`)
-
-**Purpose:** AI-powered trading decision making
-
-**Key Files:**
- `engine.go` - Decision logic with historical feedback
- `prompt_manager.go` - Template system for AI prompts
-
-**Features:**
- Chain-of-Thought reasoning
- Historical performance analysis
- Risk-aware decision making
- Multi-model support (DeepSeek, Qwen, custom)
-
-**Flow:**
-```
-Historical Data → Prompt Generation → AI API Call →
-Decision Parsing → Risk Validation → Execution
-```
-
---
-
-### 3. Market Data System (`market/`)
-
-**Purpose:** Fetch and analyze market data
-
-**Key Files:**
- `data.go` - Market data fetching and technical indicators
-
-**Features:**
- Multi-timeframe K-line data (3min, 4hour)
- Technical indicators via TA-Lib:
-  - EMA (20, 50)
-  - MACD
-  - RSI (7, 14)
-  - ATR (volatility)
- Open Interest tracking
-
---
-
-### 4. Manager (`manager/`)
-
-**Purpose:** Multi-trader orchestration
-
-**Key Files:**
- `trader_manager.go` - Manages multiple trader instances
-
-**Responsibilities:**
- Trader lifecycle (start, stop, restart)
- Resource allocation
- Concurrent execution coordination
-
---
-
-### 5. API Server (`api/`)
-
-**Purpose:** HTTP API for frontend communication
-
-**Key Files:**
- `server.go` - Gin framework RESTful API
-
-**Endpoints:**
-```
-GET  /api/traders           # List all traders
-POST /api/traders           # Create trader
-POST /api/traders/:id/start # Start trader
-GET  /api/status            # System status
-GET  /api/positions         # Current positions
-GET  /api/decisions/latest  # Recent decisions
-```
-
---
-
-### 6. Database Layer (`config/`)
-
-**Purpose:** SQLite data persistence
-
-**Key Files:**
- `database.go` - Database operations and schema
-
-**Tables:**
- `users` - User accounts (with 2FA support)
- `ai_models` - AI model configurations
- `exchanges` - Exchange credentials
- `traders` - Trader instances
- `equity_history` - Performance tracking
- `system_config` - Application settings
-
---
-
-### 7. Authentication (`auth/`)
-
-**Purpose:** User authentication and authorization
-
-**Features:**
- JWT token-based auth
- 2FA with TOTP (Google Authenticator)
- Bcrypt password hashing
- Admin mode (simplified single-user)
-
---
-
-## 🔄 Request Flow Examples
-
-### Example 1: Create New Trader
-
-```
-User Action (Frontend)
-    ↓
-POST /api/traders
-    ↓
-API Server (auth middleware)
-    ↓
-Database.CreateTrader()
-    ↓
-TraderManager.StartTrader()
-    ↓
-AutoTrader.Run() → goroutine
-    ↓
-Response: {trader_id, status}
-```
-
-### Example 2: Trading Decision Cycle
-
-```
-AutoTrader (every 3-5 min)
-    ↓
-1. FetchAccountStatus()
-    ↓
-2. GetOpenPositions()
-    ↓
-3. FetchMarketData() → TA-Lib indicators
-    ↓
-4. AnalyzeHistory() → last 20 trades
-    ↓
-5. GeneratePrompt() → full context
-    ↓
-6. CallAI() → DeepSeek/Qwen
-    ↓
-7. ParseDecision() → structured output
-    ↓
-8. ValidateRisk() → position limits, margin
-    ↓
-9. ExecuteOrders() → exchange API
-    ↓
-10. LogDecision() → JSON file + database
-```
-
---
-
-## 📊 Data Flow
-
-### Market Data Flow
-
-```
-Exchange API
-    ↓
-market.FetchKlines()
-    ↓
-TA-Lib.Calculate(EMA, MACD, RSI)
-    ↓
-DecisionEngine (as context)
-    ↓
-AI Model (reasoning)
-```
-
-### Decision Logging Flow
-
-```
-AI Response
-    ↓
-decision_logger.go
-    ↓
-JSON file: decision_logs/{trader_id}/{timestamp}.json
-    ↓
-Database: performance tracking
-    ↓
-Frontend: /api/decisions/latest
-```
-
---
-
-## 🗄️ Database Schema
-
-### Core Tables
-
-**users**
-```sql
- id (INTEGER PRIMARY KEY)
- username (TEXT UNIQUE)
- password_hash (TEXT)
- totp_secret (TEXT)
- is_admin (BOOLEAN)
- created_at (DATETIME)
-```
-
-**ai_models**
-```sql
- id (INTEGER PRIMARY KEY)
- name (TEXT)
- model_type (TEXT) -- deepseek, qwen, custom
- api_key (TEXT)
- api_url (TEXT)
- enabled (BOOLEAN)
-```
-
-**traders**
-```sql
- id (TEXT PRIMARY KEY)
- name (TEXT)
- ai_model_id (INTEGER FK)
- exchange_id (INTEGER FK)
- initial_balance (REAL)
- current_equity (REAL)
- status (TEXT) -- running, stopped
- created_at (DATETIME)
-```
-
-*(More details: database-schema.md - coming soon)*
-
---
-
-## 🔌 API Reference
-
-### Authentication
-
-**POST /api/auth/login**
-```json
-Request: {
-  "username": "string",
-  "password": "string",
-  "totp_code": "string" // optional
-}
-
-Response: {
-  "token": "jwt_token",
-  "user": {...}
-}
-```
-
-### Trader Management
-
-**GET /api/traders**
-```json
-Response: {
-  "traders": [
-    {
-      "id": "string",
-      "name": "string",
-      "status": "running|stopped",
-      "balance": 1000.0,
-      "roi": 5.2
-    }
-  ]
-}
-```
-
-*(Full API reference: api-reference.md - coming soon)*
-
---
-
-## 🧪 Testing Architecture
-
-### Current State
- ⚠️ No unit tests yet
- ⚠️ Manual testing only
- ⚠️ Testnet verification
-
-### Planned Testing Strategy
-
-**Unit Tests (Priority 1)**
-```
-trader/binance_futures_test.go
- Mock API responses
- Test precision handling
- Validate order construction
-```
-
-**Integration Tests (Priority 2)**
-```
- End-to-end trading flow (testnet)
- Multi-trader scenarios
- Database operations
-```
-
-**Frontend Tests (Priority 3)**
-```
- Component tests (Vitest + React Testing Library)
- API integration tests
- E2E tests (Playwright)
-```
-
-*(Testing guide: testing-guide.md - coming soon)*
-
---
-
-## 🔧 Development Tools
-
-### Build & Run
-
-```bash
-# Backend
-go build -o nofx
-./nofx
-
-# Frontend
-cd web
-npm run dev
-
-# Docker
-docker compose up --build
-```
-
-### Code Quality
-
-```bash
-# Format Go code
-go fmt ./...
-
-# Lint (if configured)
-golangci-lint run
-
-# Type check TypeScript
-cd web && npm run build
-```
-
---
-
-## 📈 Performance Considerations
-
-### Backend
- **Concurrency:** Each trader runs in separate goroutine
- **Database:** SQLite (good for <100 traders)
- **API Rate Limits:** Handled per exchange
- **Memory:** ~50-100MB per trader
-
-### Frontend
- **Data Fetching:** SWR with 5-10s polling
- **State:** Zustand (lightweight)
- **Bundle Size:** ~500KB (gzipped)
-
---
-
-## 🔮 Future Architecture Plans
-
-### Planned Improvements
-
-1. **Microservices Split** (if scaling needed)
-   - Separate decision engine service
-   - Market data service
-   - Execution service
-
-2. **Database Migration**
-   - Mysql for production (>100 traders)
-   - Redis for caching
-
-3. **Event-Driven Architecture**
-   - WebSocket for real-time updates
-   - Message queue (RabbitMQ/NATS)
-
-4. **Kubernetes Deployment**
-   - Helm charts
-   - Auto-scaling
-   - High availability
-
---
-
-## 🆘 For Developers
+## For Developers

 **Want to contribute?**
- Read [Contributing Guide](../../CONTRIBUTING.md)
- Check [Open Issues](https://github.com/tinkle-community/nofx/issues)
- Join [Telegram Community](https://t.me/nofx_dev_community)
+- Read the module documentation above
+- Check [Open Issues](https://github.com/NoFxAiOS/nofx/issues)
+- Join our community

-**Need clarification?**
- Open a [GitHub Discussion](https://github.com/tinkle-community/nofx/discussions)
- Ask in Telegram
+**Repository:** https://github.com/NoFxAiOS/nofx

 ---

-## 📚 Related Documentation
-
- [Getting Started](../getting-started/README.md) - Setup and deployment
- [Contributing](../../CONTRIBUTING.md) - How to contribute
- [Community](../community/README.md) - Bounties and recognition
-
---
-
-[← Back to Documentation Home](../README.md)
+[← Back to Documentation](../README.md)