# SHOC Frontend (`shoc-frontend-new`) [![CI](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml/badge.svg?branch=dev)](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml) [![Deploy](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/deploy.yml/badge.svg)](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/deploy.yml) ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white) ![React](https://img.shields.io/badge/React-087EA4?logo=react&logoColor=white) ![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white) ![AWS CDK](https://img.shields.io/badge/AWS_CDK-FF9900?logo=amazonwebservices&logoColor=white) Vite + React SPA for Sea Haven facility management (SHOC): work orders, vendor portal, uplifts, and related admin features. This is the selective rebuild of the legacy SHOC frontend — new code follows the IrisLoan.Admin conventions documented in [`docs/ARCHITECTURE_PLAN.md`](docs/ARCHITECTURE_PLAN.md). - **GitHub:** `Sea-Haven-Industries/shoc-frontend-new` - **Hosted at:** and - **Backend APIs:** matching `api..seahaven.com/api` endpoints, called directly from the browser ## Architecture Static SPA hosting on AWS. CloudFront serves the built `dist/` from a private, versioned S3 bucket; the SPA calls the backend directly over HTTPS at `VITE_API_URL`. The live stacks remain CDK/CloudFormation-owned while the import-first Terraform transfer is rehearsed and reviewed. See [`terraform/README.md`](terraform/README.md). ```mermaid graph LR U[Browser] -->|HTTPS dev.seahaven.com| CF[CloudFront] CF -->|OAC| S3[S3 seahaven-shoc-frontend-dev] CF -.->|viewer-request fn| FN[SPA rewrite → /index.html] U -->|HTTPS api.dev.seahaven.com/api CORS| API[SHOC backend API] GH[Manual GitHub deployment] -->|OIDC| ROLE[Environment deploy role] ROLE -->|content publish + invalidation| S3 ``` Frontend stack: React 19, TypeScript, Vite, Tailwind CSS 4 + MUI, TanStack Query, React Router (via `@generouted/react-router`), React Hook Form + Zod, Ky HTTP client. Source layout: `src/api/`, `src/domain/`, `src/app/` (see the architecture plan for the keep/discard migration matrix). ## AWS Resources Stacks **`shoc-frontend-dev`** and **`shoc-frontend-staging`** are currently CDK-owned in account `396287094661`, region `us-east-1`. They are defined in [`infra/cdk/lib/frontend-stack.ts`](infra/cdk/lib/frontend-stack.ts). | Resource | Name | Purpose | | ----------------------- | -------------------------------------------------- | --------------------------------------------------------------------------- | | S3 bucket | `seahaven-shoc-frontend-{dev,staging}` | Private origin (BLOCK_ALL, SSE, versioned; OAC-only reads) | | CloudFront distribution | `E2CWLM1AFB964P` / `E2JDVEZ6EGD49J` | HTTPS static hosting on the matching environment domain | | CloudFront Function | `SpaRewrite` | Viewer-request rewrite of extensionless paths to `/index.html` (deep links) | | IAM role | `githubdeploy-shoc-frontend-new-{dev,staging}` | Environment-scoped GitHub OIDC content deploy role | | Route 53 records | A/AAAA aliases in the dev and staging hosted zones | Point each custom domain at its CloudFront distribution | No Lambdas, queues, or databases — this stack is static hosting only. ## Configuration ### Secrets No Secrets Manager, SSM parameters, AWS access keys, or deploy-role repo secret are used. Content workflows assume their pinned environment role through GitHub OIDC. ### Environment variables (build-time, `VITE_*`) | Variable | Description | Dev value | | ----------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------- | | `VITE_API_URL` | Ky API base prefix, **baked into the build** at `vite build` | `/api` (dev server) / `https://api.dev.seahaven.com/api` (production build) | | `VITE_API_TARGET` | Dev-proxy target for `/api` (Vite dev server only) | `http://localhost:5141` | `VITE_API_URL` supplies the full API prefix — route paths in `API_PATHS` do **not** include `/api`. Absolute values **must end with `/api`**; `vite.config.ts` enforces this via `config/api-url-contract.ts` and fails the build otherwise. See [`.env.example`](.env.example), [`.env.development`](.env.development), and [`.env.production`](.env.production). CDK context for normal dev synthesis lives in [`infra/cdk/cdk.json`](infra/cdk/cdk.json). CDK deployment is no longer part of recurring content releases during the ownership transfer. ## Local Development Requirements: Node.js ≥ 22.22.1 (CI/CD run Node 24), npm 11.16.0 (pinned via `packageManager`). ```bash npm ci cp .env.example .env # then set VITE_API_URL=/api for local dev npm run dev # Vite dev server on port 3000, proxies /api → VITE_API_TARGET ``` The dev proxy expects the `shoc-backend` API at `http://localhost:5141`; override with `VITE_API_TARGET` (e.g. `https://api.dev.seahaven.com` to use the deployed dev API). | Command | Description | | ------------------------------------------ | -------------------------------------------------------- | | `npm run dev` | Start Vite dev server on port 3000 | | `npm run build` | Type-check (`tsc -b`) and production build to `dist/` | | `npm run preview` | Preview the production build locally | | `npm test` / `npm run test:watch` | Vitest unit tests (once / watch) | | `npm run test:e2e` / `npm run test:e2e:ui` | Playwright e2e tests (headless / UI mode) | | `npm run lint` / `npm run lint:fix` | ESLint (check / auto-fix) | | `npm run format` / `npm run format:check` | Prettier (write / check) | | `npm run governance` | Frontend governance checks (godfile + maintainability) | | `npm run verify` | **All gates**: format + lint + build + test + governance | Husky + lint-staged run ESLint and Prettier on staged files at commit; commitlint enforces conventional commit messages. Run `npx tsc --noEmit` (or `npm run build`) before pushing to catch type errors early. ## Contributing - Branch from `dev` with a kebab-case description and a prefix matching the work: `feature/`, `fix/`, `hotfix/`, `chore/`, `docs/`, or `refactor/` (e.g. `feature/vendor-portal-filters`, `chore/sea-haven-branding`). - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org) — commitlint rejects anything else at commit time. - Open PRs against `dev`. Both `dev` and `main` are protected: every PR needs a green CI run and an approving review from a code owner (`@Sea-Haven-Industries/internal-dev`); new pushes dismiss stale approvals. Merged branches are deleted automatically. - Promotion flow during migration: `feature/* → dev`, then an explicitly approved manual dev deployment and verification on `dev.seahaven.com`. Staging promotion and deployment are separate approvals. No production environment exists yet. ## Deployment CI/CD uses OIDC and stores no AWS access keys: - **CI** ([`.github/workflows/ci.yaml`](.github/workflows/ci.yaml)) — on push and PRs to `main`/`dev`, calls `Sea-Haven-Industries/.github` → `ci-typescript-frontend.yaml` (Node 24): format check, lint, build, tests; **and** runs a repo-owned `governance` job that calls `npm run verify` so every gate (including the maintainability ratchets in [`scripts/governance-check.mjs`](scripts/governance-check.mjs)) is guaranteed from this repository. Conventions and gates are documented under [`AGENTS.md`](AGENTS.md), [`QUALITY_GATES.md`](QUALITY_GATES.md), [`ARCHITECTURE_AND_CODE_QUALITY.md`](ARCHITECTURE_AND_CODE_QUALITY.md), and [`REVIEW_AND_PR_FRAMEWORK.md`](REVIEW_AND_PR_FRAMEWORK.md). - **CD** ([`.github/workflows/deploy.yml`](.github/workflows/deploy.yml), [`.github/workflows/deploy-staging.yml`](.github/workflows/deploy-staging.yml), and [`.github/workflows/deploy-tf-poc.yml`](.github/workflows/deploy-tf-poc.yml)) is manual-only during migration. [`scripts/deploy-web.sh`](scripts/deploy-web.sh) publishes to pinned targets, verifies cache/API/routing behavior, retains two release manifests, and restores the prior versioned index on verification failure. The isolated rehearsal, retention mechanism, and deployment prerequisites are documented in [`infra/cdk/README.md`](infra/cdk/README.md). Terraform ownership, HCP configuration, import gates, evidence, and rollback are documented in [`terraform/README.md`](terraform/README.md). Infrastructure changes and ownership transfer remain separate reviewed administrator actions. Content workflows never run `cdk deploy` or Terraform apply. ## Operations - **Verify:** open after a green **Deploy** run in the Actions tab; confirm a deep link (e.g. a work-orders route) loads directly and API calls succeed. - **Logs:** deploy logs live in GitHub Actions (CI + Deploy workflows). There are no CloudWatch application logs — the stack is static hosting; runtime errors surface in the browser and on the backend API's side. - **Common failure modes:** - _Stale content after deploy_ — the CloudFront invalidation step failed or is still propagating; re-run the Deploy workflow or invalidate `/*` manually. - _OIDC `AssumeRole` errors_ — the trust policy is scoped to pushes to `dev` on this repo; deploys from other branches/repos are rejected by design. - _Broken API requests after a build_ — `VITE_API_URL` missing the `/api` suffix or carrying the wrong environment's host (it is baked in at build time). - _CORS errors_ — the backend must allow the frontend origin; CloudFront does not proxy `/api`. - **Deploy workflow is unavailable on an arbitrary ref** — each manual workflow checks its exact branch or protected GitHub environment before assuming AWS credentials. ## Documentation - Infra one-time setup and stack details: [`infra/cdk/README.md`](infra/cdk/README.md) - Rebuild strategy and conventions: [`docs/ARCHITECTURE_PLAN.md`](docs/ARCHITECTURE_PLAN.md); design system and UI docs under [`docs/`](docs/)