Public docs-only mirror of a private B2B AI customer-service SaaS reference implementation. 私有项目 Cuckoo-Echo 的公开架构文档镜像。
This repository is a documentation showcase of Cuckoo-Echo, a single-author reference implementation of a multi-tenant AI customer-service SaaS platform. It contains:
- The system architecture document
- 9 Architecture Decision Records (ADRs) covering the most important trade-offs
- 3 representative production runbooks
- Performance baseline & capacity planning notes
It does not contain source code, tests, prompts, OpenSpec proposals, or migration scripts. Those live in the private parent repo and are shared with prospective clients on a per-engagement basis (see Source access).
本仓库是 Cuckoo-Echo 的纯文档橱窗，用于公开展示这个企业级 AI 客服 SaaS 参考实现的架构与运维成熟度。不包含源代码——源码、测试、Prompt、OpenSpec 提案、迁移脚本等都留在私有主仓库，按客户合作意向单独邀请访问。
This is one corner of a three-repo showcase triangle covering my main practice areas:
- You are here — multi-tenant AI SaaS architecture (this repo)
- cicd-platform-showcase — CI/CD & release governance (incremental CI, ArgoCD GitOps, canary + SLO gating)
- observability-platform-showcase — observability platform (OTel, structured logging, alert layering, tail-sampling)
All three are docs-only and intentionally cross-reference where decisions span domains.
- Type / 类型：Reference implementation, single-author / 单人设计与实现的参考架构
- Domain / 领域：B2B SaaS AI customer service / B 端 AI 智能客服
- Status / 状态：v1.0.0 shipped, not in production / v1.0.0 已 ship，未承载真实生产流量
- Codebase size / 代码量：~72,500 LOC (Python + TypeScript), 590+ commits / 约 7.25 万行，590+ 提交
- Architecture form / 架构形态：Modular monolith deployed as service-shaped units — see ADR-0001
What separates this from a typical demo project:
| Artefact / 类别 | Count / 数量 | Where / 位置 |
|---|---|---|
| Architecture Decision Records (ADRs) | 9 | docs/adr/ |
| OpenSpec design proposals (shipped + archived) | 80+ | private repo |
| Production runbooks | 15 | private repo (3 sampled here) |
| Oracle-driven audit rounds (security / refactor / dead-code) | R1–R20 | CHANGELOG, private repo |
| Alembic migration versions | 24 | private repo |
| Tests | 847 unit + PBT + E2E + load | private repo |
| Test layers | unit / property-based (Hypothesis) / integration / E2E (Playwright) / architecture-boundary / load (Locust) / RAG-quality (Ragas) | — |
| Layer / 分层 | Technology | Why / 为什么选它 |
|---|---|---|
| API framework | FastAPI + SSE / WebSocket | Async-native, token-by-token streaming |
| ASGI server | Granian (prod) / uvicorn (dev) | Rust-based, higher per-core throughput |
| Agent orchestration | LangGraph StateGraph | HITL breakpoints, checkpointer, conditional routing — see ADR-0002 |
| LLM gateway | LiteLLM | OpenAI-compatible multi-vendor routing + fallback |
| Vector DB | Milvus 2.5+ | PartitionKey isolation + built-in BM25 hybrid — see ADR-0003 |
| Database | PostgreSQL + RLS | Row-level tenant isolation — see ADR-0004 and ADR-0005 |
| Cache / locks | Redis | Distributed locks, rate limiting, key-prefix isolation |
| Document parsing | Docling (IBM) | Unified PDF / DOCX / HTML / TXT pipeline |
| Embedding & rerank | Sentence-Transformers + BGE Reranker v2 | Two-stage retrieval |
| Observability | Langfuse + Prometheus + OpenTelemetry | LLM trace + metrics + cross-service spans |
| Package manager | uv | Rust-based dependency resolver |
Standalone diagrams in diagrams/ (Mermaid source + 1600px PNG + transparent SVG). Use them as resume attachments, slide backgrounds, or email enclosures — they are designed to read on their own without context from this repo.
| Topic | |
|---|---|
 |
01-system-overview — full system topology |
 |
02-tenant-isolation — three-layer multi-tenant isolation |
 |
03-cicd-flow — CI → ArgoCD → Flagger canary + SLO gate (cross-references cicd-platform-showcase) |
 |
04-observability-pipeline — OTel pipeline + three-tier alerting (cross-references observability-platform-showcase) |
Re-render from source: ./diagrams/render.sh (requires @mermaid-js/mermaid-cli). See diagrams/README.md for details.
cuckoo-echo-showcase/
├── README.md ← you are here
├── LICENSE ← MIT
├── diagrams/ ← standalone architecture diagrams
│ ├── README.md
│ ├── render.sh ← re-render .mmd → .png + .svg
│ ├── 01-system-overview.{mmd,png,svg}
│ ├── 02-tenant-isolation.{mmd,png,svg}
│ ├── 03-cicd-flow.{mmd,png,svg}
│ └── 04-observability-pipeline.{mmd,png,svg}
└── docs/
├── architecture.md ← system architecture, data flow, isolation layers
├── performance.md ← TTFT SLA targets + local baseline (honest disclaimer)
├── capacity-planning.md ← scaling assumptions, bottleneck analysis
├── adr/
│ ├── README.md ← ADR index
│ ├── 0001-microservices-vs-monolith.md
│ ├── 0002-langgraph-agent-framework.md
│ ├── 0003-milvus-for-vector-search.md
│ ├── 0004-rls-multi-tenancy.md
│ ├── 0005-shared-database.md
│ ├── 0006-pkce-oidc.md
│ ├── 0007-feedback-dual-implementation.md
│ ├── 0008-chat-service-defense-in-depth-auth.md
│ └── 0009-fold-thin-services.md
└── runbooks/
├── production-launch-checklist.md
├── llm-provider-failover.md
└── dr-drill.md
For a 10-minute walkthrough:
docs/architecture.md— system layout & three-layer tenant isolationdocs/adr/0001-microservices-vs-monolith.md— why this is not textbook microservicesdocs/adr/0004-rls-multi-tenancy.md— how RLS replaces "one DB per tenant"docs/adr/0002-langgraph-agent-framework.md— agent orchestration choicedocs/runbooks/production-launch-checklist.md— ops maturity surface
The full source repository is private. If you are evaluating this as a body of work — for hiring, contracting, due diligence, or technical assessment — open an issue here or reach me directly. I'll grant time-boxed read access to the private repo and walk through any path you want.
完整源码仓库 不公开。如果你正在做技术评估、面试评判、外包尽调或合作前考察，请在本仓库开 issue 或直接联系我，我会给你有限时长的只读访问权限，并按你关心的路径做 walkthrough。
- This is a single-author reference implementation. It has never carried real production traffic.
- All performance, capacity, and SLA numbers in the documents are local Docker Compose baselines or design targets, not measured production figures. Each document is explicit about which is which.
- AI coding tools (e.g. OpenCode, Claude Code) participated in implementation. Architecture, ADRs, technical decisions, code review, and final quality control are author-driven — see the ADR archive and the OpenSpec audit history (R1–R20) in the private repo for evidence.
本项目为单人参考实现，从未承载真实生产流量；所有性能与容量数字均为本机基线或设计目标，每份文档均明确标注。AI 编码工具参与了实现细节，架构决策、ADR、Review 与最终代码质量由作者把关——证据见私有仓库的 ADR 目录与 R1–R20 审计历史。
MIT — applies to the documentation in this showcase repository.