SeaHaven Admin

Vite + React SPA for SeaHaven facility management (work orders, vendor portal, uplifts, and related admin features).

Requirements

• Node.js 20+
• npm 10+

Setup

npm ci
cp .env.example .env

Environment variables

Variable	Description	Default
VITE_API_URL	Ky API prefix (baked into the production build)	/api
VITE_API_TARGET	Dev proxy target for /api (Vite only)	http://localhost:5141

VITE_API_URL is the full API base prefix. Route paths in API_PATHS do not include /api — only this variable supplies it.

• Development: use VITE_API_URL=/api. The Vite dev server proxies /api to VITE_API_TARGET.
• Production: use an absolute URL that ends with /api (e.g. https://api.example.com/api). Absolute URLs without /api will produce broken API requests.

See .env.example and .env.production for reference values.

Scripts

Command	Description
npm run dev	Start Vite dev server on port 3000
npm run build	Type-check and production build to dist/
npm run preview	Preview production build locally
npm test	Run Vitest unit tests
npm run test:watch	Run Vitest in watch mode
npm run lint	ESLint
npm run lint:fix	ESLint with auto-fix
npm run format	Prettier write
npm run format:check	Prettier check (used in CI)

Architecture

New code lives under src/domain/, src/app/, and src/api/ following the IrisLoan conventions documented in docs/ARCHITECTURE_PLAN.md.

CI

GitHub Actions workflow (.github/workflows/ci.yml) runs on push and pull requests:

1. npm run format:check
2. npm run lint
3. npm run build
4. npm test

Local pre-commit hooks (Husky + lint-staged) run ESLint and Prettier on staged files.

Deployment (CI/CD)

The app is hosted on AWS S3 + CloudFront, provisioned by an AWS CDK app local to this repo (infra/cdk/). Deployment runs through the org's reusable GitHub Actions workflow via OIDC (no stored AWS keys):

• Push to dev → .github/workflows/deploy.yml calls the org reusable cd-cdk.yaml, which runs cdk deploy (infra) then scripts/deploy-web.sh (builds the SPA, syncs dist/ to S3, invalidates CloudFront).
• Served on the custom domain dev.seahaven.com; the SPA calls the backend directly over HTTPS at VITE_API_URL (https://api.dev.seahaven.com/api, cross-origin — the backend allows CORS). VITE_API_URL is baked into the build, so it is per-environment.
• First-time provisioning (OIDC provider, CDK bootstrap, first local deploy, the AWS_DEPLOY_ROLE_ARN secret) is a one-time admin task — see infra/cdk/README.md.

Playground (dev/staging only)

A hidden test panel lives at /playground — not linked from any nav; reach it by typing the URL. It's a data/scenario control panel for testers that only calls the app's normal, authenticated API routes — no privileged or structure-bypassing endpoints. It offers a raw request console (any authenticated endpoint), one-click lifecycle recipes (create work order, change status, dispatch, complete/cancel follow-ups, manage users/roles…), and bulk seeding.

Gated by env.isPlaygroundEnabled (see src/lib/env.ts): available on local dev + deployed dev/staging, and 404 in production (fail-safe). Because deployed dev/staging/prod are all production builds, the environment is resolved from VITE_APP_ENV if set, else derived from the API hostname (api.dev. / api.staging.). It requires a logged-in session and drives the real backend API as the current user. Code lives under src/app/playground/.

Development proxy

During npm run dev, requests to /api are proxied to VITE_API_TARGET (see vite.config.ts).