VAK Architecture Tutor
This is the visual guide to VAK: start with the system map, follow one request through the runtime, then use the deep dives to understand trust, execution, state, delivery, and operations.
Recommended path
- System overview
- One request end to end
- Normal vs managed flow
- Inside the runtime
- Trust, configuration, and execution
- State, delivery, and operations
- Personal OS and user surfaces
1. System overview
Layered architecture
The complete crate map, organized from user surfaces and gateway operations down to orchestration, policy, intelligence, delivery, persistence, and infrastructure.
2. One request end to end
Request lifecycle
Shows the common path for desktop, CLI, web, Telegram, Discord, and Slack: normalize identity, resolve trust and routing, freeze the session, authorize, execute, and deliver.
Gateway, channels, and trust
Explains channel bridges, bot-scoped identities, allowlist states, the bot → chat → workspace policy chain, route resolution, and safe outbound adapter selection.
3. Normal vs managed flow
Normal vs Managed Flow
Contrasts the fast direct agent loop with Managed Flow’s durable WorkContract, work items, ownership, evidence, checkpoints, and verified completion.
Flows, planner, and evaluation
Explains static DAGs, dynamic candidate plans, validation, deterministic repair, bounded replanning, governed node execution, and evaluation boundaries.
4. Inside the runtime
The vak-core runtime facade
Shows how a workspace-scoped Core composes configuration, sessions, providers, agent execution, policy, tools, persistence, delivery, and operational features for every entry point.
Inside one agent turn
Follows admission, context projection, provider streaming, assistant messages, the stop gate, tool waves, workers, managed work, goal mode, receipts, checkpoints, and final outcomes.
5. Trust, configuration, and execution
Permission and tool security
Shows the enforcement boundary: PermissionEngine → approval → brokered registry → validated operation → worker → Seatbelt/Landlock/Docker → bounded result.
Configuration, routing, and runtime contract
Explains global/project/scoped configuration precedence, atomic persistence, route provenance, provider/model freezing, secrets, permission revocation, sandbox selection, and FinOps limits.
6. State, delivery, and operations
The append-only session ledger
Explains JSONL entries, parent-pointer trees, model-visible projections, audit-only receipts, compaction, branches, checkpoints, recovery, and the rebuildable search index.
Semantic delivery pipeline
Shows how internal outcomes become OutputTimeline and PresentationDocument values, pass through capability projection and renderers, and reach UI/channel adapters or the retry outbox.
Operations Center
Explains how live handles, service-manager probes, gateway state, Doctor, security events, tasks, and delivery state become an evidence-backed operational projection.
vak doctor
Shows context collection, health checks, facts, report ordering, known mechanical repairs, re-collection, and the fail-closed “never guess” boundary.
7. Personal OS and user surfaces
Memory, learning, and automation
Connects session search, memory tiers, reflection, skill proposals, scheduled tasks, heartbeats, budget admission, inbox, outbox, and governed memory writes.
Desktop, admin, and extensions
Maps the Tauri desktop, SolidJS admin console, tray, CLI/TUI, secured router, SSE projections, operations views, plugins, skills, MCP, hooks, and channel adapters.
Cross-cutting rules
- Every execution path authorizes before dispatch.
- The session ledger is append-only and remains the source of truth.
- Provider and model are one frozen route per session.
- Channel capability overlays can restrict access but never grant secrets.
- Managed work adds durable planning and verification; it does not replace direct chat.
- The service manager owns process liveness; health probes do not compete with
KeepAliveorRestart. - The Operations Center reports evidence, not synthetic metrics.