Architecture

How the isA platform components work together.

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


┌─────────────────────────────────────────────────────────────────────────────────┐
│                                 APPLICATIONS                                     │
│              Web Apps • Mobile Apps • CLI Tools • Integrations                   │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                               AGENT SDK (Python)                                 │
│                                                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐│
│  │  Agent   │ │ Workflow │ │  Memory  │ │  Tools   │ │  Voice   │ │  A2A   ││
│  │  Runtime │ │ Engine   │ │ Manager  │ │ Registry │ │ Service  │ │Protocol││
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘│
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    ▼                   ▼                   ▼
┌──────────────────────┐  ┌──────────────────────┐  ┌──────────────────────┐
│     MCP SERVICE      │  │    MODEL SERVICE     │  │    USER SERVICES     │
│                      │  │                      │  │                      │
│  190+ Tools:         │  │  LLM Gateway:        │  │  35 Microservices:   │
│  • Web Search        │  │  • 8+ Providers      │  │  • Authentication    │
│  • File Operations   │  │  • Role Routing      │  │  • Payments          │
│  • Code Execution    │  │  • Voice/Realtime    │  │  • Storage           │
│  • Marketplace       │  │  • ML Prediction     │  │  • Organizations     │
│  • Browser           │  │  • Caching           │  │  • Devices (IoT)     │
│  • APIs              │  │  • Cost Ranking      │  │  • Memory            │
└──────────────────────┘  └──────────────────────┘  └──────────────────────┘
                    │                   │                   │
                    └───────────────────┼───────────────────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    ▼                                       ▼
┌──────────────────────────────────┐  ┌──────────────────────────────────┐
│        DOMAIN SERVICES           │  │       PLATFORM TOOLING           │
│                                  │  │                                  │
│  ┌──────────────┐ ┌───────────┐ │  │  ┌──────────────────────┐       │
│  │   Creative   │ │ Marketing │ │  │  │     Orchestration    │       │
│  │              │ │           │ │  │  │      (isA Orch)      │       │
│  │ • Content    │ │ • Campaign│ │  │  │                      │       │
│  │   Creator    │ │   Manager │ │  │  │ • Unified Code Index │       │
│  │ • Visual     │ │ • SEO     │ │  │  │ • Project Registry   │       │
│  │   Designer   │ │   Agent   │ │  │  │ • Impact Analysis    │       │
│  │ • Brand      │ │ • Content │ │  │  │ • Cross-Project      │       │
│  │   Strategist │ │   Agent   │ │  │  │   Search             │       │
│  │ • Copy Editor│ │ • Audience│ │  │  └──────────────────────┘       │
│  │ • DAM Manager│ │   Insights│ │  │                                  │
│  │ • Design     │ │ • Campaign│ │  │                                  │
│  │   System     │ │   Analyst │ │  │                                  │
│  └──────────────┘ └───────────┘ │  │                                  │
└──────────────────────────────────┘  └──────────────────────────────────┘
                    │                                       │
                    └───────────────────┬───────────────────┘
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              DATA SERVICE                                        │
│                                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │  Data Lake   │  │ Data Fabric  │  │     RAG      │  │    File      │        │
│  │   (DuckDB)   │  │  (Pipelines) │  │  (Vectors)   │  │  Processing  │        │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘        │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              isA CLOUD                                           │
│                                                                                  │
│  ┌────────────────────────────────────────────────────────────────────────┐    │
│  │                        APISIX GATEWAY (Port 9080)                       │    │
│  │            Rate Limiting • Auth • Routing • SSL • Metrics              │    │
│  └────────────────────────────────────────────────────────────────────────┘    │
│                                        │                                        │
│  ┌────────────────────────────────────────────────────────────────────────┐    │
│  │                    CONSUL SERVICE DISCOVERY (Port 8500)                 │    │
│  │              Registration • Health Checks • DNS • KV Store             │    │
│  └────────────────────────────────────────────────────────────────────────┘    │
│                                        │                                        │
│  ┌────────────────────────────────────────────────────────────────────────┐    │
│  │                        gRPC SERVICES (50051-50070)                      │    │
│  │   postgres • redis • neo4j • nats • mqtt • minio • qdrant • duckdb     │    │
│  └────────────────────────────────────────────────────────────────────────┘    │
│                                        │                                        │
│  ┌────────────────────────────────────────────────────────────────────────┐    │
│  │                          INFRASTRUCTURE                                 │    │
│  │  PostgreSQL • Redis • Neo4j • NATS • MQTT • MinIO • Qdrant • DuckDB   │    │
│  └────────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────────┘

