Architecture Overview

Dokime is a product-specific layer over Harmos. The architecture keeps product meaning independent from runtime machinery and keeps every external interface as an adapter over one runtime authority.

flowchart TB
    subgraph Product Meaning
      A[dokime-api]
      D[dokime]
      PL[Product definition crates]
    end
    subgraph Product Machinery
      H[Harmos substrate]
      R[dokime-app]
      HC[dokime-host]
    end
    subgraph Interfaces
      CLI[dokime-cli]
      API[dokime-server]
      GUI[dokime-gui]
      PY[dokime-python]
    end
    A --> D
    D --> R
    A --> R
    D --> PL
    H --> R
    A --> HC
    HC --> R
    PL --> R
    PL -. register from loaded sidecar .-> R
    R --> CLI
    R --> API
    API --> GUI
    R --> GUI
    R --> PY

Ownership Rules Visible In The Code

• dokime-api owns the contracts every party compiles: what a suite declares, what a record or telemetry channel promises, what a prompt asks, what a document lays out, and what an installed artifact contributes. Data and serde only, with no Harmos dependency, no gates, and a wasm32 check to prove it.
• dokime is the SDK kit a plugin author compiles: the authoring macros, the execution context, registration, the sidecar wire, and the evaluators over those contracts. It layers on dokime-api and re-exports every contract module under its original path, and it never depends on the app.
• dokime-app owns what the application is and how a runtime runs it: the folded state/, the closed transactions/ vocabulary that is the only way that state changes, the streams/ it publishes, the traceability/ projections read from it, and capabilities, commands, queries, jobs, storage assembly, sidecar composition, and shutdown. It depends on dokime; the edge never points back.
• dokime-app::app declares Dokime as a Harmos Application and holds its entry verbs: builder, launch, and the sim-gated simulate. It composes only; every construction lives with the module that owns it.
• Interfaces import the runtime and do not own alternate state machines. A shell owns the process side effects the application crate must not: dotenv, the tracing subscriber, the config source, and rendering an error once.
• Plugins and sidecars import dokime and, through it, dokime-api — never dokime-app. The only dokime-app entries under plugins/ are [dev-dependencies], where a test drives a real host.
• dokime-app::capabilities::installed_artifacts names trusted builtins and shipped sidecar files in ordinary Rust code; loaded sidecars register their own suites and domains. Dokime has exactly two delivery paths: in-process and sidecar.
• Harmos owns the general journal, snapshot, work, series, artifact, installed artifact, and sidecar facilities.

The current persistence architecture is a clean break from the former Keel runtime. Legacy files are intentionally left untouched, not migrated in place.