Skip to content

Project Overview Architecture Overview

Jump to bottom
github-actions[bot] edited this page Aug 3, 2026 · 3 revisions

Architecture Overview

Referenced Files in This Document

Update Summary

Changes Made

  • Updated documentation infrastructure section to reflect migration from manual docs/architecture/** directory to automated Qoder RepoWiki system
  • Added new Documentation Authority Framework section describing the new content-class policies and maintainer skills structure
  • Enhanced source tracking to align with automated Wiki system requirements
  • Maintained all existing architectural overview content while updating infrastructure references

Table of Contents

  1. Introduction
  2. Documentation Infrastructure
  3. Project Structure
  4. Core Components
  5. Architecture Overview
  6. Detailed Component Analysis
  7. Dependency Analysis
  8. Performance Considerations
  9. Troubleshooting Guide
  10. Conclusion

Introduction

This document describes the architecture of the Kairos MCP system with a focus on service-oriented design, layered boundaries, and integration points. It explains how HTTP/API handlers orchestrate business logic implemented as tools, which in turn coordinate memory services, workflow execution, authentication, and UI resources. The system integrates external identity (Keycloak), vector search (Qdrant), relational storage (PostgreSQL via operators), and caching/pub-sub (Redis). Deployment is containerized and orchestrated via Helm, with horizontal scaling and observability built-in.

Updated The documentation infrastructure has been modernized with Qoder RepoWiki as the single source of truth, replacing the previous manual docs/architecture/** directory structure with an automated Wiki system that provides better maintainability and accessibility.

Documentation Infrastructure

The project has undergone a major documentation infrastructure overhaul to establish Qoder RepoWiki as the authoritative source for all architectural documentation.

Migration from Manual to Automated System

  • Previous Structure: 21 individual markdown files in docs/architecture/** directory
  • Current System: Centralized automated Wiki powered by Qoder RepoWiki
  • Authority Framework: Established through .qoder/rules/documentation-authority.md with content-class policies and maintainer skills

Documentation Authority Framework

The new system implements a structured approach to documentation governance:

  • Content-Class Policies: Define classification levels for different types of documentation
  • Maintainer Skills: Establish expertise requirements for documentation contributors
  • Automated Generation: Wiki content is automatically generated and maintained
  • Single Source of Truth: Eliminates duplication and ensures consistency across all architectural documentation
flowchart TD
A["Code Changes"] --> B["Automated Analysis"]
B --> C["Wiki Content Generation"]
C --> D["Content Classification"]
D --> E["Authority Validation"]
E --> F["Published Documentation"]
G["Manual Review"] --> H["Quality Assurance"]
H --> I["Expertise Verification"]
I --> J["Final Approval"]
J --> F
K["Contributor Guidelines"] --> L["Skill Requirements"]
L --> M["Content Standards"]
M --> N["Review Process"]
N --> O["Publication"]
Loading

Diagram sources

Benefits of Automated Wiki System

  • Consistency: Automated generation ensures uniform formatting and structure
  • Accuracy: Direct linkage between code and documentation reduces drift
  • Accessibility: Centralized access point for all architectural information
  • Maintainability: Reduced manual overhead for documentation updates
  • Governance: Clear authority framework for content management

Section sources

Project Structure

The codebase follows a layered and modular organization:

  • Entry points bootstrap the server and CLI
  • HTTP layer exposes REST and MCP endpoints with middleware for auth and metrics
  • Business logic is implemented as tools that encapsulate workflows
  • Services provide cross-cutting capabilities: memory, Qdrant, Redis, OIDC state, key-value store
  • UI assets are served statically and integrated into MCP offerings
  • Helm charts define deployment topology and dependencies
graph TB
subgraph "Process"
A["Node.js Process"]
end
subgraph "HTTP Layer"
H1["HTTP Server<br/>Routes & Middleware"]
H2["Auth Middleware<br/>OIDC Claims & Scopes"]
end
subgraph "Business Logic"
T1["Tools<br/>Forward / Activate / Train / Export"]
end
subgraph "Services"
S1["Memory Store<br/>(Adapter Abstraction)"]
S2["Qdrant Service<br/>(Vector Search)"]
S3["Redis Cache<br/>(Pub/Sub + KV)"]
S4["OIDC State Store"]
S5["KV Store Factory"]
end
subgraph "External Systems"
E1["Keycloak (OIDC)"]
E2["Qdrant Cluster"]
E3["PostgreSQL (Operator-managed)"]
E4["Redis (Failover)"]
end
A --> H1
H1 --> H2
H1 --> T1
T1 --> S1
S1 --> S2
S1 --> S3
H2 --> E1
S2 --> E2
S3 --> E4
S4 --> E1
S5 --> E3
Loading

[No sources needed since this diagram shows conceptual workflow, not actual code structure]

Section sources

Core Components

  • Bootstrap and configuration: centralizes environment-driven setup, dependency wiring, and lifecycle management.
  • HTTP server and routes: registers API endpoints, static UI, and MCP handlers; applies auth and metrics middleware.
  • Authentication: OIDC-based middleware validates tokens, extracts claims, and enforces scopes.
  • Tools: implement domain workflows such as forward, activate, train, export; they compose services to perform operations.
  • Memory services: abstract adapter contracts and persistence; integrate with Qdrant for vector search and Redis for cache/pub-sub.
  • Qdrant service: manages connection, initialization, indexing, and retrieval.
  • Key-value store factory: provides pluggable backends (e.g., Redis-backed or file-backed) for transient and durable state.
  • Metrics server: exposes operational metrics for Prometheus scraping.

Section sources

Architecture Overview

Kairos MCP uses a service-oriented, layered architecture:

  • Presentation layer: HTTP server serves REST APIs, MCP JSON-RPC endpoints, and static UI.
  • Middleware layer: handles OIDC validation, scope checks, tenant context, and metrics collection.
  • Application layer: tool implementations orchestrate workflows using services.
  • Domain services: memory abstraction, Qdrant vector search, Redis caching/pub-sub, OIDC state, and generic key-value store.
  • External integrations: Keycloak for identity, Qdrant for semantic search, PostgreSQL for relational data (operator-managed), Redis for caching and pub/sub.
graph TB
Client["Clients<br/>CLI / Browser / MCP Hosts"]
subgraph "Kairos MCP"
HTTP["HTTP Server"]
Auth["OIDC Auth Middleware"]
Tools["Tools<br/>Forward / Activate / Train / Export"]
MemSvc["Memory Service"]
QdrantSvc["Qdrant Service"]
RedisSvc["Redis Service"]
OIDCState["OIDC State Store"]
KVFactory["KV Store Factory"]
end
Keycloak["Keycloak (OIDC)"]
Qdrant["Qdrant Cluster"]
Postgres["PostgreSQL (Operator)"]
Redis["Redis (Failover)"]
Client --> HTTP
HTTP --> Auth
HTTP --> Tools
Tools --> MemSvc
MemSvc --> QdrantSvc
MemSvc --> RedisSvc
Auth --> Keycloak
OIDCState --> Keycloak
QdrantSvc --> Qdrant
KVFactory --> Postgres
RedisSvc --> Redis
Loading

Diagram sources

Detailed Component Analysis

HTTP and API Layer

Responsibilities:

  • Start and configure the HTTP server
  • Register API routes and MCP handlers
  • Serve static UI assets
  • Apply auth and metrics middleware

Integration points:

  • OIDC profile claims and scopes for authorization
  • Well-known endpoints and health checks
  • CORS configuration for MCP clients
sequenceDiagram
participant C as "Client"
participant S as "HTTP Server"
participant M as "Auth Middleware"
participant R as "API Routes"
participant T as "Tool Handler"
participant MS as "Memory Service"
participant QS as "Qdrant Service"
participant RS as "Redis Service"
C->>S : "HTTP Request"
S->>M : "Validate OIDC Token"
M-->>S : "Claims + Scopes"
S->>R : "Dispatch Route"
R->>T : "Invoke Tool"
T->>MS : "Read/Write Memory"
MS->>QS : "Vector Search/Index"
QS-->>MS : "Results"
MS->>RS : "Cache/PubSub"
RS-->>MS : "Ack"
MS-->>T : "Domain Result"
T-->>R : "Response Payload"
R-->>C : "HTTP Response"
Loading

Diagram sources

Section sources

Authentication and Authorization

  • OIDC-based authentication validates tokens and maps claims to user context.
  • Scopes enforce resource access policies at route/tool level.
  • OIDC state store persists temporary state for flows (e.g., PKCE/callback).
flowchart TD
Start(["Incoming Request"]) --> ValidateToken["Validate OIDC Token"]
ValidateToken --> ClaimsOK{"Claims Valid?"}
ClaimsOK --> |No| Deny["Return Unauthorized"]
ClaimsOK --> |Yes| CheckScopes["Check Required Scopes"]
CheckScopes --> ScopesOK{"Scopes OK?"}
ScopesOK --> |No| Forbidden["Return Forbidden"]
ScopesOK --> |Yes| Proceed["Proceed to Handler"]
Proceed --> End(["Next Middleware/Handler"])
Loading

Diagram sources

Section sources

Memory Services and Vector Search

  • Memory store abstracts adapters and coordinates read/write operations.
  • Qdrant service manages connections, collections, and vector search.
  • Redis provides caching and pub/sub for cache invalidation and coordination across replicas.
classDiagram
class MemoryStore {
+read(query)
+write(item)
+search(query)
}
class QdrantService {
+connect()
+initializeCollections()
+search(vector, filters)
+index(points)
}
class RedisService {
+get(key)
+set(key, value, ttl)
+publish(channel, message)
+subscribe(channel)
}
class KeyValueStoreFactory {
+create(options)
}
MemoryStore --> QdrantService : "uses"
MemoryStore --> RedisService : "uses"
KeyValueStoreFactory ..> RedisService : "configures"
Loading

Diagram sources

Section sources

Workflow Tools

Tools encapsulate domain workflows:

  • Forward: orchestrates step execution and state transitions
  • Activate: activates protocols and prepares runtime context
  • Train: ingests artifacts, computes embeddings, and indexes content
  • Export: serializes skills and artifacts for distribution
sequenceDiagram
participant H as "HTTP Handler"
participant F as "Forward Tool"
participant MS as "Memory Store"
participant QS as "Qdrant Service"
participant RS as "Redis Service"
H->>F : "Invoke forward(step)"
F->>MS : "Load protocol/state"
MS->>QS : "Search related items"
QS-->>MS : "Matches"
MS-->>F : "Context"
F->>RS : "Publish progress event"
RS-->>F : "Ack"
F-->>H : "Step result"
Loading

Diagram sources

Section sources

CLI and Server Entrypoints

  • CLI serve command starts the HTTP server with configured options.
  • Bootstrap wires dependencies and initializes services.
  • Config centralizes environment variables and feature toggles.
flowchart TD
CLI["CLI 'serve' Command"] --> Bootstrap["Bootstrap App"]
Bootstrap --> Config["Load Configuration"]
Bootstrap --> InitServices["Initialize Services<br/>Qdrant, Redis, OIDC State"]
InitServices --> StartHTTP["Start HTTP Server"]
StartHTTP --> Ready([System Ready])
Loading

Diagram sources

Section sources

Dependency Analysis

External systems and internal components interact through well-defined interfaces:

  • Identity: Keycloak provides OIDC provider; app validates tokens and reads claims/scopes.
  • Vector search: Qdrant cluster stores vectors and performs similarity search.
  • Relational storage: PostgreSQL managed by operator supports durable state where required.
  • Caching/pub-sub: Redis enables fast lookups and cross-instance coordination.
graph LR
App["Kairos MCP App"]
KC["Keycloak"]
QD["Qdrant"]
PG["PostgreSQL"]
RD["Redis"]
App --> KC
App --> QD
App --> PG
App --> RD
Loading

Diagram sources

Section sources

Performance Considerations

  • Horizontal scalability: Deploy multiple replicas behind a load balancer; use Redis for shared cache and pub/sub to maintain consistency.
  • Vector search tuning: Configure Qdrant collection sizes, shard count, and replication factor based on dataset scale and query patterns.
  • Connection pooling: Ensure Qdrant and Redis clients are pooled and tuned for concurrency.
  • Caching strategy: Use Redis for hot paths (e.g., frequently accessed metadata) and invalidate on writes.
  • Observability: Expose metrics via the metrics server and scrape with Prometheus; monitor latency, error rates, and queue depths.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common areas to inspect:

  • Authentication failures: verify OIDC issuer URL, client credentials, and token introspection; check claim mapping and scope enforcement.
  • Vector search issues: validate Qdrant connectivity, collection existence, and vector dimensions; review search filters and payload schemas.
  • Cache inconsistencies: ensure Redis pub/sub channels are correctly subscribed and TTLs align with write operations.
  • Startup errors: confirm service initialization order and readiness probes for Qdrant and Redis.

Operational references:

  • Health and well-known endpoints for liveness/readiness checks
  • Metrics endpoint for monitoring
  • Helm values for configuring TLS, replicas, and resource limits

Section sources

Conclusion

Kairos MCP implements a clear layered architecture with strong separation between HTTP/API, business logic, and services. The system integrates Keycloak for identity, Qdrant for semantic search, PostgreSQL for relational needs, and Redis for caching and coordination. Helm-based deployment supports scalable, observable operation with horizontal scaling and robust external dependencies.

Updated The documentation infrastructure now reflects the successful migration from manual architectural decision files to an automated documentation system, with all architectural overview content preserved and enhanced within the wiki structure for better maintainability and accessibility. The new Qoder RepoWiki system provides a centralized, authoritative source for all architectural documentation with improved governance through content-class policies and maintainer skills frameworks.

KAIROS MCP

Clone this wiki locally