Fork-ready platform hub
This section implements the platform refactoring master plan: clean multi-repo boundaries, contract-driven integration, reusable platform core, and IDE-friendly workflows.
English
| Document | Purpose |
|---|---|
| Naming for technical docs vs legal | Technical vs legal naming; links to the documentation style guide. |
| Master plan | Full program: summary, problems, architecture, phases, risks (sections 1–20). |
| Dependency inspection (IDE agents) | Mandatory checklist before editing across repos — canonical copy lives in the operator AI documentation tree (docs/from-prego-monorepo/platform/dependency-inspection-for-ai.md) when that repository is cloned beside the monorepo. |
| Platform overview | One-page system context and layer model. |
| Tenant & trust boundaries | Headers, internal signature, trust zones — canonical copy in the operator AI docs tree (docs/from-prego-monorepo/platform/tenant-trust-boundaries.md) when cloned beside this monorepo. |
| Entity ID standard | Identifier format ([prefix]_[nanoid]), prefix registry, collision handling, migration rules. Implementation package: @platform/id-utils (see monorepo packages/id-utils/README.md). |
| Repo responsibility matrix | What each repository must / must not own. |
| How to add an API | OpenAPI → gateway → Worker ordering. |
| API gateway & BFF governance | Gateway vs same-origin BFF vs presigned upload — hybrid rules for marketing web, admin web, and client web. |
| Fork checklist | New product from the platform: copy vs depend. |
| IDE guide | Safe vs risky changes and where to add code (including gateway CORS and optional browser x-trace-id) — operator AI docs tree (docs/from-prego-monorepo/platform/ai-ide-guide.md) when cloned beside this monorepo. |
| SaaS ERP web app standard | Draft v1.0 — Next.js, Zod, RHF, shared packages, Cloudflare deploy posture for marketing, admin, and client web apps. |
| Web app standardization plan | Program plan and priorities; converges apps on the web standard. |
| Web app refactoring prompt (Cursor) | Copy-paste prompts for IDE-assisted refactors aligned with the web standard. |
| Web app safe refactor status | Behavior-preserving audit snapshot, risk map, deferred work vs the web standard. |
| Web app refactor continuation plan | Progress summary and phased follow-up (Next alignment, contracts/forms, billing, deploy decisions). |
| Deploy convergence ADR (client-web) | next-on-pages vs OpenNext — target, current posture, migration preconditions. |
| Marketing web — Cloudflare Pages hosting | Canonical hosting for apps/marketing-web vs internal Starlight docs (prego-devdoc); CI upload pointers. |
| Phase 2 — connector slots | Thin Zod + control-plane D1 0029 + operator AI worker connector context; optional CACHE erp_cred: (ERP_CREDENTIAL_KV_PREFIX) + ref — see operator AI repository docs/deployment.md when automating credential material (no big-bang). |
| Repository README index | Role-based index of gateway, Workers, ERP app, infra, and docs repositories (swap GITHUB_ORG when forking). |
| Browser storage minimization | Whitelist or blacklist per app, control-plane D1 target model, admin and marketing web contracts, client web auth phases, ERP boundaries, operator auth, optional consent audit. |
| Environment variable neutralization plan | Planning — Migration strategy for PREGO_* environment variables to brand-neutral names; phased rollout, cookie rename order, risk mitigation. Public HTTP headers (X-Prego-*) are out of scope for this phase. |
Related
- Trial marketing web → admin signup: Trial email and admin handoff — control-plane
INTERNAL_API_KEY/ optionalTRIAL_FORCE_BUSINESS_EMAILS; admin WorkerPREGO_CONTROL_PLANE_INTERNAL_API_KEY(same value as control-plane internal key). Manual approval (email OTP + details): marketing web/trial/manual-approval/verify; gatewayPOST /api/trial/manual-approval/*; control-plane D1 0027·0028 and Resend /OTP_PEPPERas in the control-plane repositoryREADME.md(same runbook). - Gateway operators (CORS / Pages origins): gateway repository
docs/runbook/README.md(index) anddocs/runbook/—ALLOWED_ORIGINS, browser preflight triage, optionalx-trace-idin CORSallowedHeaders(see tenant & trust boundaries in the operator AI docs tree when cloned beside this monorepo). - Contracts: API contracts (OpenAPI source of truth lives in the gateway repository; this section links and explains versioning).
- Gateway OpenAPI fragments: Merge order from
config/oas-manifest.json. Older planning docs may name superseded fragments — see gateway repositorydocs/planning/oas-layout-history.md· How to add an API section 1. - Domain: ERP / Frappe.
- IDE / agents: Monorepo root
AGENTS.mdand.cursor/rules/prego-multi-repo-platform.mdcpoint agents at this section. Sibling repositories use shorter.cursor/rules/prego-platform-docs-pointer.mdcstyle stubs. - Monorepo integration verify: root
AGENTS.md—pnpm run build:verify— shared packages,verify:next-dev-scripts,build:docs, etc. (does not build marketing / admin / client web production bundles). Internaldocs/Starlight pages are MDX — seedocs/README.mdbeside this app. Ifastro buildfails with missing chunks underdocs/dist(for examplerenderers.mjs), runpnpm run build:docs:cleanfrom the monorepo root (seeAGENTS.md). Monorepo verification details: operator AI docs treeai-ide-guide.md. - GitHub Actions: monorepo
.github/workflows/README.md— index of workflows (admin-web-verify,build-client-web,next-dev-scripts, …).
한국어
포크 가능한 플랫폼 문서의 시작점입니다. 기술 문서 표기는 Naming for technical docs vs legal 및 Documentation style guide 를 먼저 본다. 위 영어 표의 링크에서 마스터 플랜, 테넌트·신뢰 경계(운영 AI 문서 트리의 tenant-trust-boundaries.md), 엔티티 ID 표준, 레포 책임, API 추가 절차, API 게이트웨이·BFF 거버넌스, SaaS ERP 웹 앱 표준, 표준화·리팩터링·배포 ADR 문서, 마케팅 웹 Pages 호스팅 결정, Phase 2 커넥터 슬롯(운영 AI 저장소의 배포·KV 문서와 함께 읽기), 브라우저 저장소 최소화, 환경 변수 중립화 계획 (기획 — PREGO_* → 중립 이름 이전 전략), 포크 체크리스트, 레포 README 색인을 순서대로 읽을 수 있다. 트라이얼 마케팅 웹 → 관리자 가입·수동 승인 경로는 Trial email and admin handoff 및 컨트롤 플레인 저장소 README.md 를 참고한다. 모노레포 통합 검증: 루트 AGENTS.md 의 pnpm run build:verify — 공유 패키지·build:docs 등. astro build 실패 시 루트에서 pnpm run build:docs:clean. 게이트웨이 CORS·ALLOWED_ORIGINS·x-trace-id 는 게이트웨이 저장소 docs/runbook/ 을 본다. OpenAPI 조각 이력: 게이트웨이 저장소 docs/planning/oas-layout-history.md · API 추가 방법 §1.