System Architecture Overview

Parallax is a multi-agent orchestration platform that coordinates AI coding assistants to work together on complex tasks. This document provides a comprehensive overview of how all components work together.

High-Level Architecture

Core Components

Control Plane

The control plane is the brain of Parallax. It receives pattern execution requests, coordinates agents, and aggregates results.

Component	Responsibility
Pattern Engine	Loads patterns, selects agents, runs org-chart workflows and TypeScript pattern modules
Org-Chart Compiler	Parses org-chart YAML into a workflow spec (lives inside the control plane's org-patterns/)
Workflow Executor	Runs the workflow spec by spawning and routing managed CLI-agent threads
Workspace Service	Provisions git workspaces for agents
Agent Registry	Tracks available agents via etcd
Credential Service	Issues short-lived git credentials
Scheduler	Manages scheduled pattern executions
Event Bus	Real-time execution event streaming

Data Plane

The data plane handles the actual execution of tasks against agents with reliability and performance features.

Component	Responsibility
Execution Engine	Parallel/sequential task execution with retries
Agent Proxy	Communication layer with circuit breakers and rate limiting
Confidence Tracker	Tracks agent confidence scores over time
Result Cache	Caches high-confidence results

Agent Runtimes

Runtimes spawn and manage AI coding agent processes:

Runtime	Use Case
Local	Development - runs CLIs directly on host
Docker	Production - isolated containers
Kubernetes	Scale - auto-scaling pods

Request Flow

Here's how a pattern execution request flows through the system:

Pattern Pipeline

Parallax has two kinds of patterns, each with its own execution path — there is no shared DSL or compilation-to-script step:

Two execution paths

• Org-chart YAML — the org-chart compiler (inside the control plane's org-patterns/) parses the YAML into a workflow spec. The workflow executor runs that spec by spawning and routing managed CLI-agent threads, applying the per-role confidence/escalation policy.
• TypeScript pattern modules — a PatternModule from the @parallaxai/patterns manifest is loaded and its execute(ctx) runs directly. Modules are deployed with the control plane (Temporal-style), not uploaded at runtime.

Both paths are confidence-aware: results carry Confident<T> values, and routing (accept / retry / escalate) is driven by verification, not self-reported scores.

Data Model

Configuration

Environment Variables

# Control Plane
PARALLAX_ETCD_ENDPOINTS=localhost:2379
PARALLAX_PATTERNS_DIR=./patterns
PARALLAX_WORKSPACES_DIR=./.workspaces

# Agent Runtimes
PARALLAX_LOCAL_RUNTIME_URL=http://localhost:8081
PARALLAX_DOCKER_RUNTIME_URL=http://localhost:8082
PARALLAX_K8S_RUNTIME_URL=http://localhost:8083

# Workspace/Git
PARALLAX_GITHUB_APP_ID=123456
PARALLAX_GITHUB_PRIVATE_KEY=-----BEGIN RSA...

# Data Plane
PARALLAX_EXECUTION_ENGINE=true
PARALLAX_AGENT_TIMEOUT=30000
PARALLAX_AGENT_RETRIES=2

# Observability
PARALLAX_TRACING_ENABLED=true
PARALLAX_JAEGER_ENDPOINT=http://localhost:14268/api/traces

Next Steps

• Org-Chart Patterns - How hierarchical teams work
• Data Plane - Execution engine internals
• Agent Lifecycle - How agents are spawned and managed
• Workspace Service - Git workspace provisioning