Platform refactoring master plan

This document is the authoritative program for transforming PREGO into a clean multi-repo architecture, a reusable fork-ready platform, contract-driven integration, and documentation-aligned delivery.

1. System refactoring summary

PREGO combines a monorepo (Prego: Next.js UI, shared packages) with distributed backends and infra repos. Today, tenant identifiers coexist (tenant_id, companyId, first URL segment, X-Tenant-Id). Internal HMAC trust is implemented in both Zuplo (my-ai-internal-sig.ts) and prego_ai (internal-sig.ts). prego-control-plane mixes orchestration with simulation, RAG cost tooling, and other product-adjacent surfaces.

Goal: separate platform core (contracts, tenant headers, thin SDK, observability), domain (Frappe/ERP, AI business rules), interface (Next.js, Zuplo), and infra (Pulumi, Ansible, Docker), with schema-first communication and one documentation spine.

2. Cross-repo problems

Type	Issue	Risk
Duplication	Internal sig + tenant path logic in multiple places	Security drift if algorithms diverge
Coupling	prego_ai auth assumes Zuplo-injected headers; ERP fetch in AI worker	Hard to call “AI-only” without ERP knowledge
Boundaries	Control-plane RAG/simulation vs orchestration	Scope creep, large blast radius
Tenant	`companyId` vs `tenant_id`, demo branches scattered	Wrong tenant data, weak audit
Docs	Many overlapping `planning/*.md` files	No single truth for onboarding

3. Target platform architecture

Platform core: OpenAPI fragments, JSON Schema / TS types, header conventions, internal-sig spec + test vectors, minimal SDK, logging field names.
Domain: prego_saas (ERP); prego_ai pipelines with domain adapters behind interfaces.
Interface: prego-zuplo (routing, auth hooks, limits, proxy — no business rules); Next.js UI.
Infra: prego-pulumi, prego-ansible, prego-docker only.

4. Repo responsibility matrix

See the detailed table: Repo responsibility matrix.

5. Platform core definition

In scope: tenant/user context model, API contract store, Zuplo↔Worker trust, shared logging shape, platform AI hooks (tenant-scoped retrieval, quotas, PII policy).

Out of scope: Frappe DocTypes, payroll/attendance rules, product-specific automation semantics.

6. Domain isolation plan

Wrap ERP HTTP usage in an adapter; depend on published API contracts, not ad-hoc schema knowledge.
Keep “what to write to ERP” in domain; keep “execute job with tenant context” in platform.

7. Cleanup analysis (mandatory)

Area	Action types
OpenAPI dual trees in Zuplo	MERGE process + CI drift checks
Internal sig (Zuplo + Worker)	EXTRACT spec; single implementation + shared tests
Tenant naming	REFACTOR + doc MERGE
Control-plane demos / simulation	ARCHIVE or separate package
Planning doc sprawl	MERGE / DELETE / ARCHIVE completed plans
Duplicate UI primitives in Prego apps	MERGE into shared packages

8. Cleanup action plan (mandatory)

Every item must be labeled DELETE | MERGE | REFACTOR | EXTRACT | ARCHIVE with a one-line justification in tickets.

MERGE: One deployable merged OAS; PR gates with check-oas-* scripts where present.
EXTRACT: Internal-sig algorithm + vectors; consumers depend on one package or verified copy policy.
REFACTOR: Canonical tenant_id; gateway-only alias for legacy companyId paths if needed.
ARCHIVE: Move finished plans under archive/ (see Documentation restructuring).
DELETE: Only after grep proves zero references.

9. Shared module extraction plan

Module	Today (examples)	Target
Tenant path / headers	`company-id-from-path.ts`, `my-ai-upstream-common.ts`	Shared TS package + documented Zuplo bundle rules
Internal sig	Zuplo + prego_ai	Single implementation + cross-repo tests
OpenAPI fragments	`prego-zuplo/docs/openapi/`	Versioned `@platform/contracts` or equivalent
Logger fields	`prego_ai` logger	Common schema (OTel-friendly names)

10. API contract standardization

One merged OAS as deploy artifact; stable operationId → SDK methods.
Explicit tenant_id in paths or shared parameters.
Breaking changes: SemVer + deprecation + optional /v1 route prefix in Zuplo.

Details: How to add an API.

11. Multi-tenant model

Details: Tenant & trust boundaries.

12. Extended runtime architecture

