Skip to content

Latest commit

 

History

History
178 lines (141 loc) · 8.27 KB

overview.md

File metadata and controls

178 lines (141 loc) · 8.27 KB

Kurisu - Technical Architecture Design

1. High-Level Architecture

The system follows a Microservices-ready Monolith architecture. While currently designed as a modular monolith for simplicity and learning, the components are loosely coupled to allow future separation into microservices (e.g., separate Data Feeder, Strategy Engine, Execution Service).

Layers

  1. Presentation Layer (Frontend): Interactive dashboard for monitoring, configuration, and agent interaction.
  2. API Gateway / Application Layer (Backend): RESTful API and WebSocket server handling requests, authentication, and orchestration.
  3. Domain Layer (Core Logic):
    • Quant Engine: Strategy execution, backtesting, market data processing.
    • AI Agent Core: LLM integration, memory management, planning.
  4. Infrastructure Layer (Data & External): Databases, Exchange APIs, LLM Providers.

2. Technology Stack

Frontend (User Interface)

  • Framework: Next.js (React) - For server-side rendering and modern routing.
  • Language: TypeScript - For type safety.
  • Styling: Tailwind CSS + ShadcnUI - For rapid, beautiful UI development.
  • State Management: Zustand or TanStack Query.
  • Charts: Lightweight Charts (TradingView) or Recharts.

Backend (API & Core Logic)

  • Framework: FastAPI (Python) - High performance, async support, auto-generated docs.
  • Language: Python 3.10+ - The standard for AI and Quant.
  • Task Queue: Celery + Redis - For asynchronous backtesting tasks and scheduled jobs.
  • Data Handling: Pandas, NumPy.
  • Exchange Interface: CCXT - Unified API for 100+ crypto exchanges.

AI & Agent Framework

  • Orchestration: LangChain or LangGraph - For building stateful agents.
  • LLM Interface: OpenAI API / Anthropic / Ollama (Local).
  • Memory (RAG):
    • Vector Store: ChromaDB or pgvector (PostgreSQL extension).
    • Embeddings: OpenAI Embeddings or HuggingFace (Local).

Database & Storage

  • Relational & Time-Series: PostgreSQL with TimescaleDB extension.
    • Why: Efficiently stores OHLCV market data and structured trade records in one place.
  • Cache: Redis - For real-time market data caching and pub/sub.

3. Module Design

3.1 Data Ingestion Service

  • Responsibilities: Fetch historical data, stream real-time websocket data.
  • Flow: Exchange API -> Normalizer -> TimescaleDB / Redis.

3.2 Strategy Engine (The "Quant" Brain)

  • Responsibilities: Calculate indicators, generate signals (Buy/Sell/Hold).
  • Design: Abstract Base Class Strategy with methods on_tick(), on_candle().
  • Backtesting: Event-driven simulation engine using historical data to validate logic.

3.3 Execution Service

  • Responsibilities: Order management (OMS), position tracking, risk checks.
  • Safety: Implements "Paper Trading" mode vs "Live" mode switch.

3.4 AI Agent Service (The "Reasoning" Brain)

  • Components:
    • Planner: Breaks down user goals (e.g., "Find a low-risk strategy for ETH").
    • Tools: Custom tools to query the database, run backtests, or check news.
    • Critic: Reviews strategy code generated by the LLM for errors or logic flaws.
  • Workflow: User Query -> Planner -> Tool Execution -> Observation -> Reasoning -> Response.

4. Directory Structure

kurisu/
├── frontend/             # Next.js Application
├── backend/              # FastAPI Application
│   ├── app/
│   │   ├── api/          # API Routes (v1)
│   │   ├── core/         # Config, Security, DB Connections
│   │   ├── services/     # Business Logic (MarketData, TradeExec)
│   │   ├── agents/       # AI Agent Logic (Prompts, Tools, Memory)
│   │   ├── strategies/   # Strategy Implementations
│   │   └── models/       # Pydantic & SQL Models
│   └── tests/
├── data/                 # Local data storage (docker volumes)
├── docs/                 # Documentation
└── docker-compose.yml    # Orchestration

5. Development Roadmap

Phase 1: Foundation (Weeks 1-4)

Goal: Establish the core infrastructure and basic functionality.

Week Tasks Deliverables
1 Project setup Repository structure, Docker configuration, Poetry/Node setup
2 Database design PostgreSQL + TimescaleDB schema, migrations, connection pooling
3 Data ingestion CCXT integration, historical data fetcher, WebSocket streams
4 Basic API FastAPI skeleton, health endpoints, database CRUD operations

Milestone: Working data pipeline storing BTC/USDT OHLCV data.

Phase 2: Quant Engine (Weeks 5-8)

Goal: Build the quantitative analysis and backtesting capabilities.

Week Tasks Deliverables
5 Strategy framework Abstract Strategy class, indicator library integration
6 Backtesting engine Event-driven simulator, order matching, slippage model
7 Performance metrics Sharpe ratio, max drawdown, win rate calculations
8 Strategy examples Moving average crossover, RSI strategy, grid trading

Milestone: Complete backtest of a simple strategy with performance report.

Phase 3: AI Integration (Weeks 9-12)

Goal: Integrate LLM capabilities and build the cognitive agent.

Week Tasks Deliverables
9 LLM integration OpenAI/Anthropic/Ollama connectors, prompt templates
10 Agent tools Market data tools, backtest tools, analysis tools
11 Memory system Vector database setup, RAG implementation
12 Agent workflow LangGraph state machine, ReAct pattern implementation

Milestone: Agent can analyze market data and explain trading decisions.

Phase 4: Frontend & UX (Weeks 13-16)

Goal: Build an intuitive user interface for all features.

Week Tasks Deliverables
13 Dashboard Real-time charts, portfolio overview, position monitoring
14 Agent chat Chat interface, message history, code highlighting
15 Backtest lab Strategy configuration, parameter tuning, result visualization
16 Strategy editor Monaco Editor integration, syntax validation, save/load

Milestone: Fully functional web interface for all core features.

Phase 5: Execution & Risk (Weeks 17-20)

Goal: Enable safe paper and live trading capabilities.

Week Tasks Deliverables
17 Paper trading Simulated order execution, virtual portfolio management
18 Risk management Position limits, stop-loss logic, kill-switch
19 Live trading Exchange API integration, order management system
20 Monitoring Real-time alerts, performance tracking, logging

Milestone: Safe paper trading with configurable risk parameters.

Phase 6: Advanced Features (Weeks 21-24)

Goal: Enhance the agent with advanced capabilities.

Week Tasks Deliverables
21 Strategy generation LLM-based code generation, syntax validation
22 Multi-agent Agent collaboration, role-based agents
23 Self-improvement Performance feedback loop, strategy optimization
24 Documentation API docs, user guide, deployment guide

Milestone: Agent can autonomously improve strategies based on feedback.

6. Technical Debt & Considerations

Security

  • All API keys must be stored in environment variables or secure vaults
  • Implement rate limiting on all public endpoints
  • Add authentication for sensitive operations (live trading)

Scalability

  • Design for horizontal scaling from the start
  • Use Redis for caching frequently accessed data
  • Consider read replicas for database as load increases

Testing

  • Unit tests for all core business logic
  • Integration tests for API endpoints
  • End-to-end tests for critical user flows
  • Backtesting validation against known market scenarios

Monitoring

  • Structured logging with correlation IDs
  • Performance metrics collection
  • Error tracking and alerting
  • Database query performance monitoring