boki/stock-bot
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
stock-bot/CLAUDE.md

6.8 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Package Manager: Bun (v1.1.0+)

Build & Development:

  • bun install - Install dependencies
  • bun run dev - Start all services in development mode (uses Turbo)
  • bun run build - Build all services and libraries
  • bun run build:libs - Build only shared libraries
  • ./scripts/build-all.sh - Custom build script with options

Testing:

  • bun test - Run all tests
  • bun run test:libs - Test only shared libraries
  • bun run test:apps - Test only applications
  • bun run test:coverage - Run tests with coverage

Code Quality:

  • bun run lint - Lint TypeScript files
  • bun run lint:fix - Auto-fix linting issues
  • bun run format - Format code using Prettier
  • ./scripts/format.sh - Format script

Infrastructure:

  • bun run infra:up - Start database infrastructure (PostgreSQL, QuestDB, MongoDB, Dragonfly)
  • bun run infra:down - Stop infrastructure
  • bun run infra:reset - Reset infrastructure with clean volumes
  • bun run docker:admin - Start admin GUIs (pgAdmin, Mongo Express, Redis Insight)

Database Setup:

  • bun run db:setup-ib - Setup Interactive Brokers database schema
  • bun run db:init - Initialize database schemas

Architecture Overview

Microservices Architecture with shared libraries and multi-database storage:

Core Services (apps/)

  • data-ingestion - Market data ingestion from multiple providers (Yahoo, QuoteMedia, IB)
  • processing-service - Data cleaning, validation, and technical indicators
  • strategy-service - Trading strategies and backtesting (multi-mode: live, event-driven, vectorized, hybrid)
  • execution-service - Order management and risk controls
  • portfolio-service - Position tracking and performance analytics
  • web-app - React dashboard with real-time updates

Shared Libraries (libs/)

  • config - Environment configuration with Zod validation
  • logger - Loki-integrated structured logging (use getLogger() pattern)
  • http - HTTP client with proxy support and rate limiting
  • cache - Redis/Dragonfly caching layer
  • queue - BullMQ-based job processing with batch support
  • postgres-client - PostgreSQL operations with transactions
  • questdb-client - Time-series data storage
  • mongodb-client - Document storage operations
  • utils - Financial calculations and technical indicators

Database Strategy

  • PostgreSQL - Transactional data (orders, positions, strategies)
  • QuestDB - Time-series data (OHLCV, indicators, performance metrics)
  • MongoDB - Document storage (configurations, raw responses)
  • Dragonfly - Event bus and caching (Redis-compatible)

Key Patterns & Conventions

Library Usage:

  • Import from shared libraries: import { getLogger } from '@stock-bot/logger'
  • Use configuration: import { databaseConfig } from '@stock-bot/config'
  • Logger pattern: const logger = getLogger('service-name')

Service Structure:

  • Each service has src/index.ts as entry point
  • Routes in src/routes/ using Hono framework
  • Handlers/services in src/handlers/ or src/services/
  • Use dependency injection pattern

Data Processing:

  • Raw data → QuestDB via handlers
  • Processed data → PostgreSQL via processing service
  • Event-driven communication via Dragonfly
  • Queue-based batch processing for large datasets

Multi-Mode Backtesting:

  • Live Mode - Real-time trading with brokers
  • Event-Driven - Realistic simulation with market conditions
  • Vectorized - Fast mathematical backtesting for optimization
  • Hybrid - Validation by comparing vectorized vs event-driven results

Development Workflow

  1. Start Infrastructure: bun run infra:up
  2. Build Libraries: bun run build:libs
  3. Start Development: bun run dev
  4. Access UIs:

Important Files & Locations

Configuration:

  • Environment variables in .env files
  • Service configs in libs/config/src/
  • Database init scripts in database/postgres/init/

Key Scripts:

  • scripts/build-all.sh - Production build with cleanup
  • scripts/docker.sh - Docker management
  • scripts/format.sh - Code formatting
  • scripts/setup-mcp.sh - Setup Model Context Protocol servers for database access

Documentation:

  • SIMPLIFIED-ARCHITECTURE.md - Detailed architecture overview
  • DEVELOPMENT-ROADMAP.md - Development phases and priorities
  • Individual library READMEs in libs/*/README.md

Current Development Phase

Phase 1: Data Foundation Layer (In Progress)

  • Enhancing data provider reliability and rate limiting
  • Implementing data validation and quality metrics
  • Optimizing QuestDB storage for time-series data
  • Building robust HTTP client with circuit breakers

Focus on data quality and provider fault tolerance before advancing to strategy implementation.

Testing & Quality

  • Use Bun's built-in test runner
  • Integration tests with TestContainers for databases
  • ESLint for code quality with TypeScript rules
  • Prettier for code formatting
  • All services should have health check endpoints

Model Context Protocol (MCP) Setup

MCP Database Servers are configured in .vscode/mcp.json for direct database access:

  • PostgreSQL MCP Server: Provides read-only access to PostgreSQL database

    • Connection: postgresql://trading_user:trading_pass_dev@localhost:5432/trading_bot
    • Package: @modelcontextprotocol/server-postgres

  • MongoDB MCP Server: Official MongoDB team server for database and Atlas interaction

    • Connection: mongodb://trading_admin:trading_mongo_dev@localhost:27017/stock?authSource=admin
    • Package: mongodb-mcp-server (official MongoDB JavaScript team package)

Setup Commands:

  • ./scripts/setup-mcp.sh - Setup and test MCP servers
  • bun run infra:up - Start database infrastructure (required for MCP)

Usage: Once configured, Claude Code can directly query and inspect database schemas and data through natural language commands.

Environment Variables

Key environment variables (see .env example):

  • NODE_ENV - Environment (development/production)
  • DATA_SERVICE_PORT - Port for data service
  • DRAGONFLY_HOST/PORT - Cache/event bus connection
  • Database connection strings for PostgreSQL, QuestDB, MongoDB

Monitoring & Observability

  • Logging: Structured JSON logs to Loki
  • Metrics: Prometheus metrics collection
  • Visualization: Grafana dashboards
  • Queue Monitoring: Bull Board for job queues
  • Health Checks: All services expose /health endpoints