Skip to content

Kubernetes AI Operator & Workflow Architecture

Welcome to the technical documentation portal for the Tuluat Kubernetes AI Operator & Workflow Engine.

🏛️ System Overview

The operator extends Kubernetes with declarative AI resources (LlmProvider, AiAgent, AiWorkflow, WorkflowSession, McpServer). It orchestrates multi-agent workflows using an embedded Graph State Machine Engine and persists session states, conversation history, and vector embeddings in PostgreSQL (with pgvector).

Tuluat High-Level Architecture Diagram 

graph TD
    subgraph Kubernetes Control Plane
        CRD1[LlmProvider CRD]
        CRD2[AiAgent CRD]
        CRD3[AiWorkflow CRD]
        CRD4[WorkflowSession CRD]
        CRD5[McpServer CRD]
    end

    subgraph AI Operator Service Pod
        Rec[JOSDK Reconcilers]
        API[REST & WebSocket API]
        ExecSvc[WorkflowExecutionService]
        Engine[GraphStateMachineEngine]
        AgentExec[AgentExecutionService]
        Guardrails[Safety Guardrails Engine]
        RagSvc[RAG & Object Storage]
    end

    subgraph Persistence Layer
        Postgres[(PostgreSQL DB + pgvector)]
        MinIO[(MinIO S3 Storage)]
    end

    CRD1 --> Rec
    CRD2 --> Rec
    CRD3 --> Rec
    CRD4 --> Rec
    CRD5 --> Rec

    API --> ExecSvc
    Rec --> ExecSvc
    ExecSvc --> Engine
    Engine --> AgentExec
    AgentExec --> Guardrails
    AgentExec --> RagSvc

    Engine --> Postgres
    RagSvc --> Postgres
    RagSvc --> MinIO

📚 Documentation Navigation Map

Explore the documentation across core categories:

  1. Features & Capabilities
  2. LLM Providers: Provider management, routing, fallbacks, token cost tracking.
  3. Agents & Tools: Autonomous AI agents, prompt templates, dynamic tool registry.
  4. Workflows & Sessions: Declarative DAG workflows, state machines, execution sessions.
  5. Safety Guardrails: PII masking, prompt injection defense, JSON schema validation.
  6. MCP & A2A Protocols: Model Context Protocol tools and Agent-to-Agent communication.

  7. RAG & Memory: Short/long memory, pgvector similarity search, MinIO S3 storage.

  8. Architecture

  9. Overview: High-level system context, DAG execution, pod crash recovery.
  10. Low-Level Design: Java class models, JPA entities, database schema DDL.
  11. Safety & Guardrails: PII masking, prompt injection defense, output validation, MCP client registry, A2A protocol.
  12. HITL Approval System: Human-in-the-Loop workflow signals and approval inbox.

  13. RAG Subsystem: Document chunking, pgvector search, MinIO S3 object storage.

  14. Custom Resources (CRDs)

  15. Specifications and complete sample YAML manifests for LlmProvider, AiAgent, AiWorkflow, WorkflowSession, and McpServer.

  16. Modules

  17. Overview: 7-module Maven Reactor architecture, step-by-step layer breakdown, responsibilities.

  18. Dependencies: Inventory of global BOMs and module-by-module Maven dependencies.

  19. Tests

  20. Unit testing, ArchUnit architecture rules, Spotless/Checkstyle checks, and KinD E2E acceptance test suite.

  21. Dev Environment

  22. Local setup, KinD cluster creation, Helm deployment, port-forwarding guide, REST API curl examples, Web GUI Control Portal.

  23. ADRs (Architecture Decision Records)

  24. Design decisions ADR 001 through ADR 011.