---
generated_by: repo-insight
version: 1
created: 2026-03-03
last_updated: 2026-03-03
source_commit: 0d9dffa
coverage: deep
---

# Arbitrage Engine — AI Documentation Index

**Project**: `arbitrage-engine`
**Summary**: Full-stack crypto perpetual futures funding-rate arbitrage monitoring and V5.x CVD/ATR-based short-term trading signal engine. Python/FastAPI backend + Next.js frontend + PostgreSQL + Binance USDC-M Futures.

## Generated Documents

| File | Description |
|------|-------------|
| [00-system-overview.md](./00-system-overview.md) | Project purpose, tech stack, repo layout, entry points, environment variables |
| [01-architecture-map.md](./01-architecture-map.md) | Multi-process architecture, component diagram, signal pipeline data flow, risk guard rules, frontend polling |
| [02-module-cheatsheet.md](./02-module-cheatsheet.md) | Module-by-module index: role, public interfaces, dependencies for all 20 backend + 15 frontend files |
| [03-api-contracts.md](./03-api-contracts.md) | All REST endpoints, auth flows, request/response shapes, error conventions |
| [04-data-model.md](./04-data-model.md) | All PostgreSQL tables, columns, partitioning strategy, storage design decisions |
| [05-build-run-test.md](./05-build-run-test.md) | 构建/运行/部署命令，环境变量，PM2 配置，回测和模拟盘操作 |
| [06-decision-log.md](./06-decision-log.md) | 9 项关键技术决策：PG 消息总线、循环间隔、双写、分区、自研 JWT 等 |
| [07-glossary.md](./07-glossary.md) | 交易术语（CVD/ATR/R/tier）+ 工程术语（paper trading/warmup/circuit break） |
| [99-open-questions.md](./99-open-questions.md) | 11 个未解决问题：users 表双定义冲突、依赖不完整、硬编码密码、无测试等 |

## Recommended Reading Order

1. **Start here**: `00-system-overview.md` — 了解项目定位和结构。
2. **Architecture**: `01-architecture-map.md` — 理解 7+ 进程的交互方式。
3. **Data**: `04-data-model.md` — 任何 DB 相关工作的必读；注意时间戳格式不统一问题。
4. **API**: `03-api-contracts.md` — 前端开发或 API 对接时参考。
5. **Module detail**: `02-module-cheatsheet.md` — 修改特定文件前的参考。
6. **Ops**: `05-build-run-test.md` — 部署和运维操作。
7. **Concepts**: `07-glossary.md` — 不熟悉量化术语时查阅。
8. **Risks**: `99-open-questions.md` — 开始开发前必读，了解已知风险点。

## Coverage Tier
**Deep** — 包含完整的模块签名读取、核心业务模块深度阅读（signal_engine 全文、evaluate_signal 评分逻辑、backtest.py）、构建运行指南、决策日志、术语表和开放问题。

## Key Facts for AI Agents
- **Signal engine is the core**: `backend/signal_engine.py` — change with care; affects all trading modes.
- **Strategy tuning via JSON**: modify `backend/strategies/v51_baseline.json` or `v52_8signals.json` to change signal weights/thresholds without code changes.
- **No ORM**: raw SQL via `asyncpg`/`psycopg2`; schema in `db.py:SCHEMA_SQL`.
- **Auth is custom JWT**: no third-party auth library; hand-rolled HMAC-SHA256 in `auth.py`.
- **`TRADE_ENV=testnet` default**: production use requires explicit env override + strong JWT_SECRET.
- **Dual timestamp formats**: `ts` = Unix seconds, `time_ms`/`entry_ts`/`timestamp_ms` = Unix milliseconds — do not confuse.

## Generation Timestamp
2026-03-03T00:00:00 (UTC)