Files

th-kim0823 af8c162e09 docs(components): per-group contributor reference (12 그룹)

docs/components/<group>/README.md 12 페이지 + 인덱스 작성. 각 그룹
페이지가 구성 crate 표 + 구조 mermaid + data flow mermaid + 주요
type/trait/함수 시그니처 + 외부 의존 + 핵심 결정 (HOTFIXES + spec
의 "왜" 통합) + 관련 spec/HOTFIXES 링크. 인덱스가 그룹 wiring
다이어그램 + 진입 가이드 보유.

ARCHITECTURE.md 의 ASCII crate 의존 그래프를 mermaid flowchart 로
교체 (등가 정보, Gitea/GitHub 자동 렌더). docs/components/ 진입
링크 추가.

이 layer 는 contributor 향 — 사용자 향 grand picture 는 README.md
의 logical-architecture diagram 그대로 유지. 진척도는 HANDOFF.md,
per-task spec 은 tasks/INDEX.md 가 기존대로 source of truth.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-04 15:05:32 +09:00

4.8 KiB

Raw Blame History

Components

책임 단위 그룹별 contributor 향 상세. 사용자 향 grand picture 는 README.md, 상위 crate 의존 그래프 + 디렉토리 구조 + locked-in 결정은 docs/ARCHITECTURE.md, 진척도는 HANDOFF.md, per-task spec 은 tasks/INDEX.md.

각 그룹 페이지는 동일 템플릿: 구성 crate / 구조 다이어그램 / data flow 다이어그램 / 주요 type / 외부 의존 / 핵심 결정 (HOTFIXES + spec 의 "왜") / 관련 spec / HOTFIXES.

그룹 wiring

12 그룹 간 호출/의존 흐름. 점선 = Foundation 이 모두에 의존. UI 는 App facade 만 통해 다른 그룹 도달.

flowchart TB
    subgraph Surfaces ["UI surface"]
        UI["UI<br/>(cli + tui)"]
    end
    subgraph Orchestration ["orchestration"]
        AppFacade["App facade<br/>(kebab-app)"]
        RAG["RAG"]
        Eval["Eval"]
    end
    subgraph IngestPipe ["ingest pipeline"]
        Source["Source"]
        Parse["Parse"]
        NormChunk["Normalize+Chunk"]
    end
    subgraph IndexQuery ["index + retrieval"]
        Embed["Embed"]
        Store["Store"]
        Search["Search"]
    end
    subgraph Generation ["generation"]
        LLM["LLM"]
    end
    Foundation["Foundation<br/>(core + parse-types + config)"]

    UI --> AppFacade
    AppFacade --> Source --> Parse --> NormChunk
    NormChunk --> Store
    NormChunk --> Embed --> Store
    AppFacade --> Embed
    AppFacade --> Search
    Search --> Store
    Search --> Embed
    AppFacade --> RAG
    RAG --> Search
    RAG --> LLM
    RAG --> Store
    AppFacade --> Eval
    Eval --> AppFacade
    Eval --> Store

    Foundation -.-> Source
    Foundation -.-> Parse
    Foundation -.-> NormChunk
    Foundation -.-> Embed
    Foundation -.-> Store
    Foundation -.-> Search
    Foundation -.-> LLM
    Foundation -.-> RAG
    Foundation -.-> AppFacade
    Foundation -.-> UI
    Foundation -.-> Eval

그룹 목록

그룹	역할	페이지
Foundation	도메인 type + 설정 + parser IR. 모든 crate 의 zero-dep 토대.	foundation/
Source	워크스페이스 walk + .kebabignore + BLAKE3 checksum → `RawAsset`.	source/
Parse	bytes → `ParsedBlock` (md) 또는 `CanonicalDocument` (pdf/image). OCR + caption 어댑터.	parse/
Normalize+Chunk	`ParsedBlock` → `CanonicalDocument` lift (markdown only) + 모든 미디어 → `Vec<Chunk>` (md/pdf 변종 chunker).	normalize-chunk/
Store	SQLite (V001-V005, FTS5, jobs, chat sessions) + LanceDB (per-model vector 테이블) two-phase write.	store/
Embed	`Embedder` trait + fastembed-rs 어댑터 (multilingual-e5-small 384d).	embed/
Search	lexical (FTS5 BM25) + vector (ANN) + hybrid (RRF) — `Retriever` trait 3 변종.	search/
LLM	`LanguageModel` trait + Ollama HTTP 어댑터 (`gemma4:e4b` default). streaming + cancel-safe.	llm/
RAG	retrieve → gate → pack → generate → cite-validate → persist 9 stage pipeline. multi-turn 지원.	rag/
App facade	`kebab-app` — 모든 UI binary 의 유일한 진입점. `*_with_config` companion 패턴.	app-facade/
UI	`kebab-cli` (`--json` wire envelope) + `kebab-tui` (4 패널 + Mode machine + cheatsheet).	ui/
Eval	golden query 회귀 평가 + run-vs-run compare. `must_contain` rule-based.	eval/

진입 가이드

처음 읽는다면 (의존성 따라 bottom-up):

Foundation — 다른 모든 페이지가 참조하는 type 정의. AssetId / DocumentId / Chunk / Citation / 5 version 등.
Source → Parse → Normalize+Chunk → Store — ingest pipeline 흐름.
Embed → Search — retrieval.
LLM → RAG — generation.
App facade — 위 전부 wiring.
UI — facade 위.
Eval — 독립.

특정 작업 별 진입:

새 미디어 타입 추가 (예: epub) — Parse → Normalize+Chunk → Store (chunker_version) → App facade (라우팅).
새 retrieval 모드 — Search → App facade (mode dispatch) → UI (--mode flag).
새 LLM 어댑터 — LLM (trait crate, 새 type 금지) + 새 kebab-llm-<provider> crate → App facade (config provider switch).
TUI 신규 pane — UI 만. Mode + Theme + InputBuffer 재사용.

다이어그램 제약

각 그룹 페이지의 다이어그램은 mermaid (Gitea / GitHub 자동 렌더). 페이지 별 최소 2개 — 구조 (type/trait/struct 관계) + data flow (입출력 흐름). 실제 코드와 시그니처 일치 — 작성 시 crates/kebab-<name>/src/lib.rs 직접 읽음 (추측 금지).

4.8 KiB Raw Blame History