trading/.planning/codebase/STACK.md

Technology Stack

Analysis Date: 2025-02-23

Languages

Primary:

• Python 3.12 - Backend microservices, data processing, model serving
• TypeScript 5.9 - React frontend, type safety
• JavaScript - React components, utilities

Secondary:

• Bash - Docker entrypoints, scripts

Runtime

Environment:

• Python 3.12 runtime (Docker: python:3.12-slim)
• Node.js 20 (Docker: node:20-alpine)

Package Manager:

• pip (Python) with pyproject.toml configuration
• npm (Node) with package.json and package-lock.json
• Lockfile: package-lock.json present for frontend

Frameworks

Core Backend:

• FastAPI 0.110+ - HTTP server for API gateway at services/api_gateway/main.py
• SQLAlchemy 2.0+ with asyncio - ORM for PostgreSQL at shared/db.py
• Alembic 1.13+ - Database migrations in alembic/ directory
• Uvicorn 0.27+ - ASGI server for FastAPI

Frontend:

• React 19.2 - UI framework
• Vite 7.3 - Build tool and dev server
• Tailwind CSS 4.2 - Styling framework
• React Router 7.13 - Client-side routing

Data & State:

• TanStack Query 5.90+ - Server state management for API calls
• Axios 1.13+ - HTTP client for backend communication
• Recharts 3.7 - Charts for portfolio analytics
• TradingView lightweight-charts 5.1 - Professional candlestick charts

Testing:

• pytest 8.0+ - Python test runner with asyncio_mode = "auto"
• pytest-asyncio 0.23+ - Async test support
• pytest-cov 4.1+ - Coverage reporting
• React Testing Library - Frontend component testing (imported but not actively tested)

Build/Dev:

• Ruff 0.3+ - Python linter and formatter (line-length: 120)
• MyPy 1.8+ - Python type checker
• TypeScript Compiler (tsc) - TypeScript compilation
• ESLint 9.39+ - JavaScript/TypeScript linting with React hooks and refresh plugins

Key Dependencies

Critical Backend:

• redis 5.0+ - Message broker via Redis Streams at shared/redis_streams.py
• asyncpg 0.29+ - PostgreSQL async driver (via SQLAlchemy)
• pydantic 2.0+ - Data validation and settings management at shared/config.py
• pydantic-settings 2.0+ - Environment-based configuration

Machine Learning & NLP:

• transformers 4.38+ - FinBERT model for sentiment analysis at services/sentiment_analyzer/analyzers/finbert.py
• torch 2.2+ - PyTorch runtime for transformers
• ollama 0.1+ - Local LLM inference client (fallback analyzer) at services/sentiment_analyzer/analyzers/ollama_analyzer.py

News & Data Sources:

• feedparser 6.0+ - RSS feed parsing at services/news_fetcher/main.py
• praw 7.7+ - Reddit API client (blocking)
• asyncpraw 7.7+ - Async Reddit API client for non-blocking Reddit fetches
• httpx 0.27+ - Async HTTP client for web requests

Brokerage Integration:

• alpaca-py 0.21+ - Alpaca trading API client at shared/broker/alpaca_broker.py and services/market_data/main.py
  • Provides: Order management, position tracking, market data (bars), account info
  • Used by: Trade executor, market data service, API gateway portfolio sync

Authentication & Security:

• webauthn 2.0+ - WebAuthn/passkey registration and verification at services/api_gateway/auth/routes.py
• PyJWT 2.8+ with crypto support - JWT token creation/verification at services/api_gateway/auth/jwt.py

Observability:

• opentelemetry-sdk 1.20+ - Metrics collection framework
• opentelemetry-exporter-prometheus 0.45b+ - Prometheus metrics exporter
• opentelemetry-api 1.20+ - Telemetry instrumentation
• prometheus-client - HTTP metrics server (imported in shared/telemetry.py)

Data Processing:

• numpy 1.26+ - Numeric operations for backtester
• pandas 2.2+ - Time series data manipulation
• pytz 2024.1+ - Timezone support for market data

Utilities:

• websockets 12.0+ - WebSocket support for real-time APIs (in api_gateway optional-dependencies)

Configuration

Environment:

• Pydantic BaseSettings with TRADING_ prefix for all environment variables
• Service-specific config classes extend BaseConfig at:
  • services/sentiment_analyzer/config.py - FinBERT threshold, Ollama host
  • services/news_fetcher/config.py - RSS feeds, Reddit credentials
  • services/trade_executor/config.py - Risk limits, Alpaca credentials
  • services/api_gateway/config.py - JWT settings, CORS, WebAuthn RP
  • services/market_data/config.py - Watchlist, bar timeframe, poll intervals

Configuration File:

• .env - Runtime environment variables (not tracked, example: .env.example)
• pyproject.toml - Project metadata and optional dependency groups:
  • [api] - FastAPI, WebAuthn, JWT
  • [news] - feedparser, praw, asyncpraw, httpx
  • [sentiment] - transformers, torch, ollama
  • [trading] - alpaca-py, pytz
  • [backtester] - numpy, pandas
  • [dev] - pytest, coverage, linters

Database:

• PostgreSQL 16 + TimescaleDB extension (Docker: timescale/timescaledb:latest-pg16)
• Connection: Async with asyncpg driver
• Migrations: Alembic with alembic upgrade head (auto-run at startup)

Cache/Message Broker:

• Redis 7-alpine - In-memory data store
• Streams feature for inter-service messaging (consumer groups)
• Persistent volumes for both PostgreSQL and Redis

Build Configuration

Backend:

• pyproject.toml - Single source of truth for Python dependencies
• Setuptools 70.0+ - Build backend
• Finds packages under: shared*, services*, backtester*, scripts*, tests*

Frontend:

• dashboard/vite.config.ts - Vite configuration with React plugin and Tailwind CSS
• dashboard/tsconfig.json - TypeScript configuration (references app and node configs)
• Build: npm run build produces static files served by Nginx

Docker:

• docker/Dockerfile.service - Multi-stage build for all Python services
  • Stage 1: Builder installs dependencies via pip
  • Stage 2: Runtime with slim Python image
• docker/Dockerfile.dashboard - Multi-stage Node+Nginx build
  • Stage 1: Node 20 builds Vite app
  • Stage 2: Nginx serves static files
• docker-compose.yml - Orchestrates: PostgreSQL, Redis, 7 microservices, dashboard

Platform Requirements

Development:

• Python 3.12 with venv or virtualenv
• Node.js 20+ with npm
• Docker & Docker Compose (for integration tests and full-stack deployment)
• Optional: Ollama (local LLM, defaults to http://localhost:11434)

Production:

• Docker and Docker Compose
• PostgreSQL 16+ (external managed service or container)
• Redis 7+ (external managed service or container)
• Environment variables set via .env file or container environment
• Optional: External Ollama service for sentiment fallback

---

Stack analysis: 2025-02-23