Dashboard Refactor Plan¶

Date: 2026-05
Branch: feat-dashboard-refactor
Scope: Restructure dashboard/ into a frontend + backend monorepo; replace the single-file index.html with a TanStack Start + React + shadcn/ui application.

Background¶

The existing dashboard is a single static/index.html served by FastAPI. As data coverage and UI requirements grow, this approach limits maintainability and composability. This plan migrates the frontend to a modern React stack while keeping the FastAPI backend in place.

Target Directory Structure¶

dashboard/
├── api/                        # Python backend (moved from root)
│   ├── main.py                 # CORS added; /static mount removed
│   ├── routers/                # + accounts_router.py, audit_router.py
│   ├── budget/
│   ├── db/
│   ├── requirements.txt
│   ├── healthcheck.py
│   └── Dockerfile
├── web/                        # TanStack Start frontend
│   ├── src/
│   │   ├── routes/
│   │   │   ├── __root.tsx      # Root layout: Header + Tab Nav + AutoRefreshBar
│   │   │   ├── index.tsx       # Redirect → /docker
│   │   │   ├── docker.tsx      # Containers + Health Probes + Error Trigger
│   │   │   ├── trading.tsx     # Signals / Orders / Fills / Positions
│   │   │   ├── budget.tsx      # Budget cards + dialog
│   │   │   ├── accounts.tsx    # Accounts + AccountBalanceSnapshot
│   │   │   ├── audit.tsx       # AuditLog full view
│   │   │   └── settings.tsx    # Theme selector (global)
│   │   ├── components/
│   │   │   ├── ui/             # shadcn/ui primitives
│   │   │   ├── StatCard.tsx
│   │   │   ├── DataTable.tsx   # Reusable table with pagination + filters
│   │   │   ├── AutoRefreshBar.tsx
│   │   │   └── ThemeCard.tsx
│   │   ├── lib/
│   │   │   ├── api.ts          # Fetch wrappers (all /api/* routes)
│   │   │   └── theme.ts        # Theme definitions + CSS variable switching
│   │   └── store/
│   │       └── useAutoRefresh.ts   # Zustand store for refresh state
│   ├── app.config.ts
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts          # Dev proxy: /api → http://localhost:8000
└── README.md

Frontend Routes¶

Route	Data Displayed
`/docker`	Container stats (Total / Running / Stopped) + container table + Health Probes + Error Trigger
`/trading`	Stat cards (Signals / Orders / Fills / Buy / Sell) + Signals table + Orders table (expandable Fills) + Positions table
`/budget`	Budget card grid + budget list table + New Budget dialog
`/accounts`	Account list (venue / type / base currency / last sync) + AccountBalanceSnapshot table (total / free / locked, filterable by account)
`/audit`	AuditLog table with severity badge, entity_type / action columns, expandable before/after JSON
`/settings`	4 theme preview cards (Warm Minimal / Dark Terminal / Blue Finance / Light Clean) — select to apply globally

New Backend Endpoints¶

Router	Endpoints
`accounts_router.py`	`GET /api/accounts` — account list `GET /api/accounts/snapshots` — balance snapshots (filter: `account_id`, `currency`)
`audit_router.py`	`GET /api/audit` — audit logs (filter: `strategy_id`, `entity_type`, `action`, `severity`; pagination)

Auto-Refresh¶

AutoRefreshBar component lives in the root layout Header area
Controls: Enable/Disable toggle + interval selector (5 s / 15 s / 30 s / 60 s / 5 min)
State persisted in localStorage
Each data page's useQuery consumes refetchInterval from the useAutoRefresh Zustand store
The header status dot + last-updated timestamp update on every successful fetch

Theme System¶

Four CSS-variable themes defined in lib/theme.ts:

Token	Warm Minimal	Dark Terminal	Blue Finance	Light Clean
`--bg`	`#f5f3ee`	`#0d1117`	`#f0f4ff`	`#ffffff`
`--accent`	`#3d5af1`	`#39d353`	`#1a56db`	`#6366f1`

Selected theme stored in localStorage and applied via document.documentElement CSS variable injection.

Tech Stack¶

Layer	Technology
Frontend framework	TanStack Start (Vite + React 19)
Routing	TanStack Router (file-based)
Data fetching	TanStack Query v5 (`refetchInterval`)
Global state	Zustand (auto-refresh + theme)
UI components	shadcn/ui (Radix primitives)
Styling	TailwindCSS v4 + CSS variable themes
Icons	Lucide React
Backend	FastAPI (unchanged, +2 routers)
Dev proxy	Vite `/api → :8000`