Architecture — Technology Stack

Language

Python 3.11+ — standard for financial APIs, quantitative libraries, and LLM orchestration.

API

FastAPI / REST API — asynchronous, with Pydantic models for typed request/response and broker-data validation.

Broker Integration

alpaca-py — stable REST API wrapper for account balances, order execution, and paper-sandbox endpoints. Market bars are pulled from the Alpaca Data API (5-minute OHLCV for the watchlist, e.g. AAPL, NVDA, SPY).

Market Data + Math

Pandas + pandas-ta — computes deterministic technical indicators (14-period RSI, 20/50-period SMA, EMA). Values are reproducible and auditable across runs (rounded floats, no NaNs).

Agent / LLM Layer

Abstracted LLM client factory — a unified interface supporting a cloud provider (OpenAI) and a local Ollama model, switchable via the LLM_PROVIDER environment variable without changing orchestration code. The LLM only emits structured JSON tool calls (place_order, hold); it never executes trades directly.

Job Scheduling

Celery + Celery Beat / Redis — Celery Beat triggers discrete agent decision cycles every 15 minutes during US market hours (guarded by a market-clock is_open check); Redis backs the task queue.

Database

PostgreSQL / SQLAlchemy (async) — relational storage for trades, account equity history, LLM reasoning logs, and audit trails.

Authentication & Secrets

JWT auth + encrypted credential vault — bcrypt-hashed passwords with signed JWT tokens gating protected routes; Alpaca API keys stored with symmetric encryption (Fernet) and decrypted only at runtime for broker calls.

Frontend

Next.js + Tailwind CSS — interactive dashboard (charts via Recharts) showing real-time portfolio value, positions, live agent reasoning feeds, and operator controls (Trigger Now / Kill Switch). A centralized API client injects the JWT bearer token and handles 401s globally.

Testing

PyTest — automated test suite with emphasis on the deterministic safety guardrails (oversized-order, low-cash, and closed-market cases must fail at the guardrail layer).

DevOps

Docker & Docker Compose — multi-container setup (frontend, backend/agent, PostgreSQL, Redis) ensuring identical dev and evaluation environments via docker compose up --build.

CI / CD

GitHub Actions — runs Ruff (lint) and PyTest on every pull request, enforcing a passing suite before merge.