# trm/spa

End-user single-page app for the TRM platform: race directors, marshals, timekeepers, and (post-Phase 4 of `trm/directus`) public-facing participants. Talks to `trm/directus` for REST/GraphQL + business-plane WebSocket and to `trm/processor` for the live-position WebSocket firehose.

Architectural anchors live in `trm/docs/wiki/`:

- `wiki/entities/react-spa.md` — this service.
- `wiki/concepts/maps-architecture.md` — map subsystem (Phase 2).
- `wiki/synthesis/processor-ws-contract.md` — live-position wire spec (Phase 2).
- `wiki/synthesis/directus-schema-draft.md` — schema this consumes.

Implementation planning lives in `.planning/` — see `.planning/ROADMAP.md`.

## Stack

- **Vite 8 + React 19 + TypeScript 6** — SPA build, no SSR.
- **Tailwind CSS 4** via `@tailwindcss/vite`.
- **shadcn/ui** primitives (slate base, new-york style) — copy-in components owned by us, in `src/ui/primitives/`.
- **TanStack Router + Query** — file-based routes, server-state cache.
- **Zustand** — high-frequency client state (auth, live positions in Phase 2).
- **`@directus/sdk`** — typed Directus client (REST + WS).
- **`zod`** — runtime validation (config, forms, WS protocol).
- **`react-hook-form` + `@hookform/resolvers`** — forms.

## Common scripts

| Command              | Purpose                                       |
| -------------------- | --------------------------------------------- |
| `pnpm dev`           | Start the Vite dev server on `:5173`.         |
| `pnpm build`         | Type-check + production build into `dist/`.   |
| `pnpm preview`       | Serve the built `dist/` for smoke testing.    |
| `pnpm typecheck`     | Type-check only (no build).                   |
| `pnpm lint`          | ESLint over the repo.                         |
| `pnpm format`        | Prettier auto-format.                         |
| `pnpm format:check`  | Prettier check only (CI gate).                |
| `pnpm test`          | Test runner (Phase 3 wires Vitest).           |

## Adding a shadcn primitive

```sh
pnpm dlx shadcn@latest add <component>
```

Components land in `src/ui/primitives/` per `components.json`'s alias config. Edit them freely — they're our code from the moment they land.

## Local dev

The Vite dev proxy (Phase 1.3) routes `/api`, `/ws-business`, `/ws-live` to the appropriate local services so the SPA dev experience matches the stage/prod reverse-proxy topology under one origin. Until 1.3 lands, the SPA runs standalone.

## CI

`.gitea/workflows/build.yml` (lands in Phase 1.9) runs the four gates — typecheck, lint, format:check, build — and publishes a Docker image on push to `main`.