Web app standardization plan
This document is the program plan (기획) for standardizing PREGO’s product web tier. It complements the normative rules in Prego Web App Standard (Draft v1.0).
Canonical standard: Prego Web App Standard — implementation work should converge on that document.
IDE execution prompts: Web app refactoring prompt (Cursor) — copy-paste templates aligned with this plan.
Live audit / risk snapshot (behavior-preserving): Web app safe refactor status.
Related platform docs: Platform hub · API gateway & BFF governance · How to add an API · IDE guide · Repo responsibility matrix
1. Purpose
Align apps/www, apps/admin-web, and apps/client-web so that:
- Development rules and tooling are consistent (Next, Zod, RHF, shared packages).
- Deployment targets are understandable per app role, with a clear long-term direction (OpenNext alignment for interactive apps).
- Contracts are schema-first and shared where the product surface overlaps.
- IDE-assisted development can rely on one standard document plus app-specific Cursor rules.
Out of scope for “single stack”: Frappe, Pulumi, Ansible, Docker, Zuplo OAS authoring — these keep their own repos; the web tier consumes their contracts and runbooks.
2. Diagnosis (summary)
| Observation | Implication |
|---|---|
| Role separation across repos is mostly sound | Keep boundaries; fix web-tier consistency |
| Web apps diverged into multiple dev cultures | Unify via Prego Web App Standard |
| admin-web is operationally critical but had thinner shared contracts | Treat admin-web as highest-priority for Zod/RHF/shared packages |
| Next majors and adapters differ | Phased alignment: admin + client first, www second |
| Hono usage unclear | Standard: Hono on Workers for HTTP services; Next does not host Worker logic |
| Non-canonical HTML / demo files mixed with production | Move to archive/ and document “do not edit” |
3. Goals (tied to the standard)
- Single web standard document — Prego Web App Standard is the reference; update it when the stack or exceptions change.
- admin-web as contract-heavy app — onboarding, billing, tenant/plan/region: RHF + Zod, shared schemas with client-web where applicable.
- Shared packages —
ui,forms,contracts,api-client,config(names aligned with monorepo reality). - Deployment clarity — document per-app why (see standard §7); converge client-web toward OpenNext-on-Cloudflare like admin-web where feasible.
- System boundaries — onboarding APIs, tenant contract ownership, Zuplo vs Worker vs Next: see API gateway & BFF governance and How to add an API.
- Legacy isolation — non-source-of-truth assets out of default navigation and agent targets.
4. Priorities (execution backlog)
| Priority | Work | Done when |
|---|---|---|
| P0 | Standard published and linked from platform hub | Hub + checklist + Cursor rule point here |
| P1 | admin-web: Zod/RHF on critical flows; shared contracts adoption | Core flows covered; no new ad hoc validation |
| P2 | Next major alignment: admin-web + client-web | Documented version policy in standard |
| P3 | www Next alignment | Low-risk upgrade path executed |
| P4 | client-web deploy strategy toward OpenNext alignment | Decision recorded; migration plan if needed |
| P5 | archive/ for legacy HTML/demo; README + agent notes updated | Agents do not edit archived paths as production |
| P6 | control-plane Hono consistency | Optional RFC; not a blocker for web standard |
Next.js version matrix (living snapshot)
| App | next in package.json | Notes |
|---|---|---|
| client-web | 16.0.11 | pages:build via @cloudflare/next-on-pages; peer warns on Next 16 — tracked for Phase 4 convergence |
| admin-web | 16.0.11 | OpenNext @opennextjs/cloudflare ^1.18; next.config.mjs + cf:build verified locally |
| www | 16.0.11 | Static export; next build --webpack (Next 16 default Turbopack hits monorepo turbopack.root issues); next.config.mjs |
Deploy posture (client-web vs admin-web)
- admin-web: OpenNext → Cloudflare Worker (
apps/admin-web/wrangler.jsonc); assets from.open-next/assets. - client-web:
@cloudflare/next-on-pages(pages:buildin apppackage.json). Full convergence with admin-web’s OpenNext stack is Phase 4 — see Deploy convergence ADR (Phase 4 migration delta checklist); record breaking differences (routing, middleware, cache) before any migration.
packages/contracts (or prego-web-contracts) stays deferred until the same API shape is consumed in two places (e.g. two apps, or UI + server with distinct import paths). Password POST /auth/signin · /auth/signup JSON shapes live in @platform/web-auth-schemas (signInSchema, signUpSchema); apps/client-web/lib/schemas/auth.ts re-exports for Hono src/server/routes/auth.ts.
DX — Next tsconfig hygiene: @platform/next-dev-scripts provides prego-strip-next-dev-types-from-tsconfig (removes .next/dev/types/**/*.ts from include after builds). Used by all three web apps; root pnpm run verify:next-dev-scripts; CI .github/workflows/next-dev-scripts.yml.
Monorepo integration verify (shared packages + internal Starlight docs — not the three Next production bundles): root pnpm run build:verify. Starlight docs/ = MDX — docs/README.md · Dependency inspection §7. If docs astro build fails with missing chunks under docs/dist (e.g. renderers.mjs), run pnpm run build:docs:clean from the repo root — AGENTS.md. Prego Web App Standard §7 · IDE guide · Dependency inspection §8.
5. Phased roadmap
| Phase | Focus |
|---|---|
| 0 — Agreement | Owners, exception list (BFF), success metrics |
| 1 — Guardrails | Hub links, dependency-inspection awareness, Cursor rules |
| 2 — admin-web | Schema layer on signup/billing/tenant flows |
| 3 — Next major | admin + client; then www |
| 4 — Deploy convergence | client-web vs admin-web OpenNext posture |
| 5 — Workers / CP | Hono alignment in control-plane as separate track |
6. Success criteria
- Prego Web App Standard is the first link for “how we build web apps.”
- New UI work uses Zod at boundaries listed in the standard.
- admin-web critical paths match the contract-heavy bar described in the standard.
- Legacy/non-canonical artifacts live under
archive/(or equivalent) with explicit README. - No undocumented public API changes (OpenAPI in prego-zuplo remains source of truth for gateway routes).
7. Risks & mitigations
| Risk | Mitigation |
|---|---|
| Big-bang Next upgrade | Phased upgrades; app-by-app CI and E2E |
| Shared package cycles | Keep contracts lean; no UI imports from ERP |
| “Zuplo only” confusion | Always pair this plan with API gateway & BFF governance |
한국어 요약
이 문서는 웹 앱 3종 표준화 프로그램입니다. 규범 문서는 Prego Web App Standard 이며, 본 기획은 그 표준에 맞추기 위한 진단·목표·우선순위·로드맵·성공 기준을 정리합니다. admin-web 을 계약 밀도 최우선으로 두고, Next·배포·공유 패키지 를 단계적으로 맞춥니다. §4 직후 에 Next.js 버전 표·배포 포지션·contracts 추출 전제 를 두었습니다. 공개 HTTP는 prego-zuplo OpenAPI 와 BFF 거버넌스 를 함께 따릅니다. Next tsconfig 정리 는 @platform/next-dev-scripts — 루트 pnpm run verify:next-dev-scripts. 모노레포 통합 검증(pnpm run build:verify, 내부 Starlight docs 포함) — 내부 docs/ 는 MDX — docs/README.md · Dependency inspection §7. astro build chunk 오류 시(예: renderers.mjs) 루트 pnpm run build:docs:clean — AGENTS.md · Web app standard §7 · IDE 가이드 · Dependency inspection §8.