Version: 1.0.1 (Latest)

# Overview

Kamiwaza is a Kubernetes-based AI platform that combines model serving, governed data access, application deployment, and security controls behind a single customer-facing domain. This page provides a high-level view of the current architecture used in supported deployments.

## System Architecture Diagram

### Compute and Orchestration

- Kubernetes
- Ray and Serving Runtimes
- Extension Operator
- CPU and GPU Nodes
- Shared Platform Layer
- Traefik or Istio Ingress
- Identity Provider
- Postgres or SQLite in lite mode
- etcd
- DataHub and Catalog Services
- Object Storage
- Platform Services
- API and Auth Gateway
- Model and Serving Services
- DDE, Retrieval, and Catalog
- Workrooms and Collaboration
- Logger and Audit Services

## Architecture Layers

### Experience layer

This is how users and client applications interact with Kamiwaza.

- **Kamiwaza Web UI** for administration, models, workrooms, apps, tools, and logs
- **SDK and API clients** for programmatic access
- **App Garden and Tool Shed** for launching applications and tool servers behind managed routes

### Services layer

This layer contains the platform APIs and business logic.

- **API and Auth Gateway** for authenticated access, routing, and policy enforcement
- **Model and Serving Services** for model lifecycle and inference
- **DDE, Retrieval, and Catalog** for ingestion, discovery, secret references, and retrieval flows
- **Workrooms and Collaboration** for shared workspace functionality
- **Logger and Audit Services** for runtime troubleshooting and security evidence

### Shared platform layer

This layer provides the shared services the platform depends on.

- **Traefik or Istio** for ingress and routing, depending on environment
- **Identity provider integration** for authenticated deployments
- **Postgres** as the standard persistent database in auth-enabled deployments
- **SQLite** as a reduced-scope database option in lite mode
- **etcd** for cluster coordination and runtime configuration
- **DataHub and related catalog services** for metadata-backed catalog workflows
- **Object storage** for uploaded files, workroom context, and related assets

### Compute and orchestration layer

This layer runs the workloads that power the platform.

- **Kubernetes** as the primary deployment target
- **Ray and serving runtimes** for model execution and distributed work
- **Extension Operator** for managed application and tool deployment workflows
- **CPU and GPU nodes** that host inference and platform workloads

## Technology Stack

| Category                | Technologies                                      |
|------------------------|--------------------------------------------------|
| Backend                 | Python, FastAPI, Ray                             |
| Frontend                | React                                            |
| Data and metadata       | Postgres, SQLite in lite mode, etcd, DataHub    |
| Routing and ingress     | Traefik, optional Istio                          |
| Deployment              | Kubernetes, Helm                                 |

## Design Principles

- **Single customer-facing domain** with path-based runtime routing as the standard deployment model
- **Security by configuration** through identity integration, access controls, consent, and auditability
- **Composable services** so model serving, retrieval, catalog, apps, and tools can evolve independently
- **Operational visibility** through deployment logs, cluster logs, and OTEL-compatible export paths