Architecture at a glance
This page explains what Kaizen is made of and how a request moves through it. You do not need any of it to use Kaizen — it is here for evaluators, operators, and anyone integrating with the system.
The big picture
The clearest way to understand Kaizen's architecture is to zoom in one level at a time — from the system as a whole, to the services it runs, to what is inside the busiest one. Each diagram is a closer look at the box in the middle of the one before it.
Switch from system context to service topology, then open the trusted backend boundary.
Other views: Context · Services · Backend
Level 1 — Kaizen in context
At the widest view, Kaizen is a single system with people on one side and other systems on the other. Members search and chat; admins configure it. Kaizen leans on the Kamiwaza platform for identity, models, and a runtime-discovered connector catalog. The platform also owns consent and delegated authority for held unattended Tasks. Connector reads execute under the signed-in member's platform identity; optional write integrations remain separately policy-gated.
Level 2 — The services
Zoom into Kaizen itself and it is not one program but a set of cooperating services. The key idea: the api-backend owns everything that must be trustworthy — permissions, retrieval, budgets, and the audit log — while the agent-runtime owns the conversational loop and calls back into the backend for every tool it uses.
Level 3 — Inside the backend
Zoom into the api-backend — the service that does the most. The Member API receives every request; Search and the Agent bridge both draw on one shared Retrieval component; and Guardrails & policy sit across every tool call, enforcing ACL, budgets, approvals, and the audit trail.
The two-service split
Almost everything distinctive about Kaizen's design follows from one decision: the conversational loop and the authority to act live in different processes.
The agent-runtime is deliberately powerful and deliberately empty. It plans a turn, decides which tool to call, incorporates results, and decides when the answer is done. It holds no credentials, no member data, and no policy.
The api-backend holds all of it. Every time the runtime wants to do something — search, read a document, run code, manage a task, delegate — it calls back into the backend, which resolves the member's permissions, applies policy and budgets, executes the tool, records the result, and returns a bounded projection.
That split is why Kaizen can be both capable and safe. A prompt injection, a model mistake, or a novel jailbreak changes what the runtime asks for. It cannot change what the backend allows.
See Anatomy of a chat turn for the loop in detail, and Services & responsibilities for what each process owns.
Design principles
Permissions are enforced in the query, not filtered afterward. Lexical and semantic branches both consume the current authorization relation inside PostgreSQL before any row becomes a candidate. Raw candidate IDs and text never reach application code for post-filtering. See Retrieval & ranking.
The backend owns policy. Guardrails are part of the backend, not the runtime, so they apply regardless of how the conversational loop behaves.
Isolation for anything risky. Code execution and third-party package code run in separate, locked-down environments with controlled egress and no access to the trusted service's secrets.
Implement cross-agent behavior once. Streaming, journal projection, retries, timeout salvage, durability, grounding, lifecycle, policy, and error handling live in the shared pipeline. An individual agent defines only its persona, capabilities, tool grants, and source selection. This is what makes "every agent behaves the same way" a structural property rather than a promise.
Fail closed. When authority cannot be proven — a missing lease, a drifted definition, an unavailable authorization path — Kaizen denies. It never falls back to a weaker check, a stored snapshot, a workload identity alone, or an owner's authority.
Where data lives
| Store | Holds |
|---|---|
| PostgreSQL | System of record: conversations and their journals, the search index, documents metadata, agents, prompts, Projects, tasks, occurrences, runs, traces, audit |
| Valkey | Ephemeral only: opaque Core run references, short-lived leases, presence, queue state. Never schedules, member identity, assertions, capabilities, proof keys, credentials, or authority state |
| Object store | Uploaded file bytes, exports, artifacts, sandbox workspace snapshots |
Nothing about your identity is trusted from the browser. Kamiwaza authenticates, and the backend maps that to permissions on every request. See Data model & storage.
Where to go next
- Anatomy of a search — the non-generative path
- Anatomy of a chat turn — the generative path
- Conversation journal & durability — how a run survives failure
- Security model overview — the trust boundaries
- Deployment topology — the same picture, as processes to run