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.

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

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. It reuses http://127.0.0.1:5201 when the admin dev server is already running; otherwise it starts pnpm frontend:dev:admin.

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.