mirror of
https://github.com/Sea-Haven-Industries/shoc-frontend-new.git
synced 2026-09-30 06:53:12 +00:00
c68d47af7b
* chore: upgrade frontend application dependencies * chore: upgrade frontend infrastructure dependencies * fix: align lockfiles with CI npm * fix: preserve ky error semantics * fix: sanitize timeout error message
80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# 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`).
|