🌐 Loom — One Command to Deploy, Upgrade, or Tear Down on Any Cloud

🏗️ Terraform — Infrastructure as Code

What it does: Declares the entire cloud infrastructure in code files. Run one command → everything exists. Run another → everything is gone.

Directory: terraform/ — 9 modules, 3+ environment configs

Key commands:

terraform plan — Preview what will change (safe, read-only)

terraform apply — Create or update all infrastructure

terraform destroy — Tear everything down cleanly

State: Local backend (terraform.tfstate on deployment machine). Previously Azure Blob — migrated to local for simplicity since deployments run from a single PC.

📋 Plan Phase

terraform plan — Shows exactly what will be created, modified, or destroyed before making any changes.

Like a construction blueprint review — you see every change before the builders start. No surprises.

Output example: "Plan: 23 to add, 2 to change, 0 to destroy"

🚀 Apply Phase

terraform apply — Creates all infrastructure: Kubernetes cluster, databases, search service, vault, messaging, networking, DNS, private endpoints.

Then helm install deploys the application workloads into the cluster.

Full stack from zero: One terraform apply + helm install = entire platform running.

⬆️ Upgrade Phase

helm upgrade cerebro-app ./helm/cerebro-app — Rolling update, zero downtime.

What can be upgraded:

→ Application code (new Docker image)

→ Configuration (env vars, secrets, replicas)

→ Infrastructure (Terraform detects drift and reconciles)

→ Plugins (hot-reload via MCP engine API)

Rollback: helm rollback cerebro-app 1 — instant revert to previous version.

💥 Teardown Phase

terraform destroy — Removes ALL infrastructure cleanly. Every resource, every service, every DNS record.

Useful for: dev/test environments, cost optimization, migration between clouds.

Safety: Requires explicit confirmation. State file records what was created, so destroy is precise — no orphaned resources.

🧱 Terraform Modules

Each module abstracts one cloud service into a cloud-agnostic interface:

🆔 Identity: Azure Managed Identity / AWS IAM Roles / GCP Workload Identity

☸️ Kubernetes: AKS / EKS / GKE — same K8s API, different provisioning

💾 Database: Cosmos DB / DynamoDB / Firestore

🔍 Search: Azure AI Search / OpenSearch / Vertex AI Search

🤖 LLM: Azure OpenAI / AWS Bedrock / Vertex AI

🔐 Vault: Azure Key Vault / AWS Secrets Manager / GCP Secret Manager

📦 Registry: ACR / ECR / Artifact Registry

📧 Messaging: Azure Communication Services / Amazon SES / SendGrid

🌐 Networking: VNet / VPC / Ingress controllers

🌍 DNS: Azure DNS / Route 53 / Cloud DNS

🔒 Private Endpoints: Azure PE + Private DNS / AWS VPC Endpoints / GCP Private Service Connect — zero public access to data services

The app code never references cloud-specific APIs — only the Terraform modules change per cloud.

⎈ Helm Charts

Helm packages Kubernetes manifests into versioned, configurable releases:

cerebro-app: The main platform — Flask app, ingress, TLS, HPA autoscaling, service account with workload identity.

mcp-engine: Each MCP engine gets its own Helm release in its own namespace. Deploy new engines by adding a release.

monitoring: Full observability stack — Prometheus, Grafana, Loki, Promtail, AlertManager, dashboards.

Values files: values-azure.yaml, values-aws.yaml, values-local.yaml — same chart, different cloud configs.

📦 cerebro namespace

Runs the main Cerebro app — the Flask web server, OIDC + Magic Link auth, agent loop, Visual Designer, all API endpoints.

Pods: cerebro-app (HPA 2-8, Gunicorn), contextweaver-frontend (React SPA, HPA 2-5), Valkey (sessions + rate limiting), code-server (standalone workspace)

TLS: cert-manager auto-provisions Let's Encrypt certificates

Secrets: Cosmos endpoint, search keys, LLM keys, SSO secret — all injected via Helm values

📦 mcp1 namespace

Each MCP engine runs in its own Kubernetes namespace for isolation. Deploy additional engines (mcp2, mcp-healthcare, mcp-finance) as separate Helm releases.

Ports: 5000 (dashboard/API), 5001 (MCP transport — SSE/HTTP)

Plugins: Mounted as volumes or uploaded via API. Each plugin is a ZIP with manifest + Python code.

Scaling: Each engine scales independently based on load.

📦 monitoring namespace

Full observability stack running alongside the application:

Prometheus: Scrapes metrics from all pods via ServiceMonitors

Grafana: Dashboards for platform, MCP, RAG, security, users, Loki logs

Loki + Promtail: Aggregates all pod logs, searchable with LogQL

Alertmanager: Fires alerts on high error rates, slow tools, pod crashes, disk/memory pressure

☁️ Azure — Current Production

Fully wired and running. cd terraform/environments/azure && terraform apply

AKS (D4as_v5 nodes), Cosmos DB, Azure AI Search, Azure OpenAI (GPT-5), Key Vault, ACR, ACS Email, Private Endpoints

Security: Managed Identity for all service-to-service auth — zero API keys stored in pods.

☁️ AWS — Planned

Same Terraform modules, AWS provider. cd terraform/environments/aws && terraform apply

EKS, DynamoDB, OpenSearch, Bedrock (Claude/Titan), Secrets Manager, ECR, SES Email, VPC Endpoints

Security: IAM Roles for Service Accounts (IRSA) — same zero-key pattern as Azure.

☁️ GCP — Planned

Same Terraform modules, GCP provider. cd terraform/environments/gcp && terraform apply

GKE, Firestore, Vertex AI Search, Vertex AI (Gemini), Secret Manager, Artifact Registry, SendGrid, Private Service Connect

Security: Workload Identity Federation — same zero-key pattern.

🏠 Local / On-Premises

For development, demos, and air-gapped deployments. docker-compose up

Docker Compose, SQLite (no Cosmos needed), Ollama (free local LLM), file-based vault

No cloud account required. Everything runs on a single machine.

📦 workspaces namespace

Per-user cloud IDE environments. Each user gets their own ws-{username} pod running code-server 4.115.0.

Resources: 4 CPU cores, 4Gi RAM, Azure Disk PVC (ext4, persistent across restarts).

Tools: GitHub Copilot CLI, Claude Code, Node.js 20, kubectl, helm, git, zsh + Oh-My-Zsh with autocomplete.

Auth: nginx auth-url annotation gates access through /api/auth/verify.

Lifecycle: Spawn/stop/delete via admin API. Each workspace is a separate Helm release.

📦 jupyterhub namespace

Multi-user Jupyter notebook server. JupyterHub manages per-user jupyter-{username} pods with persistent storage.

Auth: Entra ID (Azure AD) — same identity as the main platform.

Kernels: Python 3, R, Julia, custom kernels. Pre-loaded data science libraries.

Integration: Notebooks can call ContextWeaver APIs and interact with MCP engines programmatically.

📦 ingress-nginx namespace

NGINX Ingress Controller handles all external traffic routing with TLS termination.

TLS: cert-manager auto-provisions and renews Let's Encrypt certificates for app.brainzbytes.com.

Auth gating: auth-url annotations on workspace and JupyterHub ingresses route through /api/auth/verify — only authenticated users can access their resources.

Public IP: 4.152.21.202 via Azure Load Balancer.