Architecture

Purple8 Builder is a distributed, event-driven platform. This page explains how it's structured and how a build flows through it.

Service topology

Browser
  │
  ▼
nginx (80/443)
  ├──► frontend:8080         Vue 3 SPA (Vite build)
  └──► api-gateway:8000      FastAPI — all /api/* routes, SSE pipeline stream
            │
            ├──► purple8-graph:8100    knowledge graph + vector storage (v0.25)
            │                         TenantManager API (replaces Neo4j + Qdrant)
            │
            ├──► postgres:5432         primary persistence
            ├──► redis:6379            session cache + memory tier 1
            ├──► rabbitmq:5672         async task queue
            └──► minio:9000            artifact / ZIP storage

sandbox-py312 ×4             isolated code execution (Python)
sandbox-node20 ×4            isolated code execution (Node)

April 2026: agents-service and workflow-service were consolidated into the API Gateway. All agent execution and pipeline orchestration now runs inside services/gateway/.

4-Layer agent runtime

Every agent in Builder operates within a 4-layer model:

Layer	Responsibility	Example
Purpose	What are we building? Goals, constraints, scope	IdeationAgent, ArchitectureAgent
Memory	What do we already know? Prior patterns, decisions	Memory store lookup before each agent run
Execution	Do the work	All 58+ specialist agents
Supervisor	Is the output good enough?	CTQ gates, SecurityQAAgent, re-runs

Each agent also runs through a PDCA loop (Plan → Do → Check → Act) internally — it plans its output, generates it, checks it against its own criteria, and refines before passing to the next agent.

Knowledge-graph routing (Purple8 Graph v0.25)

The Purple8 Graph at :8100 is the brain of the pipeline. Agent selection uses the native TenantManager API — no Cypher or Neo4j required. Before any agent runs, the gateway queries the graph for the ordered agent sequence:

from purple8_graph.client import Purple8AsyncClient

client = Purple8AsyncClient(base_url=PURPLE8_GRAPH_URL, api_key=PURPLE8_GRAPH_API_KEY)

# Query agent capability graph via hybrid search
agents = await client.search.hybrid(
    query=user_prompt,
    node_types=["AgentType"],
    filters={"domain": detected_domain, "phase": "planning"},
    limit=20,
)
# Returns: ordered list of agents with DEPENDS_ON + FOLLOWS_IN_SEQUENCE edges resolved

This returns the exact ordered list of agents for this build — dynamically composed, not hardcoded.

Pipeline session lifecycle

POST /api/pipeline/v2/stream
        │
        ▼
    Session created → SSE stream opened
        │
        ▼
    pre_run_recall(prompt)
      └── vector-search past Solution nodes in Purple8 Graph
          inject top-k similar build contexts into pipeline
        │
        ▼
    Phase: planning
      IdeationAgent → ArchitectureAgent
        │
    [HITL checkpoint if enabled — Monaco Copilot available in review panel]
        │
        ▼
    Phase: design
      DatabaseAgent → APIDevelopmentAgent
        │
        ▼
    Phase: implementation
      BackendDevelopmentAgent → FrontendDevelopmentAgent
      InfrastructureDevelopmentAgent
        │
        ▼
    Phase: testing
      UnittestAgent → IntegrationTestAgent → SecurityQAAgent
        │
        ▼
    Phase: release
      DeploymentAgent → DocumentationAgent
        │
        ▼
    CTQ scorecard computed → build_complete event
        │
        ▼
    post_run_save(session_id, prompt, agent_outputs)
      └── persist completed build as new Solution node in Purple8 Graph

SSE event format

Every phase emits structured events on the stream:

event: phase_start
data: {"phase": "implementation", "agents": ["BackendDevelopmentAgent"]}

event: agent_output
data: {"agent": "BackendDevelopmentAgent", "content": "...", "tokens": 1840}

event: checkpoint
data: {"checkpoint_id": "chk_x1y2z3", "phase": "planning", "type": "hitl"}

event: build_complete
data: {"project": "task-api", "files": 31, "lines": 2847, "ctq_score": 86}

LLM layer

Builder's LLM layer is in shared/llm/ — a custom implementation with no LangChain or LangGraph dependency:

• Purple8LLM — unified client for OpenAI, Anthropic, Google, Ollama
• PromptTemplate — structured prompt construction with jinja2 variable injection
• @tool decorator — function-calling interface for agents
• MoE routing — complexity classifier sends tasks to cheap/local models when possible

LangChain and LangGraph were removed in March 2026. The Journey Engine + Purple8 Graph replace all LangGraph workflow orchestration.

Memory architecture

Three-tier memory backed by Purple8 Graph v0.25 (Qdrant removed):

Tier	Store	Scope	TTL
Session	Redis	Current build only	Session end
Long-term	PostgreSQL	Across all builds	Permanent
Semantic / Vector	Purple8 Graph (GraphVectorBackend)	Cross-session similarity	Permanent

Agents query memory before generating output — if a pattern was successful before (e.g. "this project uses snake_case columns"), it's injected into the agent's context automatically.

The Solution Library (via BuildRecallService) adds a fourth dimension: whole-build recall. Before any pipeline run, the top-k most similar past builds are retrieved and injected as context — making every build informed by everything that worked before.