Skip to content

Architecture

This part of the handbook describes Kionga's architecture using the arc42 template. Each section is a separate page, so you can link to one view without pulling in the rest. Every statement is grounded in the code of the Kionga repositories or in an existing record; where the code and a plan differ, the code wins and the gap appears in risks and technical debt.

Kionga in one paragraph

Kionga is a self-hosted, open-source (MIT) platform for machine learning, data and AI agents. A Go control plane (the gateway) owns desired state, identity, authorization and audit. It delegates execution to open-source engines (Prefect, MLflow, LangGraph, Langfuse, OpenFaaS, and on Kubernetes KFP and KServe) and records what they report back. PostgreSQL is the system of record, Kafka carries lifecycle and audit events through a transactional outbox, Redis serves online features, and RustFS provides S3-compatible object storage. The same contracts run on one machine with Docker Compose and on Kubernetes through Helm.

Sections

Section What it answers
1. Introduction and goals What Kionga must do, the quality goals that shape it, and who cares
2. Constraints Technical, organizational and convention constraints the design accepts
3. Context and scope Users and external systems, and the protocols at the boundary
4. Solution strategy The few decisions that shape everything else
5. Building block view The static decomposition, from repositories down to control-plane packages
6. Runtime view Sign-in, a pipeline run, model promotion and serving, and an agent turn
7. Deployment view Local Compose, a single server, and Kubernetes through Helm
8. Crosscutting concepts Identity, authorization, tenancy, configuration, observability, errors, persistence
9. Architecture decisions The decision log, with links to each record
10. Quality requirements The quality tree and scenarios, each tied to a test or a check
11. Risks and technical debt Known weaknesses, read from the code and the implementation status
12. Glossary Terms with a specific meaning in Kionga

Supporting pages:

Keep it current

Update the affected section in the same pull request as the code change. A new building block changes section 5; a new external system changes section 3; a reversed decision adds a record under decisions and a row in section 9. The documentation standard describes the checks that run on these pages.