Architecture diagrams
For the complete visual learning path, see the VAK Architecture Tutor, which includes the layered crate map and the detailed request, agent, ledger, security, delivery, configuration, flow, memory, desktop, Doctor, and Operations diagrams.
Self-contained, interactive HTML documents describing how vak is put together. Open any file in a browser — no build step, no external assets.
| File | What it covers |
|---|---|
layered-architecture.html | The static crate map: all 18 workspace crates + 2 SolidJS frontends, arranged as a five-layer dependency stack (foundations → surfaces). |
runtime-topology.html | The runtime view: which processes exist, who hosts a Core, the gateway/channel request path, and what is shared-central vs. private-and-local. |
concurrency-model.html | An animated walkthrough of what happens when many calls arrive at once — same session (ledger lock → 409/steering), many sessions (one Core, rate limit), and many workspaces (CorePool eviction). |
vak-works.html | The vak Works — a playable, gamified view of the internals. Every component is a building and every message is a courier who walks the route: channels sit outside a trust perimeter, bridges are separate processes holding bot tokens, the gatehouse checks the allowlist, the bindings board writes bindings.json, cores are built and demolished in the pool, and the ledger tower only ever grows. Press Trace a message to follow one courier's entire life step by step, or click any courier to pick them up mid-route. |
day-simulation.html | A live 24-hour load simulation of a vak serve --gateway host: a diurnal load curve with injected incidents (morning surge, provider-429 storm, lunch dip, workspace fan-out, traffic burst, nightly unattended batch), live component tiles, and a Grafana-style ops chart (throughput, latency p50/p95, concurrency/queue, errors/retries/auto-deny). Press Play day. |
write-paths-and-growth.html | Write paths & growth: every durable artifact (from vak_core::state::REGISTRY and the crates that write it), the exact write sequence of one turn with its fsync count, measured per-turn byte costs from a real data home (13 entries / 66 KB per turn; 72% of ledger bytes are the per-turn turn_capabilities_bound record; checkpoints outweigh sessions), which per-turn reads stay flat versus scale with session or home history, a 1k/10k/100k-turn projection, and seven growth levers that change no public signature. |
All are derived from the workspace manifests, README.md, PRODUCT.md,
DESIGN.md, and the source under crates/vak-server, and use vak's own design
tokens so they read as part of the product.
The load figures in
day-simulation.htmlare a synthetic model calibrated to the real constants (rate_limit.rs— 10 runs/min/IP;core_pool.rs— 4+1 slots;15-reliability.md— retry ladder + circuit breaker), not measured production telemetry.