Platform: ingestion metadata, embedding version, tenant-mandatory retrieval filters, generation hooks, quotas, audit.
Domain: scheduled automation plans, ERP tool calls, industry prompts — isolated modules or future plugins.

flowchart LR
  IN[Ingest] --> EMB[Embed]
  EMB --> IDX[Index tenant-scoped]
  IDX --> RET[Retrieve]
  RET --> GEN[Generate]
  GEN --> OUT[Response + audit]

13. Template / fork strategy

See Fork checklist.

14. Documentation impact analysis

Prego planning/ volume hides architecture entry points.
Zuplo docs/ and control-plane docs/ can duplicate the same flows.
External prego_docs repo may duplicate internal planning unless linked explicitly.

15. Documentation restructuring plan

Canonical spine under this site:

platform/ — architecture, tenant model, execution (this tree).
contracts/ — links to OAS location, versioning story.
domain/erp/, domain/ai/ — product-specific narratives.
deployment/, runbook/ — infra (existing).
prego-zuplo repository docs/runbook/README.md (index) and docs/runbook/*.md (separate Git repo) — gateway CORS, Portal ALLOWED_ORIGINS, browser x-trace-id; cross-linked from Platform hub and Tenant & trust boundaries.
planning/archive/ — completed plans (incremental migration).

Keep Planning implementation index as a live index; retire stale entries to archive links.

16. Documentation pack (minimum)

17. Mermaid diagrams

System architecture

flowchart TB
  subgraph interface [Interface]
    UI[Next.js Prego]
    GW[Zuplo]
  end
  subgraph platform [Platform runtimes]
    CP[control-plane Worker]
    AI[prego_ai Worker]
  end
  subgraph domain [Domain]
    FP[Frappe prego_saas]
  end
  subgraph infra [Infra]
    PU[Pulumi]
    AN[Ansible]
    DK[Docker]
  end
  UI --> GW
  GW --> CP
  GW --> AI
  GW --> FP
  PU --> AN
  AN --> DK

Repo interaction (contract-driven)

flowchart LR
  OAS[OpenAPI schemas]
  OAS --> GW[Zuplo]
  OAS --> SDK[Generated SDK]
  SDK --> UI[Next.js]
  GW -->|signed internal| W[prego_ai]
  GW --> FP[Frappe]

Request flow (typical authenticated API)

sequenceDiagram
  participant U as User
  participant UI as Next.js
  participant Z as Zuplo
  participant W as Worker
  U->>UI: action
  UI->>Z: session / token
  Z->>Z: policies
  Z->>W: X-Tenant-Id X-User-Id X-Internal-Sig
  W->>W: verify + auth middleware
  W-->>Z: response
  Z-->>UI: response

Data flow (tenant isolation)

flowchart TB
  T[tenant_id] --> KV[KV keys]
  T --> R2[R2 prefixes]
  T --> D1[D1 rows]
  T --> V[Vectorize filter]

18. IDE guide

See IDE guide (includes Cursor / multi-root rules and AGENTS.md pointers).

19. Execution plan

Phase	Focus	Outcomes
1	Cleanup	Inventory, OAS drift control, archive stale docs, tenant terminology table
2	Platform extraction	Contracts package, internal-sig single source, shared header helpers
3	Repo restructuring	Narrow control-plane scope; ERP adapter boundary in prego_ai; Zuplo = policy only
4	Documentation sync	This spine + cross-links from planning index
5	Validation	Contract tests, staging e2e, tenant isolation regression

Macro phases: (A) Phases 1 + start 4 = cleanup + doc spine; (B) Phases 2–3 = extraction + structure; (C) Phase 5 = validation at each gate.

20. Risks

Risk	Mitigation
Over-abstraction	Extract only what a second product would reuse unchanged
Contract breakage	SemVer, CI merge checks, multi-consumer staging
Tenant leakage	Code review checklist; automated negative tests
Migration complexity	Deprecation period for URLs/headers; feature flags

한국어

이 문서는 PREGO를 정리(cleanup), 플랫폼 추출, 계약 표준화, 문서 동기화, 포크 전략으로 이끄는 총괄 기획입니다. 구현 전에 의존성 점검을 적용합니다. 문서 구조(§15)에는 이 모노레포 runbook/ 외에 prego-zuplo 저장소 docs/runbook/README.md (색인) · 폴더(게이트웨이 CORS·ALLOWED_ORIGINS·브라우저 x-trace-id)가 별도 레포 운영 문서로 포함됩니다.