Market Making System - Project Documentation

Generated: January 6, 2026 Project Type: Backend/API (Python FastAPI) Architecture: Microservices-ready with Kubernetes deployment Domain: Financial/Trading System

Overview

The Market Making System is a decision support and controlled automation platform for grid trading strategies. The system monitors cryptocurrency market conditions, classifies market regimes using technical analysis, and provides actionable recommendations while maintaining strict capital preservation principles.

Architecture

System Components

graph TB
    subgraph "API Layer"
        FASTAPI[FastAPI Application]
        HEALTH["/health"]
        METRICS["/metrics/collect"]
    end

    subgraph "Business Logic Layer"
        MC[MetricsCollector]
        RE[RegimeEngine]
        GM[GridManager]
        EI[ExchangeInterface]
    end

    subgraph "Data Layer"
        MH[MetricsHistory]
        CL[ConfigurationLoader]
        CM[CredentialsManager]
    end

    subgraph "External Systems"
        KC[KuCoin API]
        N8N[n8n Automation]
        ESO[External Secrets Operator]
        K8S[Kubernetes]
        MM_DATA[market-maker-data Repository]
    end

    FASTAPI --> MC
    MC --> RE
    MC --> GM
    MC --> EI
    MC --> MH
    MC --> CL
    MC --> CM

    EI --> KC
    N8N --> METRICS
    ESO --> CM
    K8S --> FASTAPI
    MM_DATA --> CL
    MM_DATA --> CM

Component Descriptions

API Layer

FastAPI Application: REST API service built with FastAPI and Uvicorn
Endpoints:
- GET /health: Health check endpoint
- POST /metrics/collect: Webhook for n8n-triggered metrics collection

Business Logic Layer

MetricsCollector: Aggregates system snapshots from all components
RegimeEngine: Analyzes market conditions and classifies regimes (currently stub implementation)
GridManager: Manages grid trading operations (currently stub implementation)
ExchangeInterface: Abstract interface for exchange integrations (implemented for KuCoin)

Data Layer

MetricsHistory: YAML-based storage with Git integration for metrics data
ConfigurationLoader: Loads trading configurations from market-maker-data repository
CredentialsManager: Manages API credentials via External Secrets Operator

Technology Stack

Category	Technology	Version	Purpose
Language	Python	3.11	Core implementation language
Framework	FastAPI	0.104.1	REST API framework
ASGI Server	Uvicorn	0.24.0	Production server
Data Validation	Pydantic	2.5.0	Request/response models
Data Formats	PyYAML	6.0.1	Configuration and metrics storage
HTTP Client	aiohttp	3.9.1	Exchange API communication
Testing	pytest	7.4.3	Unit and integration testing
Code Quality	black, flake8, isort	Latest	Code formatting and linting

Source Code Structure

src/
├── interfaces/           # Abstract interfaces
│   ├── exchange.py       # Exchange operations interface
│   ├── grid_manager.py   # Grid management interface
│   └── regime_engine.py  # Regime analysis interface
├── exchanges/            # Exchange implementations
│   └── kucoin.py         # KuCoin exchange integration
├── grid/                 # Grid trading components
│   ├── manager.py        # Grid operations (stub)
│   ├── configuration_manager.py
│   ├── performance_calculator.py
│   ├── behavior_validator.py
│   └── exchange_behavior_observer.py
├── regime/               # Market regime analysis
│   └── engine.py         # Regime classification (stub)
├── metrics/              # Metrics collection system
│   ├── collector.py      # Main metrics aggregation
│   ├── history.py        # YAML storage with Git
│   └── interfaces.py     # Metrics data models
└── config/               # Configuration management
    ├── loader.py         # Configuration loading
    ├── environment.py    # Environment-specific config
    └── credentials.py    # Secrets management

Key Interfaces

ExchangeInterface

Abstract interface for cryptocurrency exchange operations:

class ExchangeInterface(ABC):
    @abstractmethod
    async def get_account_balance(self) -> AccountBalance:
        """Get account balance information"""
 
    @abstractmethod
    async def get_market_data(self, symbol: str) -> MarketData:
        """Get current market data for symbol"""
 
    @abstractmethod
    async def get_historical_candles(self, symbol: str, interval: str, limit: int) -> List[HistoricalCandle]:
        """Get historical OHLCV data"""
 
    @abstractmethod
    async def get_active_grids(self) -> List[GridInfo]:
        """Get information about active grid trades"""

GridManagerInterface

Interface for grid trading operations:

class GridManagerInterface(ABC):
    @abstractmethod
    async def get_grid_status(self) -> List[GridStatus]:
        """Get status of all active grids"""

RegimeEngineInterface

Interface for market regime analysis:

class RegimeEngineInterface(ABC):
    @abstractmethod
    async def get_current_state(self) -> RegimeState:
        """Get current market regime classification"""

