mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-09-30 19:43:12 +00:00
69c24c1c2c
* feat(terraform): ship dev content CD through Terraform (SH-300) GitHub uploads immutable release prefixes; Terraform owns live publish. Push-to-dev stays off until TERRAFORM_CONTENT_CD_ENABLED is set. * fix(terraform): align release-plan guard flags and CloudFront verify IAM (SH-300)
204 lines
12 KiB
Markdown
204 lines
12 KiB
Markdown
# SHOC Frontend (`shoc-frontend-new`)
|
|
|
|
[](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/ci.yaml)
|
|
[](https://github.com/Sea-Haven-Industries/shoc-frontend-new/actions/workflows/deploy.yml)
|
|
|
|
|
|
|
|
|
|
|
|
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 environment; the only environment today)
|
|
- **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 using a current/previous origin group;
|
|
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 -->|origin group 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] -->|OIDC upload releases/*| S3
|
|
TF[HCP Terraform shoc-frontend-new-dev] -->|pointer origin_path invalidation| CF
|
|
```
|
|
|
|
Dev hosting and content CD are owned by HCP Terraform (SH-300). Staging still
|
|
uses CloudFormation outputs and `scripts/deploy-web.sh` (SH-287).
|
|
|
|
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 `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 |
|
|
|
|
No Lambdas, queues, or databases — this stack is static hosting only.
|
|
|
|
## Configuration
|
|
|
|
### Secrets
|
|
|
|
No Secrets Manager or SSM parameters. AWS access is OIDC only; the deploy role
|
|
ARNs are deterministic and pinned in the workflows. 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 `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.
|
|
- A PR that changes `terraform/**` may not also change application code (the
|
|
`terraform-isolation` CI job); ship Terraform in its own PR.
|
|
- Promotion flow: `feature/* → dev` (deployed to `dev.seahaven.com` through
|
|
Terraform content CD once `TERRAFORM_CONTENT_CD_ENABLED=true`)
|
|
`→ main` (production promotion — no prod environment exists yet).
|
|
|
|
## 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`/`dev`/`staging`, 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),
|
|
the Terraform gates, and the content-CD guards) 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).
|
|
- **Terraform isolation**
|
|
([`.github/workflows/terraform-isolation.yaml`](.github/workflows/terraform-isolation.yaml))
|
|
— fails a PR that mixes `terraform/**` with application code, so a Terraform
|
|
merge never races a content release for the HCP workspace.
|
|
- **Dev content** ([`.github/workflows/deploy.yml`](.github/workflows/deploy.yml))
|
|
— `workflow_dispatch` on `dev`, and push-to-`dev` when
|
|
`vars.TERRAFORM_CONTENT_CD_ENABLED` is `true` (`paths-ignore: terraform/**`).
|
|
GitHub uploads `releases/<sha>-<run>-<attempt>/` only. Terraform updates
|
|
`.release/current`, both origin paths, and the invalidation action. Verify
|
|
and rollback share `scripts/verify-cloudfront-release.sh`. Every run prints
|
|
a live-state summary.
|
|
- **Staging content**
|
|
([`.github/workflows/deploy-staging.yml`](.github/workflows/deploy-staging.yml))
|
|
— on push to `staging`, unchanged.
|
|
- **Infrastructure** — administrator-run HCP Terraform workspace
|
|
`shoc-frontend-new-dev` ([`terraform/README.md`](terraform/README.md)).
|
|
Staging hosting stays on the existing CloudFormation stack until SH-287.
|
|
|
|
Do not run `scripts/deploy-web.sh` against dev. That script remains the staging
|
|
content publisher only.
|
|
|
|
## Operations
|
|
|
|
- **Verify:** open <https://dev.seahaven.com> after a green **Deploy dev
|
|
content** 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 the `dev` ref
|
|
on this repo; dispatching the workflow from another branch is 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`.
|
|
- **Push-to-`dev` is gated.** Merging to `dev` publishes only when
|
|
`TERRAFORM_CONTENT_CD_ENABLED=true`. Merging a `terraform/**` change queues
|
|
an HCP Terraform run that a human confirms or discards before the next
|
|
content release (see the operational rules in `terraform/README.md`).
|
|
|
|
## Documentation
|
|
|
|
- Dev 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/)
|