PREGO Documentation Consolidation and Bilingual Structure Plan

Document: docs-consolidation-and-bilingual-plan.md
Target folder: /Users/marco/Prego/docs
Version: 1.0
Date: 2026-03

---

1. Overview

1.1 Purpose

Reorganize and consolidate documentation under docs/ to:

• Remove outdated or superseded documents
• Merge duplicated content into single authoritative documents
• Introduce a bilingual structure (English top, Korean bottom)
• Add Mermaid diagrams for flows, system architecture, and charts where appropriate

1.2 Scope

In scope	Out of scope
docs/planning/*.md	Code changes in repos
docs/runbook/*.md	Migrations, workflows, config files
README, IMPLEMENTATION_INDEX references	External tools/config
Folder structure and naming	Git history (no rewriting)

---

2. Current State Analysis

2.1 Document Inventory (by Domain)

mindmap
  root((docs/))
    planning
      API Control Plane
        api-control-plane-implementation-plan
        api-control-plane-quick-reference
        api-control-plane-analysis-and-recommendations
        api-control-plane-tenant-lifecycle-analysis
      Tenant Onboarding
        tenant-onboarding-demo-www-plan
        tenant-onboarding-flow runbook
        www-signup-email-otp-google-plan
        onboarding-step2/4/5/6 plans
      OTP & Email
        otp-email-* 8+ docs
        otp-verify-* 6+ docs
        email-* 15+ docs
      prego-docker
        prego-docker-* 10+ docs
      Cloudflare & Monitoring
        cloudflare-* 8+ docs
      Infrastructure
        redis, mariadb, frappe, ansible, pulumi
    runbook
      OPERATIONS
      provision-tenant-pipeline
      tenant-onboarding-flow
      email-*, logpush, etc.

2.2 Identified Overlaps and Duplicates

Domain	Candidate Merges	Rationale
OTP / Email	otp-email-flow-and-template-ownership-plan, otp-email-zuplo-api-callers-and-process, otp-email-readability-formatting-plan, otp-email-newline-*	Same ownership, flow, and template concerns
OTP Verify	otp-verify-network-error-cors-*, otp-verify-and-passcode-flow-check-plan, verify-email-rsc-and-cors-local-debug-plan, otp-verify-failure-and-dashboard-ux-plan, otp-verify-page-kv-check-*	CORS, flow, and dashboard UX related
prego-docker build	prego-docker-exit-128-*, prego-docker-build-exit-128-resolution-plan, prego-docker-build-exit-167-analysis, prego-docker-bench-init-uv-resolver-*	Build failure resolution; can be one troubleshooting doc
Onboarding	onboarding-step2-removal-step5-changes-plan, onboarding-step4-*, onboarding-plan-limits-*	Part of same wizard redesign; merge into tenant-onboarding-demo-www-plan or a single onboarding plan
API Control Plane	api-control-plane-implementation-plan (master) vs api-control-plane-quick-reference, api-control-plane-analysis-*, api-control-plane-tenant-lifecycle-*	Keep implementation as master; merge quick-reference + analysis + lifecycle into sub-sections or appendices
Email	Multiple email-* planning + email-troubleshooting, email-zuplo-vs-direct-call, email-delivery-flow-*	Single email architecture + troubleshooting doc

2.3 Likely Outdated / Superseded (Archive Candidates)

Document	Reason
opsfork-production-welcome-email-and-kv-runbook	Ops-specific, one-off
passcode-reset-local-verification	Superseded by runbook verification
employee-web-login-passcode-test-plan	Test-only, narrow scope
james-dean-demo-user-and-welcome-email-test-plan	Demo-only
cloudflare-account-migration-to-kinybaik-plan	One-time migration
verify-email-rsc-and-cors-local-debug-plan	Debug-specific; merge into OTP verify doc
Phase docs if missing (phase1-implementation-summary, etc.)	README references them; verify existence or remove references
DEPLOYMENT_CHECKLIST, QA_CHECKLIST	If missing, remove from README or add stubs

---

3. Target Structure

3.1 Proposed Folder Layout

flowchart TD
    subgraph docs["docs/"]
        README["README.md (index)"]
        planning["planning/"]
        runbook["runbook/"]
        archive["archive/"]
    end

    subgraph planning_content["planning/"]
        P1["01-architecture/"]
        P2["02-tenant-onboarding/"]
        P3["03-auth-otp-email/"]
        P4["04-control-plane/"]
        P5["05-infrastructure/"]
        P6["06-monitoring/"]
        P7["07-prego-docker/"]
        P8["index.md"]
    end

    subgraph runbook_content["runbook/"]
        R1["operations.md"]
        R2["tenant-onboarding-flow.md"]
        R3["provision-tenant-pipeline.md"]
        R4["email-troubleshooting.md"]
        R5["index.md"]
    end

    subgraph archive_content["archive/"]
        A1["obsolete/"]
        A2["superseded/"]
    end

    README --> planning
    README --> runbook
    planning --> P8
    planning --> P1
    planning --> P2
    planning --> P3
    planning --> P4
    planning --> P5
    planning --> P6
    planning --> P7
    runbook --> R5
    archive --> A1
    archive --> A2

3.2 Document Naming Convention

• YYYY-MM-topic-summary.md for consolidated planning (e.g. 2026-03-auth-otp-email-plan.md)
• Runbooks: lowercase-with-hyphens (e.g. tenant-onboarding-flow.md)
• Index files: README.md or index.md per folder

---

4. Bilingual Format Specification

4.1 Structure

Each consolidated document follows:

---
title: Document Title
domain: planning | runbook
version: 1.0
---

# [English Title]

[Full English content - sections 1..n]

---

# 한국어

## [한국어 제목]

[Full Korean content - sections 1..n]

4.2 Rules

• English section first; Korean section after --- separator
• Headings and body text in both languages
• Code blocks, Mermaid diagrams, tables: single copy (language-agnostic)
• Placeholders: [EN] / [KO] only if translation is deferred

---

5. Mermaid Diagram Requirements

5.1 Where to Add Diagrams

Document Type	Diagram Types	Example
Flow / process	flowchart, sequenceDiagram	Tenant onboarding flow
System architecture	flowchart LR/TD, C4Context (if supported)	Control Plane, Zuplo, www
State / lifecycle	stateDiagram-v2	Tenant lifecycle, OTP flow
Hierarchies / domains	mindmap	docs domain map
Dependencies	flowchart	Phase / task dependencies
Metrics / dashboards	block-beta or pie (Mermaid)	Monitoring components

5.2 Suggested Diagrams per Domain

Domain	Suggested Mermaid
Tenant onboarding	flowchart www → Control Plane → Workflow → Ansible → Zuplo
OTP / email flow	sequenceDiagram client-web ↔ Zuplo ↔ Auth Worker ↔ Resend
API Control Plane	flowchart POST /v1/tenants → Queue → Provision → Callback
prego-docker	flowchart app push → repository_dispatch → build → push image
Monitoring	flowchart Logpush → R2, Analytics Engine, D1
docs consolidation	mindmap or flowchart new folder structure

---

6. Implementation Phases

6.1 Phase 1: Inventory and Triage

• List all .md files in docs/ with size, last-modified
• Mark each as: KEEP, MERGE, ARCHIVE
• Produce docs/consolidation-inventory.csv (path, action, target)

6.2 Phase 2: Create Archive and Move Obsolete

• Create docs/archive/obsolete/ and docs/archive/superseded/
• Move archive-candidate files (5 docs)
• Add archive/README.md describing archive policy

6.3 Phase 3: Merge Duplicates

• Runbook email: merge email-mail-sender-api-url-and-key, email-no-mail-analysis, email-test-docker, email-zuplo-vs-direct-call → runbook/email-troubleshooting.md
• OTP/Email: merge into planning/03-auth-otp-email/otp-and-email-consolidated.md
• OTP Verify: merge into planning/03-auth-otp-email/otp-verify-consolidated.md
• prego-docker build failures: merge into planning/07-prego-docker/build-troubleshooting.md
• Onboarding steps: merge into tenant-onboarding-demo-www-plan §16
• API Control Plane: keep implementation-plan as master; fold quick-reference, analysis, lifecycle as Appendix A–C

6.4 Phase 4: Apply Bilingual Format

• Pilot: Convert consolidated docs (otp-and-email, otp-verify, build-troubleshooting) to EN-top / KO-bottom with frontmatter
• Convert remaining KEEP documents (batch as needed)
• Add frontmatter (title, domain, version)
• Keep code blocks and diagrams as single copy

6.5 Phase 5: Add Mermaid Diagrams

• Tenant onboarding flow diagram (tenant-onboarding-flow.md)
• OTP / email sequence diagram (otp-and-email-consolidated.md)
• Control Plane architecture diagram (api-control-plane-implementation-plan.md §2)
• prego-docker build pipeline diagram (build-troubleshooting.md)
• docs structure diagram (docs/README.md)

6.6 Phase 6: Update Indices

• Update planning/README.md and planning/IMPLEMENTATION_INDEX.md
• Update runbook/OPERATIONS.md references (OTP link → consolidated)
• Update docs/README.md as master index (runbook, archive, structure)
• Fix remaining broken links in all updated docs (spot-check)

---

7. Verification Checklist

• No duplicate content across planning docs
• All documents use EN-top, KO-bottom format
• Mermaid diagrams render in GitHub / GitLab
• IMPLEMENTATION_INDEX and README links valid
• Archive folder has README and is excluded from main navigation
• File count reduced by ~30–40% (target: ~120 → ~75 active docs)

---

8. Risks and Mitigations

Risk	Mitigation
Broken references from other repos	Grep all repos for docs/ links; update in same PR
Loss of historical context	Archive with archive/README.md and optional CHANGELOG
Translation quality	Use EN as source of truth; KO can be incremental
Mermaid compatibility	Use supported syntax; test in GitHub preview

---

9. References

• Current docs root: /Users/marco/Prego/docs
• Planning index: planning/IMPLEMENTATION_INDEX.md
• Runbook summary: runbook/OPERATIONS.md
• Mermaid docs: https://mermaid.js.org/syntax/flowchart.html

---

한국어

1. 개요

1.1 목적

docs/ 하위 문서를 정리·통합하여:

• 사용하지 않는 구버전 문서 삭제 또는 보관
• 중복 내용을 하나의 권위 문서로 통합
• 상단 영어, 하단 한국어의 이중 언어 구조 적용
• 플로우, 시스템 다이어그램, 차트 등에 Mermaid 다이어그램 추가

1.2 범위

대상	제외
docs/planning/*.md	코드 변경
docs/runbook/*.md	마이그레이션, 워크플로우, 설정 파일
README, IMPLEMENTATION_INDEX 참조	외부 도구/설정
폴더 구조 및 명명 규칙	Git 이력 변경

---

2. 현황 분석

2.1 문서 재고 (도메인별)

• planning: API Control Plane, Tenant Onboarding, OTP/Email, prego-docker, Cloudflare/모니터링, 인프라 등 100+ 문서
• runbook: OPERATIONS, provision-tenant-pipeline, tenant-onboarding-flow, email 관련, logpush 등 30+ 문서

2.2 중복·통합 후보

• OTP/Email: 8개 이상 otp-email 관련 → 1개 통합
• OTP Verify: 6개 이상 otp-verify/verify-email 관련 → 1개 통합
• prego-docker 빌드: exit 128/167, uv resolver 등 → 빌드 트러블슈팅 1개
• 온보딩: step2/4/5/6 기획 → tenant-onboarding-demo-www-plan 또는 단일 온보딩 기획으로 통합
• API Control Plane: implementation-plan 기준으로 quick-reference·analysis·lifecycle 통합

2.3 보관(Archive) 후보

• opsfork-production-welcome-email, passcode-reset-local-verification
• james-dean-demo-user, employee-web-login-passcode-test-plan
• cloudflare-account-migration-to-kinybaik-plan
• 기타 일회성/데모 전용 문서

---

3. 목표 구조

3.1 제안 폴더 레이아웃

docs/
├── README.md           # 전체 인덱스
├── planning/
│   ├── index.md
│   ├── 01-architecture/
│   ├── 02-tenant-onboarding/
│   ├── 03-auth-otp-email/
│   ├── 04-control-plane/
│   ├── 05-infrastructure/
│   ├── 06-monitoring/
│   └── 07-prego-docker/
├── runbook/
│   ├── index.md
│   ├── operations.md
│   └── ...
└── archive/
    ├── README.md
    ├── obsolete/
    └── superseded/

3.2 문서 명명 규칙

• 통합 기획: YYYY-MM-도메인-요약.md
• Runbook: 소문자-하이픈 (예: tenant-onboarding-flow.md)
• 각 폴더: README.md 또는 index.md

---

4. 이중 언어 형식

4.1 구조

• 상단: 영어 본문 전체
• 구분선 ---
• 하단: 한국어 본문 전체
• 코드 블록, Mermaid, 표: 한 번만 작성 (언어 중립)

4.2 규칙

• 영어를 기준 문서로 사용
• 한국어 번역은 점진적으로 보완 가능

---

5. Mermaid 다이어그램 요건

5.1 추가 대상

문서 유형	다이어그램 유형	예시
플로우/프로세스	flowchart, sequenceDiagram	테넌트 온보딩
시스템 아키텍처	flowchart	Control Plane, Zuplo, www
상태/생애주기	stateDiagram-v2	테넌트, OTP
도메인 구조	mindmap	docs 도메인 맵

5.2 도메인별 권장 다이어그램

• 테넌트 온보딩: www → Control Plane → Workflow → Ansible → Zuplo flowchart
• OTP/이메일: client-web ↔ Zuplo ↔ Auth Worker sequenceDiagram
• API Control Plane: POST /v1/tenants → Queue → Provision flowchart
• prego-docker: app push → build → push 이미지 flowchart

---

6. 구현 단계

1. Phase 1: 재고 및 분류 (파일 변경 없음)
2. Phase 2: archive 폴더 생성 및 구버전 이관
3. Phase 3: 중복 문서 통합
4. Phase 4: 이중 언어 형식 적용
5. Phase 5: Mermaid 다이어그램 추가
6. Phase 6: 인덱스 및 링크 갱신

---

7. 검증 체크리스트

• planning 문서 간 중복 제거
• 모든 문서 EN-상단, KO-하단 형식
• Mermaid 다이어그램 정상 렌더링
• IMPLEMENTATION_INDEX·README 링크 유효
• 문서 수 약 30–40% 감소 (목표)