julian
3c7033c3f3
Same-origin dev proxy via Vite's server.proxy:
- /api/* -> ${VITE_DEV_DIRECTUS_URL}/* (Directus REST + GraphQL)
- /ws-business -> ws://.../websocket (Directus business-plane WS)
- /ws-live -> ${VITE_DEV_PROCESSOR_WS_URL} (Processor live WS, Phase 1.5)
WS proxy targets derive ws:// scheme from the http(s) Directus URL.
loadEnv reads VITE_DEV_* overrides; sensible localhost defaults.
tsconfig.app.json: noUncheckedIndexedAccess + noImplicitOverride.
.env.example documents the two override vars; .env.local is gitignored
via the existing *.local pattern.
README "Local dev" section: proxy table + override instructions + port
collision workaround.
Deviation: spec called for .env.dev.example/.env.dev.local but Vite's
dev mode is "development" not "dev", so mode-specific files would be
.env.development.* and Vite wouldn't auto-load .env.dev.local. Switched
to the standard Vite .env.example/.env.local convention. Documented in
the task's Done section.
Plus: backfill 1.2 commit SHA (9918418) in its Done section.
63 lines
3.5 KiB
Markdown
63 lines
3.5 KiB
Markdown
# 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 server (`pnpm dev` on `:5173`) proxies three path namespaces to local services so everything runs same-origin — the same topology stage/prod gets via Traefik, no CORS workarounds needed.
|
|
|
|
| Path | Forwards to | Notes |
|
|
| -------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
|
|
| `/api/*` | `${VITE_DEV_DIRECTUS_URL}/*` | Directus REST + GraphQL. Default `http://localhost:8055`. |
|
|
| `/ws-business` | `${VITE_DEV_DIRECTUS_URL}/websocket` | Directus business-plane WebSocket (auto-derived ws:// scheme). |
|
|
| `/ws-live` | `${VITE_DEV_PROCESSOR_WS_URL}/` | Processor live-position WebSocket. Default `ws://localhost:8081` (Phase 1.5). |
|
|
|
|
Override per-developer by copying `.env.example` to `.env.local` and editing — Vite auto-loads `.env.local` in any mode and the values flow into `vite.config.ts` via `loadEnv`.
|
|
|
|
If the dev port `5173` collides with another Vite app, run with `VITE_PORT=5174 pnpm dev` (or pin a different port in `vite.config.ts`).
|
|
|
|
## 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`.
|