{"slug":"strategy/product-strategy/OODA-ARCHITECTURE","title":"OODA Loop Architecture Guide","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/product-strategy/OODA-ARCHITECTURE.mdx","bytes":10801,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Overview\n\nThe IntegrateWise platform operates as a continuous **OODA loop** (Observe, Orient, Decide, Act) that enables human-centered AI collaboration. This is not a new layer, but the operational rhythm that runs through all six platform layers.\n\n**Core Principle:** Agents handle uncertainty. Pipelines handle certainty.\n\n## The Four OODA Phases\n\n### 1. Observe — \"What is happening?\"\n\n**Layers involved:** Ingress Layer + Connector Sync\n\n**Pipeline responsibilities (mechanical):**\n\n- Webhook ingestion (`webhook-ingress`)\n- Delta polling (`connector-sync`)\n- Event streaming (SSE, MCP incoming)\n- Metric collection and logging\n- Spine change detection\n\n**Agent responsibilities (intelligent):**\n\n- Anomaly detection on incoming data streams\n- Pattern recognition across multiple connectors\n- Intent classification on natural language requests\n- Sentiment/urgency scoring before routing\n\n**Key insight:** Observation is mostly mechanical, but _what_ you observe and _how_ you prioritize it is intelligent.\n\n---\n\n### 2. Orient — \"What does it mean?\"\n\n**Layers involved:** Continuity Layer + Capability Layer\n\n**This phase is dominated by agents** because orientation requires:\n\n- Context assembly (memory, knowledge, workspace state, entity history)\n- Pattern matching (comparing current to historical)\n- Hypothesis generation (what does the user want?)\n- Spine synthesis (multi-connector coherence)\n\n**Key services:**\n\n- `intelligence` service (think/act paths) — core orientation engine\n- `twin-orchestrator` — per-user context model\n- `knowledge` (KB + vector search) — semantic retrieval\n- `continuity` (memory lifecycle) — temporal context assembly\n- Schema AI (Continuity Bridge) — entity relationship understanding\n\n**Boundary rule:** Pipelines move and transform data. **Agents interpret it.**\n\n---\n\n### 3. Decide — \"What should we do?\"\n\n**Layers involved:** Capability Layer + Governance Layer\n\n**This is a hybrid zone:**\n\n**Agents (complex decisions):**\n\n- Capability routing — which runtime? which provider? which path?\n- Dynamic policy evaluation — context-dependent governance\n- Approval routing — should this go to human review?\n- Multi-step plan generation — breaking requests into dependent actions\n- Fallback chain selection — when primary fails, what's next?\n\n**Pipelines (rule-based decisions):**\n\n- Tier gate enforcement — subscription limits\n- Rate limiting — deterministic throttling\n- Static RBAC — role-based permissions\n- Simple routing tables — path → service mapping\n\n**Boundary rule:** If decision requires context reasoning → agent. If it checks a rule → pipeline.\n\n---\n\n### 4. Act — \"Do it.\"\n\n**Layers involved:** Provider Fabric + Capability Layer\n\n**Pipelines (deterministic execution):**\n\n- Spine writes (`pipeline` — sole writer to source of truth)\n- Connector API calls with known schemas\n- Workflow step execution (predetermined paths)\n- Data synchronization pushes\n- Billing event emission\n\n**Agents (adaptive execution):**\n\n- Multi-step workflows with branching\n- MCP tool negotiation and fallback\n- Provider fallback (alternative connectors)\n- Adaptive retry with backoff strategies\n- Real-time course correction\n\n---\n\n## The Human-In-The-Loop (HITL) Cycle\n\nHITL is where human judgment enters the OODA loop at the critical **Decide** phase:\n\n```\nUser Intent\n    ↓\n┌─────────────────────────────────────────┐\n│ OBSERVE: Capture intent + context       │\n│ (hitl-orchestrator.captureIntent)       │\n└─────────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────────┐\n│ ORIENT: AI generates proposal + reasoning\n│ (intelligence service generates proposal)│\n└─────────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────────┐\n│ DECIDE: Human approves/rejects/modifies │\n│ ↑ IRREDUCIBLE HUMAN AGENCY ↑            │\n│ (hitl-orchestrator.submitApproval)      │\n└─────────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────────┐\n│ ACT: Execute approved action            │\n│ (hitl-orchestrator.executeApprovedAction)\n└─────────────────────────────────────────┘\n    ↓\n┌─────────────────────────────────────────┐\n│ LEARN: Capture results + feedback       │\n│ → Feeds into knowledge, memory, signals │\n│ → Platform evolves for next cycle       │\n└─────────────────────────────────────────┘\n```\n\n## Nested OODA Loops\n\nOODA loops are recursive. An agent's **Act** becomes a pipeline's **Observe**:\n\n```\nRequest Level OODA\n  ├─ Observe: HTTP/MCP ingress\n  ├─ Orient: Capability resolution\n  ├─ Decide: Route to ADK runtime\n  └─ Act: Spawn agent task\n      ↓\n  Agent Level OODA\n    ├─ Observe: Memory + Knowledge + Spine\n    ├─ Orient: Plan generation\n    ├─ Decide: Which tools to call\n    └─ Act: Execute tool calls\n        ↓\n    Pipeline Level OODA\n      ├─ Observe: Tool results / webhook events\n      ├─ Orient: Data normalization\n      ├─ Decide: Write to spine? Emit signal?\n      └─ Act: Pipeline execution\n```\n\nThe `signals` service bridges these loops — an agent's action emits a signal that a pipeline observes.\n\n## Service-to-OODA Mapping\n\n| Service               | Primary Phase   | Type      | Role                                          |\n| --------------------- | --------------- | --------- | --------------------------------------------- |\n| **gateway**           | Observe         | Pipeline  | Ingress/routing only                          |\n| **connector-sync**    | Observe         | Pipeline  | Mechanical delta polling                      |\n| **webhook-ingress**   | Observe         | Pipeline  | Event ingestion                               |\n| **knowledge**         | Orient          | Hybrid    | Embedding (pipeline); Retrieval (agent)       |\n| **continuity**        | Orient          | Hybrid    | Maintenance (pipeline); Assembly (agent)      |\n| **intelligence**      | Orient + Decide | **Agent** | Core orientation + decision engine            |\n| **twin-orchestrator** | Orient          | **Agent** | Per-user context model                        |\n| **govern**            | Decide          | Hybrid    | Rules (pipeline); Routing (agent)             |\n| **pipeline**          | Act             | Pipeline  | Sole Spine writer                             |\n| **workflow**          | Act             | Hybrid    | Durable execution; branching = agent-directed |\n| **mcp-connector**     | Observe + Act   | Hybrid    | Ingestion (pipeline); Negotiation (agent)     |\n| **signals**           | All phases      | Hybrid    | Signal bridge between OODA cycles             |\n| **Projection Engine** | Orient + Act    | **Agent** | User-facing domain facades                    |\n\n## The HOME Model: Platform Evolution\n\nOODA loops enable continuous platform evolution through the **HOME** lifecycle:\n\n1. **Have** — Foundation (SDK, services, schema)\n2. **Own** — User control (RBAC, workspace customization)\n3. **Maintain** — Ongoing operations (compliance, audits, governance)\n4. **Learn** — Feedback loops (memory, signals, patterns from OODA cycles)\n5. **Evolve** — Adaptation (capability discovery, agent learning, preference refinement)\n\nEach HITL cycle generates data that feeds back:\n\n- **Observe** data → Signals (anomaly patterns, priorities)\n- **Orient** data → Knowledge (semantic learning) + Memory (context models)\n- **Decide** data → Governance (approval decisions, risk calibration)\n- **Act** data → Execution (success rates, fallback effectiveness)\n- **Learn** data → Agent models (outcome-based decision refinement)\n\nThe next HITL cycle benefits from this learning. The platform adapts to the user's needs as they learn.\n\n## Agent vs. Pipeline Decision Tree\n\n```\nIs the outcome deterministic?\n├─ YES → Use Pipeline\n│   (tier gates, rate limits, RBAC, schema transforms, spine writes)\n│\n└─ NO → Does it require reasoning about context?\n    ├─ YES → Use Agent\n    │   (capability routing, plan generation, approval decisions, fallback selection)\n    │\n    └─ NO → Could happen either way (Hybrid)\n        (knowledge retrieval, memory assembly, workflow branching, error recovery)\n```\n\n## Integration Patterns\n\n### Pattern 1: Agent Orchestrates, Pipeline Executes\n\nAgent decides **what** to do → Pipeline does it deterministically.\n\n_Example:_ Agent plans multi-step spine update → `pipeline` service executes write.\n\n### Pattern 2: Pipeline Observes, Agent Decides\n\nPipeline detects condition → Agent evaluates significance → Decides response.\n\n_Example:_ `connector-sync` detects delta → `intelligence` evaluates anomaly → triggers investigation.\n\n### Pattern 3: Agent Acts, Pipeline Reacts\n\nAgent executes external call → Pipeline handles webhook/event response.\n\n_Example:_ Agent calls Salesforce API → Webhook response → Pipeline normalizes and writes to spine.\n\n## Key Insight: The Irreducible Human\n\nIn the OODA loop, there is exactly **one irreducible point of human agency**: the **Decide** phase. This is where a human chooses whether to approve an AI proposal. Every other phase can be automated:\n\n- **Observe:** Captured by pipelines and agents\n- **Orient:** Generated by intelligence service\n- **Decide:** **Only humans can decide** (approval, rejection, modification)\n- **Act:** Executed by deterministic pipelines or adaptive agents\n- **Learn:** Captured by signals, memory, knowledge systems\n\nThe platform is designed around this principle. The HITL orchestrator centers on the Decide phase. Everything else supports it.\n\n---\n\n## References\n\n- See `services/gateway/src/hitl-orchestrator.ts` for HITL implementation with OODA phase annotations\n- See `v0_memories/user/ooda-loop-architecture.md` for detailed architectural reference\n- See individual service READMEs for service-specific OODA responsibilities\n"}