Configuration Management

Environment Configuration

Located in config/ directory - contains environment-specific settings:

Database connections
External service endpoints
Feature flags
Deployment parameters

Market Configuration

Located in separate market-maker-data/ repository:

Trading parameters (system_config_v1.yaml)
Grid configurations
Risk management settings
Exchange-specific parameters

Secrets Management

API credentials managed via External Secrets Operator
Stored in market-maker-data/ repository
Injected into Kubernetes pods at runtime

Infrastructure

Kubernetes Deployment

Service: metrics-service FastAPI application
ConfigMaps: Application configuration
ExternalSecrets: Credential management via ESO
Ingress: API access routing

CI/CD Pipeline

Task: Build automation using Taskfile
Docker: Containerized deployment
Kustomize: Kubernetes manifest management

External Integrations

n8n: Workflow automation for scheduled metrics collection
KuCoin API: Cryptocurrency exchange integration
Git: Version control and metrics data persistence

Development Workflow

Local Development

# Setup environment
task metrics:setup
 
# Run development server
task metrics:dev
 
# Run tests
task metrics:test
 
# Format code
task metrics:format

Infrastructure Operations

# Build and deploy
task infra:build
task infra:apply
 
# Check status
task infra:status
 
# View logs
task infra:logs

API Documentation

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2026-01-06T10:00:00.000Z"
}

Metrics Collection

POST /metrics/collect
Content-Type: application/json
 
{
  "source": "n8n_schedule",
  "trigger_time": "2026-01-06T10:00:00Z"
}

Response:

{
  "status": "success",
  "collection_id": "metrics_20260106_100000",
  "timestamp": "2026-01-06T10:00:00.000Z",
  "data_points_collected": 15,
  "storage_status": "committed",
  "dashboard_updated": true,
  "trigger_source": "n8n_schedule"
}

Testing

Test Structure

tests/
├── test_collector.py     # Metrics collection tests
├── test_history.py       # Metrics storage tests
└── test_*.py            # Additional test files

Test Categories

Unit Tests: Individual component testing
Integration Tests: End-to-end workflow testing
Property Tests: Behavioral verification
Infrastructure Tests: Deployment validation

Current Implementation Status

Completed Features

✅ FastAPI service with health and metrics endpoints
✅ KuCoin exchange integration
✅ YAML-based metrics storage with Git
✅ Kubernetes deployment with ESO
✅ n8n webhook integration
✅ Configuration management separation
✅ Abstract interface architecture

Stub Implementations

⚠️ RegimeEngine: Basic interface, needs technical analysis implementation
⚠️ GridManager: Basic interface, needs grid trading logic implementation

Future Development

Complete regime analysis algorithms
Grid trading execution logic
Advanced risk management
Multi-exchange support
Real-time dashboard enhancements

Dependencies

Core Dependencies

fastapi==0.104.1
uvicorn==0.24.0
pydantic==2.5.0
PyYAML==6.0.1
aiohttp==3.9.1

Development Dependencies

pytest==7.4.3
black==23.11.0
flake8==6.1.0
isort==5.12.0

File Manifest

Source Files

main.py: FastAPI application entry point
src/interfaces/*.py: Abstract interface definitions
src/exchanges/kucoin.py: KuCoin exchange implementation
src/metrics/collector.py: Metrics aggregation logic
src/metrics/history.py: YAML storage implementation
src/config/*.py: Configuration management
src/grid/*.py: Grid trading components (stubs)
src/regime/*.py: Regime analysis components (stubs)

Configuration Files

pyproject.toml: Python project configuration
requirements.txt: Python dependencies
Dockerfile: Container build instructions
Taskfile.yml: Build automation tasks

Infrastructure Files

infra/*.yaml: Kubernetes manifests
infra/Taskfile.yml: Infrastructure automation

Documentation Files

README.md: Project overview
.kiro/specs/regime-management/: Detailed specifications
docs/: Generated project documentation

Techcle Wiki

Explorer

Docs

Market Making System - Project Documentation

Overview

Architecture

System Components

Component Descriptions

API Layer

Business Logic Layer

Data Layer

Technology Stack

Source Code Structure

Key Interfaces

ExchangeInterface

GridManagerInterface

RegimeEngineInterface

Configuration Management

Environment Configuration

Market Configuration

Secrets Management

Infrastructure

Kubernetes Deployment

CI/CD Pipeline

External Integrations

Development Workflow

Local Development

Infrastructure Operations

API Documentation

Health Check

Metrics Collection

Testing

Test Structure

Test Categories

Current Implementation Status

Completed Features

Stub Implementations

Future Development

Dependencies

Core Dependencies

Development Dependencies

File Manifest

Source Files

Configuration Files

Infrastructure Files

Documentation Files

Architecture

Api