Architecture Decisions — neokapi Framework

This directory contains the Architecture Decisions for the neokapi framework — the open content and language engine. All content here is Apache-2.0 licensed and describes modules at the repository root (github.com/neokapi/neokapi), the shared CLI base (github.com/neokapi/neokapi/cli), the kapi CLI (github.com/neokapi/neokapi/kapi), and Kapi Desktop (github.com/neokapi/neokapi/kapi-desktop).

Tactical implementation details (SQL schemas, wire protocols, algorithm pseudocode) are separated into Implementation Notes.

Foundation

AD	Title	Scope
001	Vision and Modules	Go modules, go.work, dependency boundaries, license gradient
002	Content Model	Part/Resource, Block, Run, Overlay, semantic vocabulary, Layers
003	Identity	Base62 IDs, dual block identity
034	Content-Model Wire Schema	canonical neokapi.content.v1 proto + protoconvert, labeled projections, frozen field numbers, guard test

Processing

AD	Title	Scope
004	Processing Engine	Channel-based streaming, Executor, parallel block tools, collectors
005	Format System	DataFormatReader/Writer, detection, registries, skeleton strategies
006	Tool System	BaseTool, locale cardinality, annotations, side effects, schemas
007	Plugin System	manifest-driven out-of-process plugins, gRPC, presets, Okapi bridge
021	SaT Segmenter Plugin	in-process ONNX SaT model, stdin/stdout protocol, native-stack isolation, sat engine
026	Flow I/O Binding	source/sink bindings, file·store·kpz·import/export, process-only runs, ingest vs run transforms
028	PDF Reader & Structure Tiers	PDFium native plugin + browser WASM, geometry/glyphs, tagged + geometric structure tiers
029	Vision & Image Adaptation	image as adaptable asset; kapi-vision OCR (PP-OCRv5) + layout (PP-DocLayoutV3), path-based, adaptation modes
030	Multimodal Extraction & LLM Refinement	confidence-gated escalation across image/audio/video; MediaAnchor + ExtractionProvenance overlays, multimodal aiprovider, generic media-refine Transform, kapi-asr/video symmetry
031	Content-Fidelity Surfacing	readers surface non-translatable context (code/captions/formulas) as Block{Translatable:false} for LLM/RAG ingestion; default-ON extractNonTranslatableContent opt-out; byte-exact + parity-safe
032	Math & Equations	cgo-free OMML→AST→MathML/LaTeX converter (core/math), RoleFormula blocks + Equiv/Disp carriers, OMML sub-skeleton for translatable <m:nor> prose, markdown/doclang rendering

Project Model

AD	Title	Scope
008	Project Model	kapi.yaml recipe, .kapi/ state, BlockStore interface, ProjectContext

Intelligence

AD	Title	Scope
009	Content Memory	memory/ store, tiered matching, generalized matching with entities
010	Terminology	Concept model, Terminology, tiered lookup
011	AI Providers	LLMProvider, streaming, batching, worker pool
012	MT Providers	MTProvider interface, built-in backends
022	Brand Voice	VoiceProfile, starter packs, vocab/voice checks, scoring, command + MCP surface

Applications

AD	Title	Scope
013	Kapi CLI	Standalone CLI, output formats, credential store, MCP server
014	Kapi Desktop	Wails v3 app, flow editor, runner, plugin manager
019	Kapi React	React i18n runtime, build-time extraction, __tx re-attach
035	In-Context Review	DOM stamping, KBF write-back over a dev middleware, Highlight-API term/QA painting
023	Toolbox Utilities	kcat/kgrep/ksed busybox multi-call, block-text projection, exit codes
024	Agent Skills	embedded SKILL.md routers, .claude/skills install, kapi-/bowrain- split
027	Visual Editor	ContentTree→RenderDoc projection, vocabulary/overlay rendering, shared preview kit, edit→commit round-trip

Cross-Cutting

AD	Title	Scope
015	Testing and Documentation	Test pyramid, Docusaurus, screenshots, recordings
016	Metadata i18n	Tool/format/plugin metadata translation via MO catalogs
017	Bilingual Format Interop	XLIFF/PO/TMX bilingual round-trip, target alignment
018	Parity Testing	Okapi parity harness, test-comparison dashboard, faithful%
020	Content Redaction	Placeholder model, local vault, rule/entity detection, secure-translate, extract/merge
038	Execution Trust	exec-class tools and formats, per-project consent keyed to the approved argv, per-surface answers