Layered architecture: control, orchestration, execution, UI, cross-cutting

[balaji-balu]

A proposal for the platform's target architecture, to settle before it goes into docs/architecture.md and the features register.

Layers

• UI layer: a thin client for users, the BA and the architect. It talks only to the control plane and holds no workflow state.
• Control layer: governance (policy, permissions, identity), registries (agents, skills, projects, models) and the API.
• Orchestration layer: the reconciler, scheduling, the agent runner and lifecycle.
• Execution layer:
  • Graph engine: the workflow as a graph. Nodes are actions (intent, requirement analysis, design, …) and edges are transitions and routes (for example route: ddd).
  • Loop engine and harness: the agent loop inside one action (pi), with guards, repair loops and pinned AGENTS.md.
  • Skills, tools and MCP servers: what an agent can call.
• Cross-cutting: evidence and provenance (git, artifact headers, trace.yaml), and observability (run IDs, cost, traces).

Open questions

1. Where do memory and the knowledge graph go: cross-cutting or execution?
   • For cross-cutting: the control plane (policy scopes), execution (agents read and write) and the code-to-spec loop all use them, and they need the same provenance and integrity rules as evidence (GOV-16).
   • For execution: agents are the only direct readers and writers, through tools (kb_search, kb_get).
   • A possible split: the store is cross-cutting, and access is an execution tool, with scopes enforced by the control plane (GOV-11).
2. Graph engine vs reconciler. Today the reconciler picks the next step from git state. With a graph engine, is the graph the definition (versioned and pinned like pipeline.lock.yaml) that the reconciler walks, or does the graph engine drive execution while orchestration only schedules and runs?
3. The litellm gateway: a control-plane shared service (budgets, routing policy) or execution infrastructure?

Comments welcome. The result will be recorded in docs/decisions.md.

🤖 Drafted with Claude Code

[balaji-balu]

Update: the layers are now in the docs, merged in #22 and recorded as decision D23 (proposed):

• Architecture: the layered diagram and what each layer holds today
• Walkthrough: the platform diagram, redrawn in layers
• Roadmap: "Layers by milestone" and the decisions below, each with a due milestone
• Features register: a UI layer, and a new EXE-GRAPH component for the graph engine

Still open, marked "placement open" in the docs:

1. Knowledge and memory: cross-cutting or execution?
2. Graph engine vs reconciler: is the graph a definition the reconciler walks, or does the graph engine drive execution? Due before reconciler v0 (M3).
3. The litellm gateway: a control-plane service or execution infrastructure?

Once these are settled, one PR will move D23 to decided, and this discussion will be closed with a link to it.

🤖 Posted with Claude Code

[AAMARVA]

This is a really clean breakdown of the layers. Separating control plane governance from the execution graph lifecycle is exactly how you prevent orchestration state from getting messy at scale. 

Regarding Open Question 1: Splitting memory/KG typically scales better. Treating the storage layer, policy scopes, and provenance as a control plane/cross-cutting asset ensures strict integrity, while letting the agents interact with it purely as a runtime tool interface during execution. If you embed core memory logic entirely inside the execution layer, enforcing cross-agent data governance becomes a major bottleneck. 

One layer worth considering as this architecture matures is the network communication boundary between these independent execution nodes. Current agent-to-agent (A2A) protocols completely lack native end-to-end (E2E) encryption and identity verification. If agents across these execution graphs are passing tasks or data without network-level isolation, you risk data exposure or unauthorized state manipulation from malicious nodes. 

We are building AAMARVA to address this exact infrastructure gap. We provide a native E2E encrypted network layer directly between agents, allowing secure discovery and communication across frameworks. To completely isolate the runtime from bad actors, we restrict the network to an apply and invite-only access model. Vetting member nodes at the network entry point ensures every edge in your execution graph remains trusted. 

Really solid proposal—looking forward to seeing how the target architecture settles before hitting the docs.