Frontend Local Development

Status: P14 updated

The new frontend platform is scoped to go-platform/. Do not edit the legacy root apps/ or root packages/ trees for this platform.

Install

cd go-platform
pnpm install

Environment

cp .env.frontend.example .env.local

Each app reads:

VITE_API_BASE_URL=http://localhost:8085
VITE_APP_ENV=local

Frontend apps must call the Go API Gateway/BFF through VITE_API_BASE_URL. They must not call individual Go microservices directly.

Use http://localhost:8085 for the normal local Gateway. Isolated route proof may use a disposable loopback Gateway in :18000-:18999; it is not a deployed route promotion. Cloudflare v2-dev is different: its Pages manifest pins the build origin to https://hoctapaz.com and records bundle provenance before a deploy can use --skip-build.

Persistent Local Services

Run the Docker service stack under the fixed hoctapaz-dev Compose project so it can be inspected independently of the terminal that started it:

make dev-live-up      # build and start services in the background
make dev-live-status  # inspect service containers and published ports
make dev-live-logs    # follow service logs
make dev-live-down    # stop only the hoctapaz-dev service containers

The local API Gateway is http://127.0.0.1:8085; check readiness at http://127.0.0.1:8085/readyz. dev-live-down does not stop separately run Vite frontend processes.

make dev-live-* also loads deploy/docker-compose.local-auth.yml, which uses the local-only routes.auth-native-dev-example.json table so the five frontend login forms can use IAM through Gateway. The baseline deploy/gateway/routes.json stays legacy-proxied for IAM/Profile cutover and rollback guards; this local override is not default-route promotion evidence.

Dev Servers

make frontend-dev-admin    # http://127.0.0.1:5201
make frontend-dev-teacher  # http://127.0.0.1:5202
make frontend-dev-student  # http://127.0.0.1:5203
make frontend-dev-parent   # http://127.0.0.1:5204
make frontend-dev-staff    # http://127.0.0.1:5206
make frontend-dev-public   # http://127.0.0.1:5205

To run the five authenticated frontend apps together in one foreground terminal, use:

make frontend-dev-all

Confirm their fixed development ports without changing any process state:

make frontend-dev-status

For the five frontend apps together with every Compose-published Go runtime, use:

make local-dev-status

It checks all local Go runtime readiness endpoints on 8081-8103, including the API Gateway at http://127.0.0.1:8085/readyz. go-formula-docx on 8095 uses its distinct http://127.0.0.1:8095/healthz contract. It does not start, stop, or mutate any process.

Capture an uncached browser baseline for each authenticated app's unauthenticated root-to-login path without restarting the dev servers:

FRONTEND_LOGIN_LATENCY_CONFIRM=local-dev make test-frontend-login-latency

The check uses a clean Chromium context for ports 5201-5204 and 5206, requires 200 plus the expected /login guard, and records FCP and DOM-content loaded timing under output/qa/frontend-login-latency-*/summary.json. It is a local Vite development baseline, not a production or Cloudflare network claim. Use FRONTEND_LOGIN_LATENCY_MAX_FCP_MS and FRONTEND_LOGIN_LATENCY_MAX_DOM_CONTENT_LOADED_MS to tighten the local limits.

Docs Site

The VitePress documentation site also lives under go-platform/ and publishes the API guides, architecture docs, runbooks, QA notes, and OpenAPI contract index.

pnpm docs:dev      # http://127.0.0.1:5210
pnpm docs:build    # output: docs/.vitepress/dist
pnpm docs:preview  # http://127.0.0.1:6210

The public v2-dev docs target is:

https://v2.dev.docs.hoctapaz.com/

Checks

make frontend-typecheck
make frontend-generate-api
make frontend-e2e
make frontend-test
make frontend-lint
make frontend-build

frontend-e2e uses playwright.config.ts and starts six isolated Vite servers by default. It does not reuse the local development ports, so a developer's active app cannot be mistaken for another frontend during a smoke run.

E2E app	Default isolated port
Admin	5301
Teacher	5302
Student	5303
Parent	5304
Public	5305
Staff	5306

Use a different contiguous range when another local process owns that range:

PLAYWRIGHT_FRONTEND_PORT_BASE=5400 pnpm frontend:e2e --project=chromium --reporter=line

PLAYWRIGHT_REUSE_EXISTING_SERVER=1 is an explicit diagnostic-only opt-in. Use it only after confirming that every app is served from the matching port; the normal suite must own and tear down its own servers.

Deployment Shape

Each Vite app builds to its own dist/ directory and can be mapped to a separate Cloudflare Pages project root:

App	Local port	Pages root	Target host
Admin	5201	apps/admin-web	admin.hoctapaz.com
Teacher	5202	apps/teacher-web	teacher.hoctapaz.com
Student	5203	apps/student-web	app.hoctapaz.com
Parent	5204	apps/parent-web	parent.hoctapaz.com
Staff	5206	apps/staff-web	staff.hoctapaz.com
Public	5205	apps/public-web	hoctapaz.com
Docs	5210	docs	docs.hoctapaz.com

The local deployment manifest is deploy/cloudflare/pages.frontend.json. It keeps one Cloudflare Pages project per frontend app plus one VitePress docs project. Vite apps deploy each app's dist/ directory; the docs site deploys docs/.vitepress/dist.

For v2 development deploys, use:

pnpm deploy:cloudflare:pages

The v2-dev Cloudflare target hostnames are documented in docs/runbooks/cloudflare-pages-v2-dev-deploy.md.

Rollback

Stop building/deploying go-platform/apps/*. Legacy frontend production traffic remains on the existing app until explicit route-by-route parity tasks cut over.