Architecture Decisions: neokapi
These are the Architecture Decisions for the neokapi framework, the open
content 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. When a subsystem
evolves, its decision is updated in place, and 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, so adding a decision means adding a
file.
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 |
| E-09 | The change contract | the change set, revisions and preconditions, the change service, homes and the file home, the commit hooks |
C: Context
| AD | Title | Scope |
|---|
| C-01 | The project model | the kapi.yaml recipe, the .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 | the checkout's projection at .kapi/work/store.db, the workspace holding each project's context store, the property graph and its query shapes |
| C-04 | Block state and the decision record | the decision ledger, document identity, the shards a checkout writes, 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 word-rule and voice checks, scoring |
| C-08 | Terms | the concept model, the terms store, 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 |
| C-11 | Context operations | the append-only operation log, candidates that advise, the policy for who decides |
| C-12 | Places | the gazetteer a geo axis reads, declared places, containment and overlap, the map's outlines |
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 and its four habits, the curated MCP surface, the context write tools, the edit tools over the change contract and the review tools |
| 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 suite in the bridge repository, its scheduled report, faithful output |