shoc-frontend-new/README.md

# SHOC Frontend (`shoc-frontend-new`)

[![CI](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml/badge.svg?branch=main)](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-web.yaml/badge.svg)](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/deploy-web.yaml)
![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)
![Terraform](https://img.shields.io/badge/Terraform-844FBA?logo=terraform&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:** <https://dev.seahaven.com> (dev, deployed from `main`) and
  <https://staging.seahaven.com> (staging, deployed from `vX.Y.Z-staging` tags)
- **Backend API:** `https://api.dev.seahaven.com/api` (called directly, cross-origin) — source: `Sea-Haven-Industries/shoc-backend`

## Architecture

Static SPA hosting on AWS, owned by HCP Terraform
([`terraform/README.md`](terraform/README.md)). CloudFront serves the built
`dist/` from a private S3 bucket at the bucket root;
the SPA calls the backend directly over HTTPS at `VITE_API_URL` (no `/api`
proxy at the CDN — the backend allows CORS).

```mermaid
graph LR
    U[Browser] -->|HTTPS dev.seahaven.com| CF[CloudFront]
    CF -->|OAC bucket root| 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[GitHub Actions] -->|OIDC s3 sync dist/| S3
    TF[HCP Terraform] -->|bucket CloudFront IAM SSM| CF
```

Dev and staging hosting live in `terraform/live/dev` and
`terraform/live/staging`. GitHub `.github/workflows/deploy-web.yaml` syncs
content.

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

HCP workspace **`shoc-frontend-new-dev`** — account `396287094661`, region
`us-east-1`. Defined in [`terraform/live/dev`](terraform/live/dev).

| Resource                | Name                                                                   | Purpose                                                                                   |
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| S3 bucket               | `seahaven-shoc-frontend-dev`                                           | Private origin (BLOCK_ALL, SSE, versioned; OAC-only reads)                                |
| CloudFront distribution | (stack output `DistributionId`)                                        | HTTPS static hosting on `dev.seahaven.com`, ACM `*.seahaven.com`                          |
| CloudFront Function     | `SpaRewrite`                                                           | Viewer-request rewrite of extensionless paths to `/index.html` (deep links)               |
| IAM role                | `githubdeploy-shoc-frontend-new-dev`                                   | GitHub Actions OIDC deploy role, trust scoped to Environment `dev` plus `deploy-web.yaml` |
| Route 53 records        | A/AAAA apex alias in zone `dev.seahaven.com` (`Z07671212N75U4YLPWZR8`) | Points the custom domain at CloudFront                                                    |

No Lambdas, queues, or databases — this stack is static hosting only.

## Configuration

### Secrets

No Secrets Manager. Deploy looks up `/shoc-frontend-new/<env>/deploy/{bucket,distribution-id}`
after assuming `DEPLOY_ROLE_ARN`. AWS access is OIDC only. The one **GitHub Actions
repo secret** is:

| Secret              | Purpose                                                            |
| ------------------- | ------------------------------------------------------------------ |
| `SENTRY_AUTH_TOKEN` | Source-map upload by `scripts/upload-sourcemaps.sh` after a deploy |

### 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).

Pinned hosting constants (domain, certificate ARN, hosted zone) live in
[`terraform/live/dev/main.tf`](terraform/live/dev/main.tf).

## 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`                       | Governance checks (godfile, maintainability, Terraform, CD guards) |
| `npm run verify`                           | **All gates**: format + lint + build + test + governance           |

`npm run governance` needs `terraform` and `python3` on `PATH` for the
Terraform and content-CD gates.

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 `main` 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 `main`. The PR body uses the three-section layout the
  template pre-fills: Summary, Changes and value, Ticket. `main` needs the
  `ci-complete` check and an approving review from a code owner
  (`@Sea-Haven-Industries/internal-dev`); new pushes dismiss stale
  approvals. PRs merge through the merge queue, so a branch does not need to
  be updated with `main` before it merges. Merged branches are deleted
  automatically.
- A change set cannot mix `terraform/` with deployable application files (G13),
  including each queued PR on the merge-group check. Workflow, docs, and
  gate-script changes may travel with either side. `deploy-web.yaml` still
  ignores `terraform/**` so a Terraform-only merge does not sync the bucket.
- Promotion flow: merge to `main` deploys `dev.seahaven.com`. A person cuts
  `vX.Y.Z-staging` for `staging.seahaven.com`. Core `vX.Y.Z` waits until a
  prod distribution exists.

## Deployment

No stored AWS keys — OIDC only. Infrastructure and content deploy separately:

- **CI** ([`.github/workflows/ci.yaml`](.github/workflows/ci.yaml)) — on push
  and PRs to `main`, runs format, lint, build, sharded unit tests, visual
  regression, and `npm run governance` as parallel jobs, then `ci-complete`.
  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).
- **SPA content** ([`.github/workflows/deploy-web.yaml`](.github/workflows/deploy-web.yaml))
  — push to `main` deploys `dev`; a published `vX.Y.Z-staging` release deploys
  `staging`. Syncs `dist/` to the bucket root and invalidates `/*`.
- **Infrastructure** — HCP workspaces `shoc-frontend-new-dev` and
  `shoc-frontend-new-staging` ([`terraform/README.md`](terraform/README.md)).

## Operations

- **Verify:** open <https://dev.seahaven.com> after a green **Deploy Web**
  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_ — CloudFront is still `InProgress` or an edge
    still serves the previous `index.html` hash. Read the live-state summary
    before assuming the site is down.
  - _OIDC `AssumeRole` errors_ — the trust policy is scoped to Environment
    `dev` or `staging` plus `deploy-web.yaml`. A job without `environment:`
    cannot assume the role.
  - _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`.
  - _Non-empty origin path_ — `deploy-web.yaml` refuses to sync until Terraform
    has moved every origin to the bucket root.

## Documentation

- Terraform runbook: [`terraform/README.md`](terraform/README.md)
- Rebuild strategy and conventions: [`docs/ARCHITECTURE_PLAN.md`](docs/ARCHITECTURE_PLAN.md);
  design system and UI docs under [`docs/`](docs/)