Architecture Decisions: neokapi
These are the Architecture Decisions for the neokapi framework, the open
content and language engine. Everything here is Apache-2.0 and describes the
framework modules: the repository root, the cobra-free host runtime, the shared
CLI base, the kapi binary, Kapi Desktop, and the in-repo plugins.
Each decision describes the current state of its subsystem, not the history
of how it got there. When a subsystem evolves, its decision is updated in place;
the history lives in version control.
Tactical detail (SQL schemas, wire formats, algorithm pseudocode) is separated
into Implementation Notes.
How the corpus is organized
Six series, by concern. A decision's identifier is its series letter and its
position within the series, and it does not change when a neighbour is added or
retired:
| Series | Concern |
|---|
| F: Foundations | what the framework is, what a unit of content is, and how it is identified and serialized |
| E: Engine | how content is read, processed, written, and extended |
| C: Context | what a project knows, where it keeps it, and what governs it |
| S: Surfaces | the CLI, the desktop app, agent surfaces, and the runtime libraries |
| M: Multilingual | what it takes for content to exist in more than one language |
| A: Assurance | how the framework proves it works |
Each series is a directory, and its decisions sort by sidebar_position within
it. The sidebar is generated from the directory: adding a decision means adding a
file, never editing a list.
F: Foundations
| AD | Title | Scope |
|---|
| F-01 | The framework and its modules | the Go modules, go.work, the enforced dependency direction |
| F-02 | The content model | Part and Resource, Block, Run, Overlay, the semantic vocabulary, Layers |
| F-03 | Identity | short ids, the durable content key, occurrences |
| F-04 | The content-model wire schema | the canonical proto, protoconvert, frozen field numbers, the drift guard |
E: Engine
| AD | Title | Scope |
|---|
| E-01 | The processing engine | channel-based streaming, the Executor, parallel block tools, collectors |
| E-02 | The format system | readers and writers, detection, registries, skeletons, non-translatable context |
| E-03 | The tool system | the Tool interface, locale cardinality, annotations, side effects, schemas |
| E-04 | Flows and I/O binding | source and sink bindings, process-only runs, ingest versus run transforms |
| E-05 | The plugin system | manifest-driven out-of-process plugins, the transport modes, presets |
| E-06 | Execution trust | the exec class, per-project consent keyed to the approved argv |
| E-07 | Model and translation providers | the model provider interface, machine-translation backends, credentials |
| E-08 | Document structure tiers | tagged structure versus geometric reconstruction, the native and browser readers |
C: Context
| AD | Title | Scope |
|---|
| C-01 | The project model | the kapi.yaml recipe, the committed .kapi/ layout, the store interface, ProjectContext |
| C-02 | Coordinates and governance | the product × channel space and the declared axes, per-file resolution, validity windows |
| C-03 | The context store and graph | .kapi/work/store.db, the shared subsystem tables, the property graph and its query shapes |
| C-04 | Unit state and the decision record | .kapi/state/, the working set, document identity, kapi commit, basis and target-hash staleness |
| C-05 | Freshness and the composite ref | one ref per stream, compare-and-swap per component, the staleness gate |
| C-06 | Context retrieval | by location and by content, on the CLI and over MCP |
| C-07 | Voice profiles | the profile model, starter packs, the vocabulary and voice checks, scoring |
| C-08 | Terms | the concept model, the committed source, tiered lookup, validity |
| C-09 | Content memory | tiered matching, entity generalization, version chains and governed reuse, the two-stage rebuild |
| C-10 | Redaction and clearance | the placeholder model, the local vault, the three policy readers |
S: Surfaces
| AD | Title | Scope |
|---|
| S-01 | The kapi CLI | the command tree, output formats, the credential store, exit codes |
| S-02 | Kapi Desktop | the desktop app, the project home and point map, the Context hub, governance editing, runs through the up venue |
| S-03 | Agent surfaces: MCP and skills | the embedded skill, the curated MCP surface, apply_edits and the review verbs |
| S-04 | Toolbox utilities | the multi-call binary, block-text projection, exit codes |
| S-05 | The i18n runtime for React | the runtime, build-time extraction, re-attach, in-context review |
| S-06 | The visual editor data model | the render projection, the shared preview kit, the edit round-trip |
M: Multilingual
| AD | Title | Scope |
|---|
| M-01 | Bilingual format interop | the extract and merge round trip, target alignment, exchange carriers |
| M-02 | Segmentation | the stand-off overlay, the engine registry, per-project selection |
| M-03 | Multimodal content | image, audio and video extraction, confidence-gated escalation, provenance |
| M-04 | Math and equations | the equation converter, formula blocks, translatable prose inside math |
| M-05 | Prompts and batching | the prompt library, batching, the placeholder protocol |
| M-06 | Content packages | the block bundle and the project parcel |
| M-07 | Metadata in other languages | tool, format and plugin metadata, compiled catalogs |
A: Assurance
| AD | Title | Scope |
|---|
| A-01 | Testing and documentation | the test pyramid, the eval bands, the docs site and its pseudo-locale, recordings |
| A-02 | Parity with the Okapi Framework | the parity harness, the local report, faithful output |