Holocron

Mission operations console for a fictional deep-space hardware provider — yards, docks, and orbital platforms feeding live telemetry from thrusters, life-support racks, power buses, and avionics. Operators triage severity, acknowledge incidents, and hand off work by site and role before a vehicle leaves the pad.

Stack

• React 19 + TypeScript
• Vite
• React Router 7
• TanStack Query
• Tailwind CSS v4
• Zod
• Vitest + Testing Library + MSW
• Playwright
• ESLint + Prettier

Prerequisites

• Node.js 22+ (asdf pin in .tool-versions)
• pnpm 10+

asdf install   # if you use asdf
corepack enable

Quick start

pnpm install
pnpm exec playwright install chromium
pnpm dev

Open the URL Vite prints (usually http://localhost:5173). You should see the Ops Console shell (nav + outlet).

Scripts

Script	Purpose
pnpm dev	Start the Vite dev server
pnpm build	Typecheck and production build
pnpm preview	Preview the production build
pnpm test	Run unit + component tests once
pnpm test:watch	Vitest watch mode
pnpm test:unit	Unit tests only (*.unit.test.ts)
pnpm test:component	Component tests only (*.test.tsx)
pnpm test:coverage	Vitest with V8 coverage
pnpm test:e2e	Playwright end-to-end tests
pnpm test:e2e:ui	Playwright UI mode
pnpm test:all	Unit + component + e2e
pnpm lint	ESLint
pnpm format	Prettier write
pnpm format:check	Prettier check (CI)
pnpm typecheck	TypeScript project references check

Testing workflow

Details: docs/testing-config.md.

Layer	Tooling	Location	What it proves
Unit	Vitest + MSW (node)	src/**/*.unit.test.ts	Pure logic, API client, mappers
Component	Vitest + Testing Library (jsdom)	src/**/*.test.tsx	UI behavior in isolation
E2E	Playwright (Chromium)	e2e/**/*.spec.ts	Real browser flows against the running app

Shared helpers live in src/test/:

• render.tsx — renderWithProviders (Query + Router + UiProvider)
• msw/server.ts — Node MSW server for unit tests
• Browser MSW stays in src/mocks/ for local/dev e2e realism

pnpm test              # fast feedback loop
pnpm test:coverage     # coverage report in coverage/
pnpm test:e2e          # starts Vite automatically
pnpm test:e2e:ui       # debug flows visually

State boundaries

Concern	Home
Server / cache data	TanStack Query
Shell chrome (theme, sidebar, selected site)	Context + useReducer
Shareable filters / site	URL (preferred)
Local interaction	useState

Do not copy server lists into React state “to keep them in sync.” See .cursor/rules/state-boundaries.mdc and the other committed rules under .cursor/rules/ for project defaults.

Public notes live in docs/ (testing setup, API contract drills). The internal phase map is local-only and not published with the repo.

Project structure

src/
  app/           # providers, router, UI context
  api/           # typed fetch client + error mapping
  features/      # sites | assets | alerts | dashboard
  components/    # shared shell / primitives
  lib/           # queryClient factory, utils
  mocks/         # MSW browser handlers
  styles/        # Tailwind entry
  test/          # Vitest setup + render helpers
e2e/             # Playwright specs

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

Author

Created by zanuka (Michael Delucchi)

License

Copyright © 2026 Michael Delucchi. Released under the MIT License.