← Documentation Home

System Architecture Overview

Complete architectural overview of the LLM Platform ecosystem

High-Level Architecture

The LLM Platform is an enterprise-grade AI orchestration system built on a distributed microservices architecture, providing unified management for multiple AI providers, vector databases, and workflow automation.

graph TB
    subgraph "Frontend Layer"
        UI[Drupal 11 UI]
        CLI[BuildKit CLI]
        IDE[AgentStudio IDE]
    end

    subgraph "API Gateway Layer"
        Gateway[LLM Gateway<br/>Multi-Provider Routing]
        MCP[MCP Registry<br/>Model Context Protocol]
        API[API Normalizer<br/>Standardization Layer]
    end

    subgraph "Orchestration Layer"
        BuildKit[Agent BuildKit<br/>BAR Runtime]
        Mesh[Agent Mesh<br/>Coordination Layer]
        Orchestra[AI Agent Orchestra<br/>Workflow Engine]
    end

    subgraph "Agent Layer"
        Workers[Worker Agents<br/>TDD, API Builder, Doc Sync]
        Governors[Governor Agents<br/>Version Sync, Branch Policy]
        Critics[Critic Agents<br/>Security, Performance, Quality]
        Observers[Observer Agents<br/>Metrics, Roadmap, Health]
    end

    subgraph "AI/ML Layer"
        Anthropic[Anthropic Claude]
        OpenAI[OpenAI GPT]
        Ollama[Ollama Local Models]
        HuggingFace[HuggingFace Models]
    end

    subgraph "Data Layer"
        Postgres[(PostgreSQL<br/>Relational Data)]
        Redis[(Redis<br/>Cache & Sessions)]
        Qdrant[(Qdrant<br/>Vector DB)]
        MongoDB[(MongoDB<br/>Document Store)]
        Neo4j[(Neo4j<br/>Knowledge Graph)]
    end

    subgraph "Observability Layer"
        Tracer[Agent Tracer<br/>AI Ops Intelligence]
        Phoenix[Phoenix Arize<br/>LLM Tracing]
        Prometheus[Prometheus<br/>Metrics]
        Grafana[Grafana<br/>Dashboards]
        Jaeger[Jaeger<br/>Distributed Tracing]
    end

    UI --> Gateway
    CLI --> BuildKit
    IDE --> Mesh

    Gateway --> Orchestra
    MCP --> Mesh
    API --> Gateway

    Orchestra --> Mesh
    BuildKit --> Workers
    BuildKit --> Governors
    BuildKit --> Critics
    BuildKit --> Observers

    Mesh --> Workers
    Mesh --> Governors
    Mesh --> Critics
    Mesh --> Observers

    Workers --> Anthropic
    Workers --> OpenAI
    Workers --> Ollama
    Workers --> HuggingFace

    Orchestra --> Postgres
    Orchestra --> Redis
    Orchestra --> Qdrant
    Orchestra --> MongoDB
    Orchestra --> Neo4j

    Mesh --> Tracer
    Workers --> Phoenix
    Tracer --> Prometheus
    Prometheus --> Grafana
    Tracer --> Jaeger

Core Architectural Principles

1. Separation of Concerns

2. Distributed by Design

3. OSSA Compliance

4. Observability First

Component Overview

Frontend Layer

Drupal 11 Platform

BuildKit CLI

AgentStudio IDE

API Gateway Layer

LLM Gateway

MCP Registry

API Normalizer

Orchestration Layer

Agent BuildKit (BAR Runtime)

Agent Mesh

AI Agent Orchestra

Agent Layer

Worker Agents

Execution-focused agents that perform specific tasks: - TDD Enforcer: Ensures test-driven development practices - API Builder: Generates API implementations from OpenAPI specs - Doc Synchronizer: Syncs documentation to GitLab Wiki - Code Executor: Secure sandboxed code execution - Test Generator: AI-powered test case generation

Governor Agents

Policy enforcement and compliance agents: - Version Sync: Maintains version consistency - Branch Policy: Enforces git branching strategies - OSSA Compliance Monitor: Validates OSSA adherence - Security Policy: Enforces security standards

Critic Agents

Analysis and review agents: - Security Auditor: Vulnerability scanning and analysis - Performance Monitor: Performance regression detection - Code Reviewer: Automated code quality review - Quality Gate Enforcer: Ensures quality thresholds

Observer Agents

Monitoring and analytics agents: - Roadmap Tracker: Monitors project progress - Metrics Collector: Aggregates performance metrics - System Monitor: Infrastructure health monitoring - Network Health Checker: Agent mesh connectivity

AI/ML Layer

Anthropic Claude

OpenAI

Ollama (Local Models)

HuggingFace

Data Layer

PostgreSQL

Redis

Qdrant

MongoDB

Neo4j

Observability Layer

Agent Tracer

Phoenix Arize

Prometheus

Grafana

Jaeger

Network Architecture

Service Communication Patterns

graph LR
    subgraph "External Access"
        User[End Users]
        Dev[Developers]
    end

    subgraph "Ingress Layer"
        Nginx[Nginx Ingress]
        LB[Load Balancer]
    end

    subgraph "Service Mesh"
        Gateway[API Gateway]
        Mesh[Agent Mesh gRPC]
        Services[Microservices]
    end

    subgraph "Backend Services"
        Data[Data Services]
        AI[AI Services]
        Obs[Observability]
    end

    User --> Nginx
    Dev --> LB
    Nginx --> Gateway
    LB --> Mesh
    Gateway --> Services
    Mesh --> Services
    Services --> Data
    Services --> AI
    Services --> Obs

Port Allocation

Service HTTP Port gRPC Port Purpose
Drupal Platform 443 (HTTPS) - Web UI
LLM Gateway 4000 - AI routing
Agent Mesh 3005 50051 Agent coordination
Agent Tracer 3007 - Observability
ACE 3008 - Capability scoring
ATLAS 3009 - Analytics
PostgreSQL 5432 - Database
Redis 6379 - Cache
Qdrant 6333 6334 Vector DB
Phoenix Arize 6006 4317 (OTLP) LLM tracing
Prometheus 9090 - Metrics
Grafana 3000 - Dashboards
Jaeger 16686 - Tracing UI
MongoDB 27017 - Document store
Neo4j 7474 7687 Graph DB

Deployment Topologies

Development (DDEV)

Staging (Kubernetes)

Production (Kubernetes)

Security Architecture

Authentication & Authorization

Network Security

Data Security

Scalability & Performance

Horizontal Scaling

Vertical Scaling

Performance Optimization

Next Steps

  1. For Developers: Start with DDEV Development
  2. For Operations: Review Kubernetes Setup
  3. For Architects: Dive into BuildKit Architecture
  4. For Monitoring: Explore Agent Tracer