Component Details

Agent SDK

The Python SDK is the primary interface for building agents:

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 →

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 →

User Services

35 microservices for common application needs:

Category	Services
Auth	auth, profile, rbac, social
Payments	payment, subscription, billing, wallet
Storage	storage, album, media, document
Social	organization, invitation, membership
IoT	device, ota, telemetry
AI	memory (cognitive memory system)

User Services Documentation →

Creative Service

AI-powered creative agents for content production and brand management:

Agent	Purpose
Content Creator	Generates written content (articles, posts, scripts)
Visual Designer	Produces visual assets and design concepts
Brand Strategist	Maintains brand voice and positioning
Copy Editor	Reviews and refines content for quality
DAM Manager	Digital asset management and organization
Design System Agent	Enforces design system consistency

Creative Documentation →

Marketing Service

AI-driven marketing automation and analytics:

Agent	Purpose
Campaign Manager	Plans and executes marketing campaigns
SEO Agent	Search engine optimization and keyword strategy
Content Agent	Marketing-specific content generation
Audience Insights	Audience segmentation and analysis
Campaign Analyst	Campaign performance analytics and reporting
Compliance Agent	Ensures marketing content meets regulations
Report Generator	Automated marketing reports and dashboards

Marketing Documentation →

Orchestration (isA Orch)

Platform-level tooling for cross-project operations:

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 Service

Data processing and analytics:

Component	Technology
Data Lake	DuckDB for analytics
Data Fabric	Apache Spark pipelines
RAG	Qdrant + pgvector
File Processing	Multi-format extraction

Data Documentation →

isA Cloud

Production infrastructure:

Component	Technology	Port
Gateway	Apache APISIX	9080
Discovery	Consul	8500
Database	PostgreSQL	5432
Cache	Redis	6379
Graph	Neo4j	7687
Messaging	NATS	4222
IoT	MQTT	1883
Storage	MinIO	9000
Vectors	Qdrant	6333
Analytics	DuckDB	-

Cloud Documentation →

Data Flow

Agent Request Flow


1. User sends request to Agent
2. Agent SDK processes request
3. Agent decides which tools to use
4. Tools call backend services via MCP
5. Model service generates responses
6. Results aggregated and returned

Authentication Flow


1. User authenticates via auth_service
2. JWT token issued
3. Token included in API requests
4. APISIX validates token
5. Request routed to service
6. Response returned

Event Flow


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

Deployment Options

Local Development


# Using KIND (Kubernetes in Docker)
cd deployments/kubernetes/local/scripts
./kind-setup.sh
./kind-deploy.sh

Staging/Production


# GitOps with ArgoCD
git push origin main  # Triggers deployment

Environment	Cluster	Auto-Deploy
Local	KIND	Manual
Staging	EKS	Yes (main branch)
Production	EKS/GKE	Manual approval

Security

Authentication

JWT tokens for API access
OAuth2/OIDC for SSO
API keys for service-to-service

Authorization

RBAC with fine-grained permissions
Organization-level isolation
Resource-level access control

Data Protection

Encryption at rest (AES-256)
Encryption in transit (TLS 1.3)
Secrets in Vault/AWS Secrets Manager

Next Steps

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