Architecture Decisions — neokapi Framework
This directory contains the Architecture Decisions for the neokapi framework
— the open localization 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 |
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·klz·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 Localization | image as localizable asset; kapi-vision OCR (PP-OCRv5) + layout (PP-DocLayoutV3), path-based, localization modes |
Project Model
| AD | Title | Scope |
|---|---|---|
| 008 | Project Model | .kapi recipe, .kapi/ state, BlockStore interface, ProjectContext |
Intelligence
| AD | Title | Scope |
|---|---|---|
| 009 | Translation Memory | Sievepen, tiered matching, generalized matching with entities |
| 010 | Terminology | Concept model, TermBase, 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 |
| 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 |