Velocity GP

Velocity GP is a TypeScript monorepo for a multi-day endurance game experience. It includes a React web app, an Express BFF API, shared API contracts/client packages, and shared UI primitives.

Monorepo Layout

apps/
  web/                  # React + Vite frontend
  api/                  # Express BFF + Prisma

packages/
  api-contract/         # Shared endpoints, schemas, contracts, domain types
  api-client/           # Reusable typed HTTP client
  ui/                   # Shared React UI primitives
  config-typescript/    # Shared TS config presets

docs/                   # Product, architecture, design, and contribution docs

Prerequisites

• Node.js 18+
• npm 9+
• Docker (for local Postgres)

Quick Start

1. Install dependencies:

npm install

2. Create local env files:

cp .env.example .env.local
cp apps/api/.env.example apps/api/.env

3. Start local Postgres:

docker compose up -d

Default local database from docker-compose.yml:

• host: localhost
• port: 16432
• user: postgres
• password: postgres
• db: velocitygp

4. Run Prisma migrations and seed data:

npm run db:deploy
npm run db:seed

5. Start development:

npm run dev

Local URLs:

• Web: http://localhost:5173
• API: http://localhost:4000
• API prefix: /api

Scripts

Root scripts:

• npm run dev - run all workspaces in watch mode
• npm run dev:web - run contract/client/ui + web only
• npm run dev:api - run contract + api only
• npm run build - build all workspaces
• npm run build:web - build web-related workspaces
• npm run build:api - build api-related workspaces
• npm run lint - lint all workspaces
• npm test - run tests across workspaces
• npm run test:api:unit - run API unit tests
• npm run test:api:integration - run API integration tests
• npm run test:web:unit - run web unit tests
• npm run test:web:component - run web component tests
• npm run test:web:e2e - run web end-to-end tests (Playwright)
• npm run format - format apps/web
• npm run db:generate - generate Prisma client
• npm run db:deploy - apply migrations
• npm run db:migrate - create/apply dev migration
• npm run db:studio - open Prisma Studio
• npm run db:seed - seed local database

API Surface (Current)

Health routes:

• GET /health
• GET /ready

API routes are mounted under /api and currently include:

• Events: /events, /events/current, /events/:eventId
• Game: /events/:eventId/players/:playerId/race-state, /events/:eventId/players/:playerId/hazard-status, /events/:eventId/leaderboard
• Players: /players, /players/:playerId
• Teams: /teams, /teams/:teamId, /teams/:teamId/join, /teams/:teamId/members
• Hazards: /hazards/scan, /hazards/:hazardId, /events/:eventId/hazards
• Rescue: /rescue/initiate, /rescue/:playerId/status, /rescue/:playerId/complete
• Scans: /events/:eventId/scans
• Admin (guarded by requireAdmin): /admin/session, /admin/events/:eventId/race-control, /admin/events/:eventId/teams/:teamId/pit-control, /admin/users/:userId/helios-role, /admin/events/:eventId/audits

Key Documentation

• Development workflow: DEVELOPMENT.md
• Docs index: docs/README.md
• Product spec: Velocity GP BDD Specifications
• Architecture overview: RepoStructure
• Planned stack direction: Tech Stack Needed
• Observability: observability.md
• Contributing: CONTRIBUTING.md

Contributors

Thank you to everyone who has contributed to Velocity GP.

Neer Patel

Daniel Grant

Ryan Milton

jn-anki

MiloWical

See the full list: Contributors Graph.

Notes

• The API uses shared contracts/schemas from packages/api-contract.
• Env loading for API supports repo-level and package-level .env/.env.local files.
• Do not commit local env files.