Architecture

How the isA platform components work together.

Verified against isA_Cloud/deployments on 2026-09-01. Ports are the container ports declared in the Helm values files. Where GCP and SN differ, the difference is a values overlay, never a code fork — see Editions.

For the enterprise consumption and governance layer above these providers, see the AEP control plane guide. AEP coordinates projects, capability requests, policy, approvals, evidence, and release intent; the provider remains authoritative for runtime execution and source-system truth.

Platform Overview

Layers are ordered by the path a request takes.


┌──────────────────────────────────────────────────────────────────────────────┐
│  CLIENTS                                                                     │
├──────────────────────────────────────────────────────────────────────────────┤
│  browser · App SDK (TypeScript) · CLI + portable CICD · MCP clients          │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  HTTPS
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  EDGE                                                                        │
├──────────────────────────────────────────────────────────────────────────────┤
│  isa-gateway-nginx           GCP — path routing, prefix preserved            │
│  Apache APISIX        :9080  SN  — routes synced from Consul :8500           │
│  cert-manager + internal CA · per-service TLS sidecar     :8443              │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  verify token · policy decision · approval state
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  IDENTITY & GOVERNANCE                                                       │
├──────────────────────────────────────────────────────────────────────────────┤
│  Authentik            :9000  ns isa-iam  — SSO federation (isa_iam)          │
│  isa-aep-api          :8080  ns isa-aep  — catalog, policy, approvals        │
│  isa-aep-portal       :3000  ns isa-aep  — enterprise operating surface      │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  authorized session
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  EXPERIENCE                                                                  │
├──────────────────────────────────────────────────────────────────────────────┤
│  isa-web / isa-app    :4100  end-user agentic app (isa-app on SN)            │
│  isa-console          :4200  build & operate control plane                   │
│  isa-admin            :4300  isa-docs             :4300                      │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  /api/v1/agent/*  ·  /api/v1/mate/*
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  AGENT & EXECUTION                                                           │
├──────────────────────────────────────────────────────────────────────────────┤
│  isa-agent            :8080  management plane — config, templates            │
│  isa-mate            :18789  execution plane — chat, stream, swarm, A2A      │
│  isa-agent-runtime    :8091  managed runtime, trusted envelope only          │
│  pool-manager         :8090  worker lease broker                             │
│  python-repl :8085 · code-repl :8087 · cloud-os :8086 · isa-os :8083         │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  workflow run · activity dispatch · connector execution
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  ORCHESTRATION                                                               │
├──────────────────────────────────────────────────────────────────────────────┤
│  maestro              :6792  workflow runtime (3 replicas on SN)             │
│  maestro-purger       :6793  retention sweeper (GCP)                         │
│  isa-int-hub          :8080  integration data plane for Maestro              │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  tool call · inference · query
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  CAPABILITY, MODEL & DATA                                                    │
├──────────────────────────────────────────────────────────────────────────────┤
│  isa-mcp              :8081  tools, skills, resources (MCP server)           │
│  isa-model            :8082  LLM gateway — provider routing, vLLM            │
│  isa-data             :8084  profile-driven warehouse client                 │
│  searxng                     private search backend                          │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  domain capability
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  DOMAIN SERVICES                                           GCP unless noted  │
├──────────────────────────────────────────────────────────────────────────────┤
│  isa-trade   :18790  isa-creative      :18791  isa-marketing :18792          │
│  isa-datawise:18793  isa-customer-service :18793  (also on SN)               │
│  isa-knowledge-hub :18795  isa-dreamforge :18796                             │
│  isa-omni-content  :18797  isa-vibe       :8080  (also SN)                   │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  identity · billing · storage · tasks
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  USER SERVICES                                              ports 8201-8292  │
├──────────────────────────────────────────────────────────────────────────────┤
│  44 services from ONE image (isa-user-shared); SERVICE_NAME selects          │
│  which service the process becomes. GCP routes 44; SN enables 16.            │
└──────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       │  pooled writes · events · objects · vectors
                                       ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│  PERSISTENCE                                                                 │
├──────────────────────────────────────────────────────────────────────────────┤
│  PgBouncer  :6432 → PostgreSQL 16  :5432                                     │
│  Redis 7          :6379            FalkorDB 4.8.7  :6379  (graph)            │
│  Qdrant           :6333/:6334      MinIO           :9000/:9001               │
│  NATS 2.14.3      :4222  JetStream, 3 replicas                               │
│  warehouse: BigQuery (GCP) · Iceberg + StarRocks (SN)                        │
│  Feast · MLflow · Cube.js · KubeRay                                          │
└──────────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────────────┐
│  CROSS-CUTTING                                 applies to every layer above  │
├──────────────────────────────────────────────────────────────────────────────┤
│  Observability  ns observability — Prometheus + Alertmanager + Grafana,      │
│                 Loki + promtail, Tempo (OTLP :4317/:4318)                    │
│  Delivery       Argo CD ApplicationSets + portable target-native CICD;       │
│                 Harbor (SN) · Artifact Registry (GCP)                        │
│  Secrets        External Secrets Operator → Vault (SN) / Secret Manager      │
└──────────────────────────────────────────────────────────────────────────────┘

Component Details

Agent SDK

The Python SDK is the primary interface for building agents. It ships as a package — it runs inside isa-mate and the agent-runtime workers, and has no deployment of its own:

Component	Purpose
Agent Runtime	Executes agent logic, manages state
Workflow Engine	Swarm handoffs and DAG orchestration
Memory Manager	Handles short and long-term memory
Tools Registry	Discovers and invokes tools
Voice Service	Full-duplex voice with audio buffering and STT rewriting
A2A Protocol	Agent-to-agent communication via Agent Card + JSON-RPC
Delegation	Remote team task delegation with circuit breakers
Observability	Prometheus metrics for nodes, models, tools, and pools

Agent SDK Documentation →

Agent Services

Agent work is split across two planes. This split is the most common source of misdirected debugging: if chat is broken, isa-agent health tells you nothing.

Service	Port	Responsibility
isa-agent	8080	Management plane — agent config CRUD, templates, AI codegen, deployment proxying
isa-mate	18789	Execution plane — chat, query, streaming, swarm orchestration, A2A
isa-agent-runtime	8091	Managed execution — accepts only a version-pinned envelope issued by `isa-agent`
pool-manager	8090	Lease broker for runtime workers

Capacity for managed agents is a lease, not a pod. If runs queue, inspect pool-manager before scaling isa-agent-runtime.

Mate Documentation →

MCP Service

Model Context Protocol provides 190+ tools with marketplace and multi-tenant security:

Category	Tools
Search	web_search, image_search, news_search
Files	file_read, file_write, file_list
Code	code_interpreter, shell, git
Data	database_query, api_call, scrape
Browser	browser_navigate, browser_click
Marketplace	Package install, update, enable/disable
Security	JWT/API key auth, command allowlist, SSE injection prevention

MCP Documentation →

Model Service

Unified LLM gateway with intelligent routing:

Feature	Description
Multi-Provider	OpenAI, Anthropic, OpenRouter, Cerebras, Ollama, YYDS, Replicate, Anthropic Sub
Intelligent Routing	Role-based resolution, capability filtering, cost-aware ranking
Voice/Realtime	WebSocket sessions with privacy filter and turn detection
ML Prediction	Time-series forecasting with Prophet (training + inference)
Caching	L1 exact-match (Redis) + L2 semantic (Qdrant)
Failover	Automatic provider failover with circuit breakers

Model Documentation →

Workflow Orchestration

Service	Port	Responsibility
maestro	6792	Workflow runtime — runs the shared Agent SDK workflow contract across agents, teams, deterministic activities, tools, human actions, events, and subprocesses
maestro-purger	6793	Retention sweeper (GCP)
isa-int-hub	8080	Integration data plane. It does not define workflows or own business state — Maestro owns workflow releases, tenant policy, and connection config

Maestro Documentation →

Identity and Governance

Service	Port	Namespace	Responsibility
Authentik	9000	`isa-iam`	SSO federation — turns customer identity systems into a stable isA contract
isa-aep-api	8080	`isa-aep`	Capability catalog, policy, approvals, provisioning, audit evidence
isa-aep-portal	3000	`isa-aep`	Enterprise operating surface

AEP Control Plane →

User Services

44 microservices sharing a single image (isa-user-shared). The SERVICE_NAME environment variable selects which service the process becomes, so the running set is a deployment-list choice in the Argo CD ApplicationSet, not a rebuild. Ports 8201-8292.

Category	Services
Identity	auth, account, session, authorization, organization, invitation, membership
Commerce	payment, subscription, billing, wallet, credit, order, product, tax, fulfillment, inventory
Storage	storage, album, media, document, artifact
Workspace	project, project-sharing, task, calendar, sharing, trading-workspace
IoT	device, ota, telemetry
Platform	audit, notification, event, metrics, compliance, vault, connector, developer, training
Context	memory, location, campaign, weather

The GCP gateway publicly routes 43 of them; user-metrics is deployed through its own Argo application with no public route. The SN edition enables 16 — the identity core, plus audit, authorization, notification and storage, the metered-inference spine (billing/product/subscription), and the workspace surface (calendar/document/project/project-sharing/task). Removing a name cascade-deletes only its Deployment, HPA and Service; the service’s tables in the shared Postgres are untouched, so re-adding the name restores it.

User Services Documentation →

Domain Services

Deployed on GCP unless noted:

Service	Port	Purpose
isa-trade	18790	Trading domain
isa-creative	18791	Content production and brand management
isa-marketing	18792	Marketing automation and analytics
isa-datawise	18793	Analytics domain
isa-customer-service	18793	Multi-agent customer support (also deployed on SN)
isa-knowledge-hub	18795	Knowledge domain
isa-dreamforge	18796	Generative media
isa-omni-content	18797	Multi-channel content
isa-vibe	8080	AI-SDLC orchestrator (also deployed on SN)

Creative Documentation → · Marketing Documentation →

Data Service

isa-data (:8084) is the data platform. The concrete engines are not hardcoded — a DataPlaneProfile assigns each role per target, which is why the same data-product code runs on both:

Role	GCP (`isa-data-plane`)	SN (`isa-bigdata`)
Object store	GCS	MinIO
Warehouse	BigQuery	Iceberg
Catalog	BigQuery	Hive Metastore
Query engine	BigQuery	StarRocks
Stream broker	Pub/Sub	Kafka
Stream processor	Dataflow	Flink
Transform scheduler	Dataform	Dataphin

Identical on both targets: Feast (feature store), Redis (online store), Cube.js (metric store), MLflow (model registry), isa_model (serving). Feast and Cube.js configuration ports across targets; a hand-written BigQuery SQL string does not.

Data Documentation →

isA Cloud

Production infrastructure:

Component	Technology	Port
Gateway (GCP)	nginx — `isa-gateway-nginx`	80/443
Gateway (SN)	Apache APISIX	9080
Discovery (SN)	Consul	8500
Database	PostgreSQL 16 behind PgBouncer	5432 / 6432
Cache	Redis 7	6379
Graph	FalkorDB 4.8.7	6379
Vectors	Qdrant	6333 / 6334
Messaging	NATS 2.14.3 — JetStream, 3 replicas	4222
Object storage	MinIO	9000 / 9001
Analytics	BigQuery (GCP) / Iceberg + StarRocks (SN)	—

Not deployed, despite appearing in older revisions of this page: Neo4j (replaced by FalkorDB), MQTT, DuckDB as a store (it survives only as an in-process engine), and the gRPC store tier on 50051-50070 — that exists only in the staging Terraform, never in production. Services connect to stores directly.

Cloud Documentation →

Observability

Self-hosted LGTM in the observability namespace, separate from the workload namespace:

Concern	Chart	Components
Metrics and alerts	`kube-prometheus-stack` 84.5.0	Prometheus, Alertmanager, Grafana, node-exporter, kube-state-metrics
Logs	`loki-stack` 2.10.3	Loki (single binary) + promtail DaemonSet
Traces	`tempo` 1.24.4	Tempo with OTLP receivers on 4317 / 4318

Grafana is pre-wired with all three datasources and is served through the gateway at /grafana/ (root_url + serve_from_sub_path), so the Console Metrics page can embed it same-origin. The gateway blanks the internal-service headers on that route.

Developer Tooling (isA Orch)

isA_Orch is not a runtime service and has no deployment manifest. It is platform-level developer tooling:

Component	Purpose
Unified Code Index	Single index spanning all isA projects with symbol resolution
Project Registry	Configuration and relationships of all sub-projects
Platform CLI	Cross-project indexing, search, and impact analysis

Orchestration Documentation →

Data Flow

Agent Request Flow


1. Client sends request to the gateway
2. Gateway authenticates and routes to isa-mate :18789 (execution plane)
3. Mate plans the run and resolves the tools it needs
4. Tool calls go to isa-mcp :8081; inference goes to isa-model :8082
5. State and results persist to Postgres (pooled), Redis, and Qdrant
6. Response streams back on the same connection

Managed Agent Execution


1. isa-agent :8080 issues a version-pinned runtime envelope
2. isa-agent-runtime :8091 accepts it — and rejects anything else
3. Runtime acquires a worker lease from pool-manager :8090
4. Pool manager allocates an SDK worker (python-repl / code-repl)
5. Result streams back to the caller

Authentication Flow


1. User authenticates via Authentik (SSO) or user-auth :8201
2. JWT token issued
3. Token included in API requests
4. Gateway validates the token — nginx on GCP, APISIX on SN
5. Request routed to the service, which re-checks authorization
6. Response returned

Services are the authorization boundary. The gateway rejects an internal-service envelope arriving from the public edge, but a service never assumes the edge already authorized the caller.

Event Flow


1. Service publishes event to NATS JetStream
2. Interested services subscribe
3. Events processed asynchronously
4. State updated across services
5. Notifications sent if needed

On SN, where user-event is not enabled, user-audit subscribes to NATS directly. GCP routes user-event (:8230) as well.

Deployment

Local Development


# KIND cluster named isa-cloud-local
.claude/skills/cluster_operations/scripts/setup-local.sh

The older deployments/kubernetes/local/scripts/kind-*.sh path is deprecated — it assumed raw-manifest kustomize overlays that the cluster no longer uses.

Production

Environment	Cluster	Registry	Sync
GCP	GKE `isa-saas-poc` (`project-sweet-498401`, `us-central1-a`)	Artifact Registry	Argo CD, digest-pinned
SN	On-premises, air-gapped	Harbor (`core.harbor.domain/isa`)	Argo CD, tag-pinned

Two things this page previously got wrong:

git push does not deploy. Argo CD reconciles the cluster from git; a release bumps a pinned tag or digest in the edition values file, and Argo syncs that.
Images are built target-natively — GCP Cloud Build for GCP, kubernetes-buildkit for SN — through the portable CICD control plane. Never GitHub Actions, never laptop image builds.

Security

Authentication

JWT tokens for API access
OAuth2/OIDC for SSO via Authentik
API keys for service-to-service
Forwarded-principal tokens between internal services

Authorization

RBAC with fine-grained permissions
Organization-level isolation
Resource-level access control
AEP policy and approval state gate high-risk capability use

Data Protection

Encryption at rest (AES-256)
Encryption in transit (TLS 1.3); per-service TLS sidecar on :8443 with an internal CA
Secrets delivered by the External Secrets Operator from Vault (SN) or GCP Secret Manager — never committed to git

Next Steps

Getting Started - Build your first agent
Cloud Setup - Deploy infrastructure
Security Guide - Authentication details