Agent Onboarding

Welcome. Read this first; it will make you 10× faster.

What this repo is

TradeMasterAPI — an algorithmic trading platform for individual retail traders. Vision: explore a symbol → backtest a strategy on it → paper-trade that strategy → eventually execute via the user's own broker (Fidelity, Schwab, Alpaca, etc.) with AI assisting on signal + risk + sentiment fusion.

Active epics: - #78 Exploration Platform - #79 Backtesting Lab - #80 AI-Assisted Trading - #81 SDLC + Security

Architecture in 30 seconds

• backend_v2/ — active Flask API, port 5001 (codename: Raptor).
• api/routes/*.py — Flask blueprints registered under /api
• api/services/ — integrations (Alpaca trading, Alpaca market data, chart export)
• db/migrations/ — Raptor's local SQLite migrations (raw SQL). Active for legacy schema only; the SQLite → Postgres migration is in flight per ADR-0093 (docs/architecture/adr/0093-raptor-postgres-migration.md).
• console/ — operator admin app (codename: Antlers' sibling). Postgres + Alembic.
• app/ — Flask blueprints + templates
• migrations/versions/00NN_*.py — Alembic Python migrations. This is where new flag-promotion (B1) migrations go. See adding_a_feature.md §1 for the pattern.
• frontend/trademaster_ui/ — React app, port 3000, proxies /api/* to backend.
• frontend/status-page/ — public status page deployed to status.raxx.app via .github/workflows/deploy-status-page.yml. Contains a placeholder until the React status app ships in #604. No CF Access gate — customer-facing.

Running locally

./start.sh  # boots backend + frontend, checks venv, waits for health

Single smoke check:

./scripts/agent-tools/run_smoke.sh

Credentials

Alpaca paper credentials live in .env at repo root. Never commit .env. If a test needs credentials, use .env.test (gitignored) or mock the Alpaca calls.

Patterns you should follow

1. Surface errors; never silently return mock data. If a backend call fails, let the UI see it. The mock-fallback pattern caused real bugs — see commit history for why it was removed.
2. Real data in backtests. Bars come from Alpaca (api/services/alpaca_market_data_service.py). Do not introduce a random-OHLC generator, ever.
3. Feature-flag WIP. If a change risks shipping half-built, gate it with backend_v2/api/feature_flags.py (#86) + the frontend useFlag hook.
4. Test additions land with tests. pytest for backend (backend_v2/tests/), Jest for frontend (frontend/trademaster_ui/src/**/__tests__/).
5. Respect paper-first gating. Any code path that can submit a live broker order must pass through a paper-first guard. Bypass requires an explicit justification in the PR.

Patterns you should not follow

• Adding a "disable real data" toggle. We removed these — don't reintroduce.
• Hardcoding symbols. The cache is populated from Alpaca /v2/assets at startup (#15 / backend_v2/api/routes/symbols.py).
• Committing secrets. gitleaks will catch you; the CI job security-secrets will block merge.

How to add a feature

See adding_a_feature.md. Short version: 1. Find or create an issue under an epic 2. Branch off main: feature/<kebab-case-name> 3. Build behind a flag if risky 4. Tests alongside code 5. PR with filled-in template 6. Watch CI; address security findings before review

How to respond to a security finding

See security_response.md.

Internal surfaces

Where to ask

• GitHub discussions (when enabled)
• In-issue comments for specific issues
• docs/agents/ — improve these as you go