Docs / Architecture

Architecture

Kraftverk is a Cargo workspace of first-party crates with a hard ceiling (≤10) to discourage artificial micro-crates. The product framing is the evidence loop; the implementation is a session that inspects, measures, searches, and persists.

Evidence loop

Measure → Experiment → Validate → Improve, then learn and repeat.

Crate layout

Crate	Role
`kraftverk-core`	Domain models, errors, stats, Kraft Index, goals/constraints
`kraftverk-system`	Platform trait, Native/Mock, recovery journal, hardware eligibility, telemetry
`kraftverk-bench`	KraftBench workloads + suite runner
`kraftverk-optimizer`	Search strategies + profile catalog
`kraftverk-data`	SQLite experiment store + reports + sessions
`kraftverk-agent`	Privileged agent IPC types (scaffold in 0.2)
`kraftverk-sdk`	Programmatic facade
`kraftverk-cli`	User-facing binary / optimize orchestration
`kraftverk-desktop`	Local engineering instrument UI

Control flow

CLI → open_session (inspect fingerprint, open DB, recover journal)
    → baseline/benchmark: KraftBench samples → Kraft Index → SQLite
    → optimize: SearchStrategy proposes Candidate
         → ApplyGuard (journal + apply/verify)
         → KraftBench samples → compare vs baseline
         → rollback (search) or commit (validated accept)

flowchart TB
  CLI[kraftverk-cli] --> SYS[kraftverk-system]
  CLI --> OPT[kraftverk-optimizer]
  OPT --> BENCH[kraftverk-bench]
  OPT --> SYS
  BENCH --> CORE[kraftverk-core]
  CLI --> DATA[kraftverk-data]
  DESK[kraftverk-desktop] --> DATA
  AGENT[kraftverk-agent] -.->|scaffold IPC| SYS

Platform boundary

Callers never branch on OS. Platform (in kraftverk-system) exposes capabilities/topology, read/apply/verify/rollback, and a mock-only score multiplier. MockPlatform simulates deltas, noise, failed applies, throttling, and unsupported keys for tests.

Persistence

SQLite stores fingerprint, versions, OS info, candidate JSON, parent id, samples, stats, telemetry, stability, score, accept/reject reason, and timestamps.

Privilege separation

Safe opts run in-process today. kraftverk-agent defines request/response types for a future authenticated local IPC channel. Privileged agent execution remains a scaffold in 0.2 — treated as experimental, not a finished security boundary.

Optimizer · Safety · security.md