From bfdb122a8028df311c40583d8c7cd35607ee5413 Mon Sep 17 00:00:00 2001 From: th-kim0823 Date: Mon, 4 May 2026 14:47:28 +0900 Subject: [PATCH] docs(spec): component documentation design (2026-05-04) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per-component README pages under docs/components//, grouped by responsibility (12 groups). Each page carries 구조 + flow mermaid + key-decision rationale consolidated from HOTFIXES + spec. Index page hosts group-wiring diagram; ARCHITECTURE crate graph migrates from ASCII to mermaid. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../specs/2026-05-04-component-docs-design.md | 162 ++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-04-component-docs-design.md diff --git a/docs/superpowers/specs/2026-05-04-component-docs-design.md b/docs/superpowers/specs/2026-05-04-component-docs-design.md new file mode 100644 index 0000000..83b6850 --- /dev/null +++ b/docs/superpowers/specs/2026-05-04-component-docs-design.md @@ -0,0 +1,162 @@ +# Component documentation design + +**Date**: 2026-05-04 +**Status**: planned +**Audience**: contributor / reader who wants per-component depth beyond README + ARCHITECTURE. + +## Goal + +Add a per-component documentation layer under `docs/components/` so that contributors can read a single page per responsibility group and understand: + +- which crate(s) the group contains; +- the internal structure (types / traits / structs); +- the data flow through the group; +- key decisions (and the *why*, often spread across HOTFIXES + spec); +- which spec / HOTFIXES entries the group descends from. + +End-user audience stays served by the existing README. ARCHITECTURE keeps its crate-level depth but its ASCII graph is upgraded to mermaid. + +## Non-goals + +- Re-doing the README user-layer Mermaid (already covers the user grand-picture). +- Editing spec files (frozen) or HOTFIXES content. +- Adding code comments / rustdoc. +- Per-task spec diagrams. +- A separate user-facing tutorial — that stays in README. + +## Output tree + +```text +docs/components/ +├── README.md # index + group wiring diagram +├── foundation/README.md # kebab-core + kebab-parse-types + kebab-config +├── source/README.md # kebab-source-fs +├── parse/README.md # kebab-parse-md + kebab-parse-pdf + kebab-parse-image +├── normalize-chunk/README.md # kebab-normalize + kebab-chunk +├── store/README.md # kebab-store-sqlite + kebab-store-vector +├── embed/README.md # kebab-embed + kebab-embed-local +├── search/README.md # kebab-search +├── llm/README.md # kebab-llm + kebab-llm-local +├── rag/README.md # kebab-rag +├── app-facade/README.md # kebab-app +├── ui/README.md # kebab-cli + kebab-tui +└── eval/README.md # kebab-eval +``` + +The folder + `README.md` pattern means Gitea / GitHub auto-render each group page when navigated to. + +### Why these 12 groups (not 21 crates, not 6 stages) + +- **Trait + impl pairs stay together** (`kebab-embed` + `kebab-embed-local`, `kebab-llm` + `kebab-llm-local`) — the swap pattern is the point of the pair. +- **Same-output parsers grouped** (`parse-md` + `parse-pdf` + `parse-image` all emit `ParsedBlock`) — comparison only makes sense side-by-side. +- **Sequential transforms grouped** (`normalize` → `chunk` are both `ParsedBlock → next stage`). +- **Storage backends grouped** (`store-sqlite` + `store-vector` share the persistence-trait pattern). +- `kebab-app` stays alone — the facade rule is load-bearing enough to deserve its own page. +- `kebab-cli` + `kebab-tui` grouped as UI — both consume facade only, contract identical, surface different. +- `kebab-eval` stays alone — independent of pipeline crates. + +## Per-group page template + +Every `/README.md` follows this skeleton: + +```markdown +# + +> One-line summary — what this group is. + +## 구성 crate + +| Crate | 역할 | +|-------|------| +| kebab-X | … | + +## 구조 + +\`\`\`mermaid + +\`\`\` + +## Data flow + +\`\`\`mermaid + +\`\`\` + +## 주요 type / trait / 함수 + +- `TypeName` — one-line description +- `fn signature(...) -> Result<...>` — one-line description + +## 외부 의존 + +- crate dep: … +- 외부 서비스: … + +## 핵심 결정 + +- **결정**: … + **왜**: HOTFIXES or spec link. + +## 관련 spec / HOTFIXES + +- spec: `tasks/p/p--.md` +- HOTFIXES: `tasks/HOTFIXES.md` (relevant entries) +``` + +Diagram count is fixed at minimum 2 (구조 + flow). More are allowed if needed. + +The "핵심 결정" section is the heaviest — it consolidates the *why* behind decisions that are currently scattered across HOTFIXES entries and frozen spec sections. + +## Index page (`docs/components/README.md`) + +Contains a single mermaid `flowchart` showing group-level wiring (one node per group, arrows for "calls / depends on"), plus a table linking each group page. Example wiring (final exact form drawn after all group pages exist): + +```mermaid +flowchart LR + Source --> Parse --> NormalizeChunk --> Store + NormalizeChunk --> Embed --> Store + Store --> Search + Search --> RAG + Embed --> Search + LLM --> RAG + AppFacade --> Source & Parse & NormalizeChunk & Store & Embed & Search & LLM & RAG & Eval + UI --> AppFacade + Foundation -.-> Source & Parse & NormalizeChunk & Store & Embed & Search & LLM & RAG & AppFacade & UI & Eval +``` + +## ARCHITECTURE.md changes + +- The existing ASCII crate-dependency graph (lines 36–54) is replaced with an equivalent mermaid `flowchart` — same nodes, same edges, same information, better rendering on Gitea / GitHub. +- A single new line added near the top: `> 그룹 단위 view + 컴포넌트별 상세는 [docs/components/](components/).` +- Directory tree, locked-in decisions table, "외부 AI 통합", "비-목표" sections all stay unchanged. + +## Writing order (bottom-up) + +1. **Foundation** — defines types every other page links to (`AssetId`, `DocumentId`, `Chunk`, `Citation`, …). +2. **Source → Parse → Normalize+Chunk → Store** — ingest pipeline order. +3. **Embed → Search** — retrieval. +4. **LLM → RAG** — generation. +5. **App facade** — wires the above. +6. **UI** — sits on facade. +7. **Eval** — independent. +8. **Index `README.md`** — wiring diagram drawn last (so arrows match actual page content). +9. **ARCHITECTURE crate-graph mermaid replacement** — last, since it does not depend on the others. + +## Verification + +Per page: + +- mermaid syntax renders (preview on Gitea or mermaid.live). +- Every type / trait / function signature in the page matches the actual code in `crates/kebab-/src/lib.rs` — author reads source while writing, no guessing. +- HOTFIXES anchor links resolve. + +Across pages: + +- Group wiring diagram in the index does not contradict the crate graph in ARCHITECTURE. +- Bidirectional links: README ↔ ARCHITECTURE ↔ components index ↔ each group page. + +## Risks / notes + +- **Drift**: code changes after these pages land will silently invalidate signatures. Mitigation = page text stays minimal (signatures, not bodies); contributors update the page in the same PR that changes the surface (same rule the README/HANDOFF/ARCHITECTURE trio already follow). +- **HOTFIXES dilution**: if "핵심 결정" copies HOTFIXES entries verbatim, the live source-of-truth duplicates. Mitigation = component pages link to HOTFIXES entries by anchor + summarize in one line, not full quote. +- **Group-count debate**: 12 is a judgment call. If a group page grows past ~250 lines, it is a signal to split (e.g. `parse/` could split into per-format pages later — defer until pressure shows up).