From ef9703ae124b1209a45f53426bcc3ebe3a2b08aa Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Wed, 15 Jul 2026 14:43:29 -0400 Subject: [PATCH] docs: rewrite README --- README.md | 225 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 159 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index c58d0fcd..9615176a 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,173 @@ -# SeaHaven Admin +# SHOC Frontend (`shoc-frontend-new`) -Vite + React SPA for SeaHaven facility management (work orders, vendor portal, uplifts, and related admin features). +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). -## Requirements - -- Node.js 22.22.1+ -- npm 11.16.0 - -## Setup - -```bash -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`](.env.example) and [`.env.production`](.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) | +- **GitHub:** `Sea-Haven-Industries/shoc-frontend-new` +- **Hosted at:** (dev environment; the only environment today) +- **Backend API:** `https://api.dev.seahaven.com/api` (called directly, cross-origin) — source: `Sea-Haven-Industries/shoc-backend` ## Architecture -New code lives under `src/domain/`, `src/app/`, and `src/api/` following the IrisLoan conventions documented in `docs/ARCHITECTURE_PLAN.md`. +Static SPA hosting on AWS, provisioned by a CDK app local to this repo +([`infra/cdk/`](infra/cdk/README.md)). CloudFront serves the built `dist/` +from a private S3 bucket; the SPA calls the backend directly over HTTPS at +`VITE_API_URL` (no `/api` proxy at the CDN — the backend allows CORS). -## CI +```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[GitHub Actions push to dev] -->|OIDC| ROLE[githubdeploy-shoc-frontend-new-dev] + ROLE -->|cdk deploy + s3 sync + invalidation| S3 +``` -GitHub Actions workflow (`.github/workflows/ci.yml`) runs on push and pull requests: +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). -1. `npm run format:check` -2. `npm run lint` -3. `npm run build` -4. `npm test` +## AWS Resources -Local pre-commit hooks (Husky + lint-staged) run ESLint and Prettier on staged files. +Stack **`shoc-frontend-dev`** — CDK, account `396287094661`, region +`us-east-1`. Defined in [`infra/cdk/lib/frontend-stack.ts`](infra/cdk/lib/frontend-stack.ts). -## Deployment (CI/CD) +| 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 `repo:Sea-Haven-Industries/shoc-frontend-new:ref:refs/heads/dev` | +| Route 53 records | A/AAAA apex alias in zone `dev.seahaven.com` (`Z07671212N75U4YLPWZR8`) | Points the custom domain at CloudFront | -The app is hosted on **AWS S3 + CloudFront**, provisioned by an **AWS CDK** app -local to this repo ([`infra/cdk/`](infra/cdk/README.md)). Deployment runs -through the org's reusable GitHub Actions workflow via **OIDC** (no stored AWS -keys): +No Lambdas, queues, or databases — this stack is static hosting only. -- 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`](infra/cdk/README.md). +## Configuration -## Development proxy +### Secrets -During `npm run dev`, requests to `/api` are proxied to `VITE_API_TARGET` (see `vite.config.ts`). +No Secrets Manager or SSM parameters. The one secret is a **GitHub Actions +repo secret**: + +| Secret | Purpose | +| --------------------- | ----------------------------------------------------------------------------------- | +| `AWS_DEPLOY_ROLE_ARN` | ARN of `githubdeploy-shoc-frontend-new-dev`, passed to the org reusable CD workflow | + +### 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 (domain, certificate ARN, hosted zone) lives in +[`infra/cdk/cdk.json`](infra/cdk/cdk.json) so CI runs `cdk deploy` with no flags. + +## 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) | + +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/`, `bug/`, `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: `feature/* → dev` (auto-deployed and verified on + `dev.seahaven.com`) `→ main` (production promotion — no prod environment + exists yet). + +## Deployment + +CI/CD uses the org's reusable workflows (no stored AWS keys — OIDC only): + +- **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. +- **CD** ([`.github/workflows/deploy.yml`](.github/workflows/deploy.yml)) — on + push to `dev`, calls `Sea-Haven-Industries/.github` → `cd-cdk.yaml`, which + runs `cdk deploy` on `infra/cdk` (stack `shoc-frontend-dev`, `us-east-1`) + and then [`scripts/deploy-web.sh`](scripts/deploy-web.sh): `npm run build`, + `aws s3 sync dist/` (hashed assets immutable, `index.html` never cached), + CloudFront invalidation. Both run as the OIDC deploy role. + +One-time provisioning (OIDC provider, CDK bootstrap, first local deploy, +setting `AWS_DEPLOY_ROLE_ARN`) is documented in +[`infra/cdk/README.md`](infra/cdk/README.md). + +Manual deploy (emergency/reference only — needs credentials for the +external-dev AWS account; the normal path is push to `dev`): + +```bash +cd infra/cdk && npx cdk deploy +STACK_NAME=shoc-frontend-dev AWS_REGION=us-east-1 bash scripts/deploy-web.sh +``` + +## 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`. +- **CI and CD both fire on push to `dev` in parallel** — a red-CI commit still + deploys (matches the org's push-time-CD model; gating deploy on CI is known + follow-up work). + +## 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/)