Architecture Overview

Understanding the Composio Helm Charts deployment architecture

System Components

┌─────────────────────────────────────────────────────────────────┐
│                         Kubernetes Cluster                       │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                  Composio Namespace                      │   │
│  │                                                           │   │
│  │  ┌──────────────┐         ┌──────────────┐              │   │
│  │  │   Apollo     │◄────────┤  PostgreSQL  │              │   │
│  │  │   (API)      │         │  (External)  │              │   │
│  │  │  Port: 9900  │         └──────────────┘              │   │
│  │  └───────┬──────┘                                        │   │
│  │          │                                               │   │
│  │          │  ┌──────────────┐         ┌──────────────┐  │   │
│  │          ├──┤   Thermos    │◄────────┤    Redis     │  │   │
│  │          │  │ (Background) │         │ (Optional)   │  │   │
│  │          │  │  Port: 8180  │         └──────────────┘  │   │
│  │          │  └──────────────┘                            │   │
│  │          │                                               │   │
│  │          │  ┌──────────────┐                            │   │
│  │          └──┤   Mercury    │  (Knative Service)        │   │
│  │             │    (MCP)     │  Auto-scaling: 1-10       │   │
│  │             │  Port: 8080  │                            │   │
│  │             └──────────────┘                            │   │
│  │                                                           │   │
│  │  ┌──────────────┐         ┌──────────────┐              │   │
│  │  │    Minio     │         │   Temporal   │              │   │
│  │  │  (Storage)   │         │  (Workflow)  │              │   │
│  │  │  Port: 9000  │         │  Port: 7233  │              │   │
│  │  └──────────────┘         └──────────────┘              │   │
│  │                                                           │   │
│  │  ┌──────────────────────────────────────────────────┐  │   │
│  │  │      OpenTelemetry Collector (Observability)     │  │   │
│  │  │      Exports: Google Cloud Monitoring/Trace      │  │   │
│  │  └──────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Knative Serving Namespace                   │   │
│  │  ┌──────────────────────────────────────────────────┐  │   │
│  │  │  Knative Controller, Webhook, Activator, HPA     │  │   │
│  │  │  Kourier Ingress Controller                       │  │   │
│  │  └──────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Core Services

Service Type Purpose Port Replicas Resources Template Key Features
Apollo API Service Main API server for Composio platform 9900 (NodePort: 30900) 2 (default) 5Gi memory, 1 CPU composio/templates/apollo.yaml:1
  • RESTful API endpoints
  • PostgreSQL database integration
  • Auto-generated admin tokens
  • Health checks and readiness probes
  • Optional HPA for auto-scaling
Thermos Background Service Background processing and task execution 8180 (ClusterIP) 2 (default) 4Gi memory, 2 CPU composio/templates/thermos.yaml:1
  • Asynchronous task processing
  • Temporal workflow integration
  • Redis queue management
  • Database initialization jobs
  • Configurable scaling policies
Mercury Knative Service Model Context Protocol (MCP) endpoint 8080 (ClusterIP) Auto-scaling (1-10) 2Gi memory, 1 CPU composio/templates/mercury.yaml:1
  • Knative-based serverless scaling
  • Scale-to-zero capabilities
  • Request-based auto-scaling
  • Configurable concurrency limits
  • 300-second request timeout
Minio Storage Service S3-compatible object storage 9000 (ClusterIP) 1 4Gi memory, 2 CPU composio/templates/minio.yaml:1
  • S3-compatible API
  • Persistent volume storage (8Gi)
  • Tool and function storage
  • Health and readiness probes
  • Admin credentials management
Temporal Workflow Engine Distributed workflow orchestration 7233 (Frontend), 8080 (Web UI) 2 (server) Default Temporal settings Dependency (temporal-0.64.0)
  • Workflow and activity orchestration
  • PostgreSQL persistence
  • Web UI for monitoring
  • Admin tools included
  • Namespace management
OpenTelemetry Collector Observability Metrics and trace collection 4317 (gRPC), 4318 (HTTP) 1 512Mi memory, 500m CPU composio/templates/otel-collector.yaml:1
  • OTLP, Jaeger protocol support
  • Google Cloud Monitoring export
  • Google Cloud Trace export
  • Prometheus metrics endpoint
  • Batch processing and memory limits

Communication Patterns

Service-to-Service Communication

  • Apollo → PostgreSQL: Direct database connection via secret-managed credentials
  • Apollo → Redis: Optional external or internal Redis for caching
  • Apollo → Minio: Object storage for tools and Lambda functions
  • Thermos → Temporal: Workflow execution and task management
  • Mercury → Apollo: API calls for MCP functionality
  • All Services → OTEL Collector: Telemetry data export

Security Architecture

  • Secrets Management: Kubernetes Secrets with auto-generated values
  • Non-root Containers: All services run as non-root users
  • Security Contexts: Drop all capabilities, read-only root filesystem where possible
  • Network Policies: Can be configured per environment
  • RBAC: Service accounts with minimal required permissions
  • Image Pull Secrets: AWS ECR authentication for private registries

Data Flow

  • Request Flow: User → Apollo API → PostgreSQL → Response
  • Background Tasks: Apollo → Temporal → Thermos → Task Execution
  • MCP Requests: Client → Mercury (via Knative) → Apollo → Response
  • File Storage: Service → Minio → S3-compatible storage
  • Observability: All Services → OTEL Collector → Google Cloud

External Dependencies

Required

  • PostgreSQL: External database for all services
  • AWS ECR: Container registry authentication
  • Kubernetes 1.28+: Container orchestration platform
  • Knative Serving: Serverless runtime for Mercury

Optional

  • Redis: Can use external or bundled Redis (Bitnami)
  • OpenAI API: For AI-powered features
  • Google Cloud: For observability exports
  • Load Balancer: For production ingress

Scaling Strategy

Service Scaling Type Min/Max Replicas Trigger
Apollo HPA (Optional) 2 / 10 CPU: 70%, Memory: 80%
Thermos HPA (Optional) 2 / 10 CPU: 70%, Memory: 80%
Mercury Knative Auto-scaling 1 / 10 CPU: 80%, Concurrency
Minio Manual 1 N/A (StatefulSet)
Temporal Manual 2 N/A
OTEL Collector Manual 1 N/A

Deployment Modes

Development Mode

  • Uses values.yaml defaults
  • Minimal resource requests
  • Single replica for most services
  • Includes debug utilities
  • Local port-forwarding for access

Production Mode

  • Uses values-override.yaml
  • High-availability configuration
  • Multiple replicas with HPA
  • External PostgreSQL and Redis
  • Load balancer ingress
  • Enhanced monitoring and alerting