docs: map existing codebase
This commit is contained in:
Viktor Barzin
parent
d36ae40df1
commit
bc34c78072
7 changed files with 2003 additions and 0 deletions
169
.planning/codebase/STACK.md
Normal file
169
.planning/codebase/STACK.md
Normal file
|
|
@ -0,0 +1,169 @@
|
|||
# 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*
|
||||
Loading…
Add table
Add a link
Reference in a new issue