Skip to content
Prego Prego Docs

PREGO v4.0 Implementation Index

Index of code, configuration, and documentation produced from the plan prego-saas-control-platform-v4-implementation-plan.

Phase summaries

PhaseSummary doc
Phase 1phase1-implementation-summary
Phase 2phase2-usage-r2-kv
Phase 3phase3-governance-summary
Phase 4phase4-us-autoscaler-summary
Phase 5phase5-eu-gdpr-summary

For the full directory-by-directory output and planning doc index, see the 한국어 section below.

flowchart TB
  I[Implementation Index] --> P[Phase 1-5 summaries]
  I --> D[Directory output]
  I --> R[Runbook]
  I --> Q[Planning docs]

한국어 {#korean}

PREGO v4.0 구현 산출물 인덱스

기획서 prego-saas-control-platform-v4-implementation-plan 기준으로 생성된 코드·설정·문서 일람.

Phase별 요약 문서

Phase요약 문서
Phase 1phase1-implementation-summary
Phase 2phase2-usage-r2-kv
Phase 3phase3-governance-summary
Phase 4phase4-us-autoscaler-summary
Phase 5phase5-eu-gdpr-summary

디렉터리별 산출물

경로내용
migrations/D1 0001_init ~ 0008_rag_ai
workers/rag-query/RAG Query Worker (Vectorize + Workers AI) — 스켈레톤·스텁 응답.
.github/workflows/pulumi-preview, pulumi-up, pulumi-destroy
prego-pulumi/main.py, config/region.py, Pulumi.sg/us/eu.yaml
workers/control-plane/Stripe Webhook, D1, trace_events, audit_logs, provision trigger
workers/usage-writer/POST /usage → R2 usage_raw
workers/usage-aggregator/Cron R2 → usage_rollups
workers/cycle-close/Cron 월말 → usage_cycle_totals, Stripe
workers/purge-job/Cron 30일 Pending_Deletion → Hard Purge §5.8
workers/autoscaler/Cron Health Score, scaling_events, Scale Out/In
prego-ansible/ (별도 레포)Ansible playbook, inventory, roles (docker, mariadb_server, frappe_bench, frappe_site). Ref: ansible-implementation-plan.md, ansible-implementation-sequence.md. bench rc:127 해결: ansible-frappe-bench-rc127-resolution-plan.md.
prego-docker/ (별도 레포)Docker 이미지 빌드: Dockerfile(apps.json·tag pinning), build-and-push(repository_dispatch 전용·Verify image apps·멀티아키텍처), trivy-scan.yml, compose(prod·bluegreen). Ref: prego-docker-implementation-plan.md.
prego-control-plane/ (별도 레포)Control Plane Worker: POST /v1/tenants(202+job_id), GET /v1/jobs/:id, Stripe webhook, provision-complete 콜백, KV(TENANT_ORIGINS) 갱신, internal/trace·nodes. D1 migrations 0001~0006. Ref: api-control-plane-implementation-plan.md Phase A.
apps/www/데모 테넌트 온보딩 웹: 위저드(패키지·서브도메인·로그인·결제·테넌트 정보·제출·프로비저닝 대기), api.js(Control Plane 연동), billing.html. PREGO_CONTROL_PLANE_URL·PREGO_AUTH_URL·PREGO_BILLING_PROXY_URL. Ref: tenant-onboarding-demo-www-plan.md, tenant-onboarding-flow.md.
infra/zuplo_sync.tsZuplo API Key 등록 (tenant_id, slug, subdomain 메타)
infra/logpush_setup.tsLogpush Job 생성·목록·삭제 (R2), create-all-email-workers·workers_trace_events·script-name 필터.
infra/logpush_r2_lifecycle_example.jsonR2 Logpush prefix별 90일 만료 Lifecycle 규칙 예시.
docs/runbook/github-secrets.mdSecrets·Environment 안내
scripts/smoke-verify-control-plane.shControl Plane R1·R5·R7 스모크 검증 (CONTROL_PLANE_URL, INTERNAL_API_KEY). Ref: prego-control-plane-dashboard §배포 후 검증.

API·Worker

  • Worker·API 개요: API_OVERVIEW.md — Control Plane, usage-writer, usage-aggregator, cycle-close, purge-job, autoscaler 엔드포인트·Cron 요약.

배포·운영

기획서

  • 구현 기획서: prego-saas-control-platform-v4-implementation-plan.md
  • 통합 아키텍처: saas-unified-architecture-hetzner-cloudflare-zuplo-plan.md
  • 지능형 자동화 구현 계획: intelligent-automation-implementation-plan.md — 전 구간 자동화(Pulumi→Ansible→Zuplo→D1), 모니터링, AI 서버 배치 구현 순서·산출물·검증.
  • 전 구간 자동화 워크플로 설계: provision-tenant-workflow-design.md — provision-tenant.yml / Provision Worker 설계 기획(입출력·단계·콜백·보안). Zero-Touch 이벤트 흐름(수신→큐→Worker: Ansible→KV→완료), Playbook 태스크 구성·확장성(DB 부하 분산·리소스 격리·로그 통합) 전략 반영.
  • API 기반 컨트롤 플레인: api-control-plane-implementation-plan.md — Control Plane vs Data Plane 분리, 5단계 워크플로(진입·큐·오케스트레이션·상태·콜백), Contract(비즈니스 의도만 API로), Plan별 DB·Zuplo KV 라우팅·Self-Healing·Dry-run/Idempotency/Shadow. Queues·보상 트랜잭션·Update/Delete 큐(§12–§15). 서비스 자원 모니터링·보안·데이터백업 §16–§20. 구현 Phase A→B→C→D(§21). Appendix A 퀵 레퍼런스 · B 현행 분석·개선안 · C 테넌트 생애주기(시나리오 1~8·Placement·Grace·Purge). (기존 3개 문서 통합)
  • RAG AI 엣지 아키텍처: rag-ai-edge-architecture-plan.md — Full Edge-Computing, Zuplo+Workers, Vectorize 멀티테넌시, D1/R2, 엔터프라이즈 기능(Guardrail·Document Intelligence·Privacy Masking·Audit), Phase 1–4 로드맵.
  • RAG AI Phase 1 구현 계획: rag-ai-phase1-implementation-plan.md — Data Ingestion Worker, RAG Query Worker, Zuplo 메터링 Policy, Vectorize·D1 프로비저닝, Wrangler 배포 순서·검증.
  • Worker AI 구현 기획서: worker-ai-implementation-plan.md — Edge-Native Data Ingestion·RAG Query·Compliance Checker·PII Filter 요구사항, UI/UX·보안·배포 순서·Phase, 코드 없이 명세만.
  • 네이밍 규칙: naming-conventions.md — 서버·DB·테넌트·DNS·Ansible·로그 등 프로젝트 전반 네이밍 규칙.
  • 테넌트 서브도메인·DNS: tenant-subdomain-dns-design.md — 가입 시 subdomain.pregoi.com 등록, 채택 방식 C: 내부 canonical tenant-{short_id}.pregoi.com + 사용자 CNAME. 라우팅은 canonical로만 처리.
  • www.pregoi.com 가입→결제→프로비저닝 플로우: www-pregoi-com-signup-to-provisioning-flow.md — 클라이언트가 www.pregoi.com 접속, Gmail SSO/이메일 가입, 패키지(무료/유료) 선택·결제, 리소스 할당 로직, 초기 인프라 자동화 단계 정리 및 단계별 현재 구현 상태.
  • 테넌트 온보딩 데모 www 기획·체크리스트: tenant-onboarding-demo-www-plan.md — Slug·서브도메인 Rule, 위저드 단계, 결제 후 테넌트 정보·additional_users, §10 구현 체크리스트(전 항목 구현 완료). 운영: tenant-onboarding-flow.md.
  • 5단계 확인 및 제출 → 제출 후 실제 진행 기능: step5-confirm-submit-to-provisioning-flow.md — 5단계(확인 및 제출) 화면 요약, 「시작하기」 클릭 시 www·Control Plane·워크플로·Ansible·Zuplo·콜백까지 단계별 동작 및 확인 항목→백엔드 사용처 매핑 (코드 기준 분석, 코드 없음).
  • 온보딩 상세 변경 (통합): tenant-onboarding-demo-www-plan.md §16 — Step 2 제거·6단계 전환, Step 4 필드·UI(회사명·서브도메인·약어·관리자 First/Last), 플랜별 팀원 한도(Free/Basic 5, Pro/Ent 10), Step 6 백엔드 연동·관리자 URL. (기존 3개 문서 통합)
  • 테넌트 온보드 후 리소스 할당 플로우·케이스별 관리: tenant-onboard-resource-allocation-flow-plan.md — Submit 후 단계별 리소스 할당 플로우(API·Placement·Queue/workflow·서버 해석·DNS·Ansible·Zuplo·콜백), Control Plane의 현재 Placement·노드·메트릭 관리, 시나리오별(서버 메모리 포화·DB/Redis 증설·패키지별 설치·Ansible/Zuplo limit) 현재 vs 추천 정의. §6 R1~R8 상세 요건. §7 구현 Phase·우선순위·의존성. §8 Runbook·운영 절차 제안. §10 R1–R8 구현 완료 상태·배포·검증 체크리스트 (prego-control-plane, Prego workflow, prego-ansible, Runbook 반영). R7 GET /internal/db-host·워크플로 resolve-server 연동. R2/R8 기준값 env(PLACEMENT_, SATURATION_) 조정 가능. 배포 후 스모크 검증: scripts/smoke-verify-control-plane.sh.
  • Placement 테스트 데이터·시뮬레이션·모니터링 페이지: placement-test-data-and-simulation-dashboard.md — Placement(기존 노드 vs 새 서버) 로직 검증용 Order 10건 테스트 데이터 정의(free/basic/professional/enterprise, sg/us/eu), 초기 상태(시나리오 A/B), 드라이 런 시뮬레이션 vs E2E 프로비저닝 검증 범위, 모니터링 페이지 요건(테스트 데이터 로드·Placement 실행 결과·노드·메트릭·provision_jobs·단계별 타임라인·동적 적층 시각화). 코드 없음.
  • Hetzner·Pulumi·Trial·독립 서버 리소스 모델: hetzner-pulumi-trial-dedicated-server-resource-model.md — 모든 서버 Hetzner, prego-pulumi 연동이 기획서·워크플로에 반영된 여부 확인. 무료 Trial(~3개월) 종료 후 유료 전환/서비스 종료, 처음부터 유료·독립(전용) 서버(테넌트당 Frappe 1 + MariaDB 1 + Redis 1 = 3대) 현재 설계 반영 여부 및 서버 리소스 관리 모델 추천(공유 풀 vs 독립 풀). 코드 없음.
  • 프로비저닝 완료 후 테넌트 URL 테스트: tenant-url-testing-plan.md — www 7단계 생성 URL 검증 요건·테스트 관점(DNS·TLS·도달성·Frappe)·수동 절차·선택 자동화. 코드 없음.
  • DB 분리·사용량 기반 확장: saas-db-separation-and-scaling-plan.md — Frappe와 별도 DB 서버 MariaDB 연동, Pulumi로 DB 서버 프로비저닝·사용량 모니터링 기반 확장(Replica/샤딩), Ansible로 설치·연동. Phase 1(단일 DB 서버) → Phase 2(Primary+Replica) → Phase 3(샤딩) 로드맵.
  • 확장 SaaS 멀티테넌시(Redis·R2): saas-expanded-multitenancy-redis-storage-plan.md — Redis 별도 서버 분리, 각 고객(테넌트)별 저장공간 R2 분리, Full HA(DB+Redis HA)·샤딩·프로비저닝 자동화. 테넌트 100+ 확장 목표.
  • Redis 서버 분리 (Pulumi·Ansible): redis-separation-pulumi-ansible-plan.md — A안 단일 Redis, DB 1/2/3 역할 분리. 설계 목표(테넌트 격리·중앙 집중형 Redis·운영 자동화), Competing Consumers·Throttling·Health Check 인사이트, Phase 1~3 로드맵(L7·K8s·멀티DC). Pulumi Redis VM·방화벽, Ansible redis_server Role·App Redis URL, 전환·롤백·체크리스트.
  • Cloudflare 오케스트레이션·GTape 백업: cloudflare-orchestration-and-gtape-backup-plan.md — Workers 동적 테넌트 라우팅(KV→오리진 프록시), Tunnel Gatekeeper(Zero Trust), GTape 4단계(Soft Delete·스냅샷·R2 Offsite·DiRT 복구 검증). 현재 시스템 적용 방안(Pulumi·Ansible·tenant canonical·R2) 정리.
  • Cloudflare Logpush 기반 통합 로그 관측성: cloudflare-logpush-observability-plan.md — Logpush·R2 중심 중앙 집중형 로그 파이프라인, Golden Signals(에러·지연·트래픽·보안), Phase 1~3 로드맵, 샘플링·PII 마스킹·TTL 운영 전략. 프로젝트 전반 로그 관리 방법.
  • Logpush 이메일·Workers R2 수집: cloudflare-logpush-email-workers-r2-plan.md — 버킷 cloudflare-managed-f6a80c57, Workers Trace Events·HTTP Requests, 경로 workers_trace_events/·http_requests/, 이메일 검증 대시보드 연동·Lifecycle. 구현: infra/logpush_setup.ts(create-all-email-workers·script-name), infra/logpush_r2_lifecycle_example.json, Runbook §1b·§5.
  • Cloudflare 기반 모니터링 (Serverless Observability): cloudflare-based-monitoring-plan.md — Prometheus/Grafana 대체: Analytics Engine·D1·Workers 대시보드·Logpush/R2·알림. Hybrid(인프라 지표 보완) 권장. api-control-plane §16–§17과 연동.
  • Analytics Engine 연동 구현: cloudflare-analytics-engine-implementation.md — 데이터 포인트 스키마·호출 위치. prego-control-plane: wrangler ANALYTICS_ENGINE·src/analytics.ts·index/internal 연동.
  • 커스텀 대시보드 구현: cloudflare-dashboard-implementation.md — D1 기반 메트릭 API·UI 행 구성. prego-control-plane: GET /internal/metrics/summary, GET /internal/dashboard (HTML·Chart.js·Node health), POST /internal/server-metrics (Hybrid). D1 migration 0007 server_metrics.
  • OTP·이메일 통합: 03-auth-otp-email/otp-and-email-consolidated.md — OTP 플로우·템플릿 소유·Zuplo 호출·가독성·Resend 마이그레이션·이메일 전달·템플릿 통합·OTP 입력 UI. (10개 문서 통합)
  • OTP 검증 통합: 03-auth-otp-email/otp-verify-consolidated.md — OTP 검증·passcode 플로우·CORS·네트워크 에러·대시보드 UX·KV 코드 일치(B6). (5개 문서 통합)
  • Docker Hub 스택·Ansible 배포: docker-hub-stack-ansible-deploy-plan.md — Frappe v15 추천 스택(MariaDB 10.6, Redis 6.2, Node/Python 버전), Docker Hub에서 DB·Redis·App 이미지 다운로드·설치, Ansible IaC·네트워크 격리·멱등성·데이터 보존. 패턴 A(서버 분리) vs B(단일 호스트), 현행 prego-ansible과의 정합성.
  • MariaDB 10.6 my.cnf 최적화: mariadb-mycnf-optimization-plan.md — 8GB~16GB RAM·Frappe 특화 파라미터(buffer_pool·flush·연결·utf8mb4), flush_log_at_trx_commit=2 시 R2 백업 병행, Binlog·MySQLTuner.
  • 리소스 사용량 절감(안전 적용): resource-optimization-safe-adoption-plan.md — Noisy Neighbor 방지·Docker Soft/Hard·memswap·Control Plane plan_limits 동적 적용, Redis 튜닝(maxmemory·allkeys-lru), Gunicorn max-requests·jitter, CDN/Static Offload(R2·선행 조건), OOM 90%·CPU 스로틀 모니터링. 기존 시스템 영향 없이 적용 가능한 항목만 단계별 적용 순서·선행 조건 정리. ProxySQL·PyPy·D1 하이브리드는 제외. 요약: resource-optimization-quick-reference.md.
  • Frappe 바로 구축 템플릿·Runbook: saas-frappe-build-templates-and-runbook.md — Redis 3인스턴스(cache/queue/socketio) 분리+HA Compose, App 클러스터 docker-compose+Frappe·nginx, Worker Runbook. 모니터링: Cloudflare 기반 관측성(권장) 또는 Hybrid 시 Prometheus+Grafana(Data Plane 로컬)·테넌트 관측성. 동시 3,000 기준.
  • Ansible Frappe bench rc:127 해결 기획: ansible-frappe-bench-rc127-resolution-plan.md — bench 경로/venv 미생성 원인, 단기(동적 경로)·중기(init 검증)·장기(이미지/Golden Image) 해결안.
  • Frappe Docker 커스텀 이미지(HRMS 포함) 로컬 빌드: frappe-docker-hrms-custom-image-build-plan.md — 공식 이미지(ERPNext만) → bench get-app/apps.json 기반 HRMS 포함 이미지 재빌드, 로컬 빌드 코드 구현용 기획. §10 멀티플랫폼(amd64·arm64만, linux/386 미지원) 빌드·Docker Hub 업로드 가이드(buildx, prego-builder, Builder/Final 2단계, 매니페스트 검증, Production-Ready) 포함.
  • prego-docker GitHub Actions·Docker Hub 푸시: prego-docker-github-actions-docker-hub-plan.md — prego-docker 레포 기준, frappe_docker custom Containerfile + apps.json으로 ERPNext v15·HRMS 멀티아키텍처(linux/amd64, linux/arm64) 이미지 빌드, GitHub Actions로 Docker Hub(iamfork/prego-erpnext) 푸시 기능 개발 기획. 워크플로우·Secrets·태그 전략·Hetzner CPX 사용법 명세.
  • prego-docker 코드 구현 상세: prego-docker-implementation-plan.md — prego-docker 폴더 파일 트리·Vendoring·apps.json·build.yml·trivy-scan.yml·prego-saas-app notify-image-rebuild·Secrets·태그 정책. 현재: apps.json에 ERPNext·HRMS·prego-saas-app(태그) 포함, 단일 bench init·repository_dispatch 전용·Verify image apps·Trivy 스캔(정책 Critical 0) 반영. (선택) Production compose·digest 승격·Blue/Green.
  • prego-docker 취약점 수치 미개선 원인·감소 기획: prego-docker-vulnerability-reduction-plan.md — 새 이미지 빌드 후에도 CVE 수(8/51/61/76/2)가 동일한 원인(동일 빌드 입력·베이스·의존성), CVE·레이어 매핑·베이스 digest·apt·Node·pip 개선 단계·정책 유지.
  • prego-docker build 트러블슈팅 (통합): 07-prego-docker/build-troubleshooting.md — exit 128(중복 clone·clone/checkout 실패), 167(시그널 39·OOM), yarn FileNotFoundError, uv resolver 실패 원인·해결 요약. (기존 5개 문서 통합)
  • prego-saas-app 이벤트 → Docker 이미지 빌드 단계: prego-saas-app-event-to-docker-image-build-plan.md — 이벤트·dispatch·빌드 흐름 기획(원안: app_sha 동적 apps.json). 현재 구현: tag 기반·커밋된 apps.json, prego-docker-implementation-plan.md §4·§5.
  • prego-saas-app → prego_saas 마이그레이션: prego-saas-app-to-prego-saas-migration-plan.md — 레포·앱 이름 변경에 따른 prego-docker CI/CD 연동 업데이트 기획.
  • prego-saas-app 코드 구현: prego-saas-app-implementation-plan.md — prego-saas-app 폴더(/Users/marco/prego-saas-app) 생성용 기획. 2-Repo 전략·비즈니스 전용 구조, Phase 1(health_check·Sales Order hook·notify 워크플로)9(Multi-region). Frappe 앱 트리·Doctype 스키마(Prego Tenant, Feature Flag, Plan Feature, Tenant Flag, Usage Metric/Event/Aggregation)·Tenant 프로비저닝 API·Feature Flag·Stripe·Provisioner UI·Usage 과금·Enterprise 분리. 코드 없이 명세만. 구현: Phase 18 + Control Plane 워크스페이스·Plan/Tenant Flag 유일성·Prego Tenant 기본 status·region 필드(Phase 9 준비) — 레포 Pregoi/prego-saas-app.

선택적 후속 작업

  • 보안: Control Plane GET /trace, GET /audit 에 CF Access 또는 API Key 적용.
  • 환경: workflow_dispatch로 region=us/eu 실행 시 별도 승인을 위해 GitHub Environment production-us, production-eu 추가 후 워크플로에서 region별 environment 사용 검토.
  • 메트릭: Autoscaler 전제인 node_metrics_rollups 채우기 — 노드별 메트릭 수집 Worker 또는 에이전트 추가.
  • 대시보드 UI: P3-5 Audit, P5-7 관리자 대시보드 — client-web 또는 별도 앱에서 /audit, nodes/tenants 집계 API 호출 및 UI 구현.
Help