shoc-frontend-new/README.md

# SeaHaven Admin

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

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

## 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/`](infra/cdk/README.md)). 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`](infra/cdk/README.md).

## Development proxy

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