Skip to content

PR Description - #181

Open
Paul-Orlando wants to merge 6 commits into
ed-donner:mainfrom
Paul-Orlando:feature/multi-agent-architecture
Open

Paul-Orlando wants to merge 6 commits into
ed-donner:mainfrom
Paul-Orlando:feature/multi-agent-architecture

Conversation

@Paul-Orlando

Copy link
Copy Markdown

Multi-Agent Trading Backend Implementation

Overview

Complete implementation of the FinAlly AI trading workstation backend as a final project for the AI Coder: Complete Claude Code & Coding Agents Course.

What's Included

Architecture

  • 5 Specialized Agents:
    • Portfolio Agent: Executes trades, manages positions, calculates P&L
    • Risk Agent: Validates trades, enforces position limits (hard/soft rules)
    • Analyzer Agent: Portfolio analysis, concentration metrics, diversification
    • Watchlist Agent: Manages watched tickers
    • Chat Orchestrator: Routes user queries to appropriate agents

Backend

  • FastAPI application with 7 RESTful endpoints
  • SQLite database with 7 tables (positions, trades, watchlist, chat, snapshots, portfolio_state, agent_logs)
  • LiteLLM integration with OpenRouter/Cerebras for structured LLM responses
  • SSE price streaming from existing market data simulator
  • Comprehensive audit logging for all agent actions

Testing & Quality

  • 87 tests passing (72 existing market tests + 15 new API tests)
  • Lint clean (ruff)
  • Live server verification
  • Mock LLM mode for development/testing (no API costs)

Key Design Decisions

  1. One LLM call per chat turn (Orchestrator only) - deterministic agents for reliability
  2. Batch trade validation - skip rejected, execute approved trades
  3. Hard limits (insufficient cash/shares, max 50% position) vs. soft warnings (>25% position)
  4. Audit logging for compliance and debugging

Files Changed

  • backend/app/main.py - FastAPI routes and startup
  • backend/app/db.py - SQLite layer with schema initialization
  • backend/app/agents/ - 6 agent modules (base, portfolio, risk, analyzer, watchlist, orchestrator, metrics)
  • backend/tests/api/ - End-to-end API tests
  • backend/db/schema.sql - Database schema (7 tables, 10 indexes, seed data)
  • pyproject.toml - Updated dependencies (litellm, pydantic, httpx)

Testing

cd backend
uv sync
pytest  # All 87 tests pass
ruff check app/  # Lint clean
uvicorn app.main:app --reload  # Live server test

Next Steps

  • Frontend scaffolding (Next.js + React)
  • Docker multi-stage build
  • E2E testing with Playwright
  • Cloud deployment

Notes

  • Created feature branch: feature/multi-agent-architecture
  • Backend fully functional and tested
  • Ready for frontend integration

Paul-Orlando and others added 6 commits September 19, 2026 21:26
- Fix: GET endpoints no longer write to database
- Perf: Optimize queries, cache portfolio values, use threadpool for reads
- Duplication: Extract metrics.py, consolidate trade models
- Code quality: Split functions, remove dead code, improve error handling
- All 87 tests pass, lint clean, live server verified

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Watchlist with live price updates via SSE
- Portfolio heatmap and P&L charts
- Trade execution form
- AI chat panel with model integration
- Dark theme (Bloomberg-inspired)
- All API endpoints connected
- Mock data for development

Also gitignore the runtime SQLite database (keep db/.gitkeep), per PLAN.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Node 20: Build Next.js frontend (static export)
- Python 3.12: Run FastAPI backend + serve static frontend
- Volume mount for SQLite persistence
- Reads .env for API keys
- Single container on port 8000

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- scripts/start_mac.sh, start_windows.ps1: build image if needed, run container with
  volume + .env, wait for health, open browser, print instructions
- scripts/stop_mac.sh, stop_windows.ps1: stop and remove container, keep data volume
- Idempotent: safe to run repeatedly (uses 'docker container inspect' so an existing
  image is not mistaken for a container)
- .gitattributes: force LF for *.sh so scripts work when committed from Windows
- docker-compose.yml: fixed volume name so compose and scripts share one database

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- test/e2e/test_full_workflow.spec.ts: 10-step serial workflow (fresh start, price
  streaming + flashes, manual buy, AI chat, AI trade, AI watchlist add, heatmap, sell,
  P&L chart, SSE reconnect)
- Page objects for header, watchlist, trade form, positions, chat, heatmap, P&L chart
- Helpers: trade/chat actions, backend cross-checks, flash MutationObserver, and a
  severable TCP proxy for a real SSE connection drop
- test/docker-compose.test.yml: production image (LLM_MOCK=true, fresh in-memory DB)
  + separate Playwright container; screenshots/traces/videos kept on failure
- Frontend: add data-testid attributes for stable selectors (no behavior change)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Layer 1 (Code): Rate limit chat (15/hr) and trades (20/hr) per IP
- Layer 2 (Provider): Documented OpenRouter spend cap (set manually in the web UI)
- In-memory sliding-window limiter with Railway proxy support
- Returns 429 with retry-after on limit exceeded
- Updated RAILWAY.md with protection documentation
- All 91 tests passing, locally verified 429 responses

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant