Frontend Platform Architecture

Status: P14 updated

Scope

This document defines the new frontend platform inside go-platform/. It does not replace or edit the legacy Next.js frontend under the repository root apps/ directory. Legacy frontend source remains read-only reference while the Go platform gains independent Vite applications that can be migrated behind the API Gateway/BFF over time.

Target Layout

go-platform/
  apps/
    admin-web/
    teacher-web/
    student-web/
    parent-web/
    staff-web/
    public-web/
  packages/
    ui/
    api-client/
    auth-client/
    config/
    types/
    validators/

The existing Go package tree under go-platform/packages/common stays in place. Frontend packages use scoped npm package names and TypeScript path aliases so Go tests and frontend builds remain separate.

Toolchain

• Vite 8.1 for app dev/build. Vite 8 is the stable entrypoint; Rolldown is the bundler layer for the VoidZero direction.
• @vitejs/plugin-react for React Fast Refresh and OXC-backed transforms.
• Vitest 4 projects for monorepo test execution across apps and packages.
• Tailwind CSS through the Vite plugin, with shared shadcn-style primitives exported from packages/ui.
• TanStack Query for gateway request state and query-key ownership.
• Zustand for auth/session state ownership in packages/auth-client.
• OpenAPI-generated API Gateway types in packages/api-client/src/generated.
• Playwright smoke coverage for app-level frontend runtime checks.
• Oxlint for fast JavaScript/TypeScript linting through the OXC toolchain.
• Turborepo for task orchestration across apps and shared packages.
• pnpm workspace for dependency and package ownership.

App Boundaries

App	Audience	Domain
admin-web	Admin, staff	System operations, users, billing, audit, feature maintenance
teacher-web	Teachers	Classes, assignments, question bank, DOCX import, exams
student-web	Students	Dashboard, classes, practice, mock exams, results
parent-web	Parents	Child progress, reports, payments, teacher contact
staff-web	Staff	Support, content review, audit, operations workflows
public-web	Public visitors	Landing, pricing, blog, school introduction

Each app can be built and deployed independently. Shared UI and API behavior must live in go-platform/packages/*; app directories own only composition and route entrypoints.

UI Package Boundaries

packages/ui is organized for a larger platform:

packages/ui/src/
  components/
    primitives/
    data-display/
    forms/
    domain/
  layout/
  modules/
    auth/
    portal/
    public-home/
  router/

Use components for reusable UI without side effects. Use modules for shared cross-app feature surfaces that legitimately own config/auth/i18n behavior. Use layout for shell composition. Keep temporary compatibility wrappers such as src/auth-pages.tsx and src/public-home.tsx thin.

API Rule

Frontend applications call one gateway endpoint:

VITE_API_BASE_URL=http://localhost:8085

They must not call auth-service, question-bank-service, docx-import-service, or other internal microservices directly. The Go API Gateway keeps auth, RBAC, request logging, rate limiting, route migration, and legacy compatibility in one place.

Migration Notes

• Public legacy frontend routes stay on the existing app until a route-specific parity task proves compatibility.
• New Vite apps begin as parallel surfaces for the Go platform.
• Cloudflare Pages can map each app directory to a separate project/root build command when production deployment is ready.
• V2 development Cloudflare Pages projects use the manifest at deploy/cloudflare/pages.frontend.json and target v2.dev.*.hoctapaz.com hostnames.
• Rollback is simple during this phase: stop building/deploying go-platform/apps and keep the legacy frontend as the source of production traffic.

Validation

• pnpm install
• pnpm frontend:typecheck
• pnpm frontend:test
• pnpm frontend:lint
• pnpm frontend:build
• git diff -- apps packages --exit-code