Deployment Spec — trading.boas.dev

Date: 2026-04-16

Status: Approved design — ready for implementation planning

Owner: Plutus (coordinator), Apollo (frontend), Proteus (infrastructure)

Decision Summary

Architecture

                     ┌─────────────────────────────────┐
                     │        Cloudflare Edge           │
                     │                                  │
   Browser ──────────┤  trading.boas.dev ──► CF Pages   │
                     │  api.trading.boas.dev ──► Tunnel │
                     └──────────┬───────────────────────┘
                                │ tunnel
                     ┌──────────▼───────────────────────┐
                     │        Hostinger VPS              │
                     │                                  │
                     │  :8100 FastAPI proxy              │
                     │    └── Alpaca Paper API           │
                     │    └── SQLite (trading.db joins)  │
                     │                                  │
                     │  :5678 n8n (trading-spoke)        │
                     │    └── R2 writes (pipelines)      │
                     └──────────────────────────────────┘

   Data sources:
     Static pages  ──► R2 JSON (fallback: public/data/demo/*.json)
     Live pages    ──► FastAPI proxy (fallback: public/data/demo/*.json)
     Market page   ──► TradingView widgets (always live, no auth)

Frontend — React App

Stack

Already scaffolded at apps/dashboard/:

• Vite 6 + React 19 + TypeScript
• React Router 7 (SPA with client-side routing)
• Recharts (charting)
• Tailwind CSS 3.4
• date-fns

Design System

Apollo's HTML mockups define the visual language. The existing scaffold uses generic Tailwind

classes — this must be replaced with the mockup design system:

• Color tokens: CSS custom properties (--bg-base: #070a0f, etc.)
• Typography: Syne (headings), JetBrains Mono (data), Manrope (body)
• Layout: 220px sidebar + content grid, 52px topbar
• 7 pages total (6 nav items + /market under System section)

The mockups are the source of truth for visual design. React components must match them

pixel-for-pixel in layout, color, and typography.

Reference mockups:

• mockups/portfolio-overview.html (in repo)
• mockups/trade-journal.html (in repo)
• ~/Library/CloudStorage/Dropbox/_DevSync/mockups/trading-dashboard/positions.html
• ~/Library/CloudStorage/Dropbox/_DevSync/mockups/trading-dashboard/strategy.html
• ~/Library/CloudStorage/Dropbox/_DevSync/mockups/trading-dashboard/analytics.html
• ~/Library/CloudStorage/Dropbox/_DevSync/mockups/trading-dashboard/alerts.html
• ~/Library/CloudStorage/Dropbox/_DevSync/mockups/trading-dashboard/market-context.html

Pages

Demo Data Fallback

Each data-fetching hook follows this pattern:

async function fetchWithFallback<T>(url: string, demoPath: string): Promise<T> {
  try {
    const res = await fetch(url)
    if (!res.ok) throw new Error(res.statusText)
    return await res.json()
  } catch {
    const demo = await fetch(demoPath)
    return await demo.json()
  }
}

Demo JSON files live in public/data/demo/ and ship with the build. They contain

realistic placeholder data matching the API response schemas.

Environment Variables

Build & Deploy

cd apps/dashboard
npm install
npm run build          # outputs to dist/
# CF Pages picks up dist/ via git push or wrangler pages deploy

CF Pages project name: trading-dashboard

Custom domain: trading.boas.dev

Build command: cd apps/dashboard && npm install && npm run build

Build output directory: apps/dashboard/dist

SPA routing: add _redirects file or [[redirects]] in wrangler.toml:

/* /index.html 200

Backend — FastAPI Proxy

Already Built (apps/api/main.py)

3 endpoints implemented:

• GET /api/health — health check
• GET /api/account — equity, buying power, cash, portfolio value
• GET /api/positions — all open positions with P&L
• GET /api/orders — recent orders (50)

Needs Completion

Per the FastAPI proxy spec (04_launch/fastapi-proxy-spec.md):

1. GET /api/history — equity curve from Alpaca portfolio history API

- Computed fields: P&L, high watermark, max drawdown

- Query params: period, timeframe

2. Computed fields on /positions — stop_level, target_level, risk_badge

- Requires SQLite join against trade_log table

- Currently returns 0 for stop/target

3. Computed fields on /account — daily P&L, exposure %, drawdown status

- Currently returns raw Alpaca data without enrichment

4. CORS update — add https://trading.boas.dev to allowed origins

5. Error handling — per spec (503 for auth failure, 429 passthrough, 502/504)

6. Env var alignment — use ALPACA_API_KEY_ID / ALPACA_API_SECRET_KEY (nono profile names),

not ALPACA_API_KEY / ALPACA_SECRET_KEY (current code)

Deployment

• VPS port 8100, systemd service
• Cloudflare Tunnel route: api.trading.boas.dev → localhost:8100
• Env vars from nono deploy script (scripts/deploy-trading-war-room-env.sh)

Infrastructure — Proteus Scope

1. CF Pages project — create trading-dashboard project, wire trading.boas.dev CNAME

2. Tunnel route — add api.trading.boas.dev → localhost:8100 to existing CF Tunnel config

3. FastAPI systemd service — create unit file, deploy apps/api/ to VPS

4. R2 public access — configure public read for the plutus-trading bucket (or proxy via Worker)

Work Distribution (War Room)

Not In Scope (This Spec)

• Authentication / CF Access (add later if needed for live-only features)
• WebSocket real-time streaming (polling at 30s is sufficient for Phase 1)
• Order submission through the dashboard (execution goes through war room agents)
• Mobile-native app (responsive web is the target — 375px minimum)
• R2 → React data pipeline for all static pages (R2 writes need credential wiring first — can ship with demo data)