AI Capability Architecture

1. Architecture Objective

The Site Application needs one architecture that supports simple chat, RAG assistants, tool-using agents, deterministic automation, and autonomous operating loops without coupling the platform to a single vendor.

The architecture therefore separates definition, implementation, execution, knowledge, identity, and user experience.

2. Logical Architecture

flowchart TD
    subgraph SITE["Site Application"]
      UX(["Side Menu / Page / Object / Event / Job / API / User Interaction"]):::actor
    end
    subgraph REG["AI Capability Registry"]
      C[("Assistant / Agent / Automation / Autonomous")]:::store
      CFG[("Prompt / Model / Knowledge / Tools / Flow / Permissions / Policy")]:::store
      C --> CFG
    end
    subgraph EXEC["Execution and Orchestration"]
      R[["Direct API / Client SDK / Agent SDK / Flowise / n8n / Custom Code"]]:::process
    end
    subgraph CORE["Runtime Resources"]
      M["Model / Inference<br/>LLM / Embedding / Vision / Audio<br/>Local or Cloud"]:::model
      K[("Knowledge and Memory<br/>Documents / Chunking / Embeddings<br/>Vector Search / Reranking / Session State")]:::store
      T["Tools / Integrations<br/>REST / OpenAPI / MCP<br/>Jobs / Events / Enterprise APIs"]:::process
    end
    subgraph GOV["Governance and Observability"]
      G["Identity / RBAC / Approval / Audit / Trace / Cost / Safety / Policy"]:::govern
    end
    UX --> C
    CFG --> R
    R --> M
    R --> K
    R --> T
    M -.-> G
    K -.-> G
    T -.-> G

    style SITE fill:#94A3B81A,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:3 3
    style REG fill:#94A3B81A,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:3 3
    style EXEC fill:#94A3B81A,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:3 3
    style CORE fill:#94A3B81A,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:3 3
    style GOV fill:#94A3B81A,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:3 3

    classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
    classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220

3. Control Planes

3.1 Definition Plane

Stores what the capability is:

Capability identity and type.
Purpose and description.
Prompt template.
Model/provider reference.
Knowledge source references.
Tool/connector references.
Flow/workflow reference.
Business-object bindings.
User/group/site permissions.
Execution and autonomy policy.

3.2 Runtime Plane

Executes the capability using one of the supported runtimes:

flowchart TD
    C[("Capability Definition")]:::store --> API[["Direct Provider API"]]:::model
    C --> SDK[["Provider Client SDK"]]:::model
    C --> AG[["Agent SDK"]]:::model
    C --> F[["Flowise Flow"]]:::process
    C --> N[["n8n Workflow"]]:::process
    C --> X[["Custom Service / Code"]]:::process
    C --> E[["External SaaS / On-Prem Application"]]:::external

    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
    classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#0B1220,stroke-dasharray:4 3

3.3 Knowledge Plane

Maintains persistent reference information separately from conversation state.

flowchart TD
    D(["Documents / Text / Data"]):::actor --> N["Normalize / Extract"]:::process
    N --> C["Chunk"]:::process
    C --> E["Embed"]:::model
    E --> V[("Vector Store + Metadata")]:::store
    V --> S["Search / Filter / Rerank"]:::store
    S --> X["Context"]:::process
    X --> M[["Model"]]:::model

    classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220

3.4 Identity Plane

Identity must travel through the architecture rather than being re-created independently inside each AI application.

flowchart TD
    U(["Site User"]):::actor --> I["Site Authentication"]:::govern
    I --> C["Capability Permission"]:::govern
    I --> B["Business Object Permission"]:::govern
    I --> K["Knowledge ACL"]:::govern
    I --> T["Tool Permission"]:::govern
    I --> D[["Delegated External Identity"]]:::external
    I --> S[["Service Identity"]]:::external

    classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
    classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
    classDef external fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#0B1220,stroke-dasharray:4 3

3.5 Experience Plane

The UI layer can be native or external.

Experience	Use
Native Site component	Custom assistant/agent experiences
Embedded iframe/browser	Flowise, n8n, Open WebUI, studios, external tools
Redirect	Applications that cannot or should not be embedded
Background execution	Agent, automation, or autonomous operation without active UI

4. Runtime Selection

flowchart TD
    A{"Is the sequence completely predefined?"}:::gate
    A -->|"Yes"| AUT[["Automation / n8n / code workflow"]]:::process
    A -->|"No"| B{"Does the model only need to answer or generate?"}:::gate
    B -->|"Yes"| AS[["Assistant via client SDK / direct API"]]:::model
    B -->|"No"| C{"Must the model select tools or steps dynamically?"}:::gate
    C -->|"Yes"| AG[["Agent SDK / Flowise Agentflow / custom agent"]]:::model
    C -->|"No"| O[["Simple orchestrated flow"]]:::process
    AUT --> D{"Continue without a user request?"}:::gate
    AS --> D
    AG --> D
    O --> D
    D -->|"Yes"| P["Apply Autonomous policy and governance"]:::govern
    D -->|"No"| E(["Run as bounded execution"]):::output

    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef gate fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#0B1220
    classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
    classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220

5. Common Execution Contract

All runtimes should map into a common Site execution envelope.

{
  "site_id": "site-reference",
  "capability_id": "capability-reference",
  "capability_type": "assistant|agent|automation|autonomous",
  "execution_id": "execution-reference",
  "correlation_id": "correlation-reference",
  "user_context": {},
  "business_context": {},
  "input": {},
  "knowledge_scope": [],
  "tool_scope": [],
  "policy": {}
}

And return a normalized result:

{
  "execution_id": "execution-reference",
  "status": "completed|failed|waiting|approval_required",
  "output": {},
  "actions": [],
  "citations": [],
  "artifacts": [],
  "usage": {},
  "trace_reference": "trace-reference"
}

6. Boundary Between AI and Automation

Do not allow model reasoning to replace deterministic logic where deterministic logic is sufficient.

Problem	Preferred Mechanism
Fixed data transformation	Automation/code
Scheduled API synchronization	Automation
Fixed approval routing	Workflow/rules
Explain a document	Assistant
Decide which tool to use	Agent
Diagnose across multiple uncertain signals	Agent
Continue monitoring and re-plan over time	Autonomous policy around agents/automation

7. Autonomy as an Execution Policy

Autonomy should be implemented as policy over a capability composition, not as a magical separate runtime.

flowchart TD
    O(["Objective"]):::actor --> A[["Planner / Agent"]]:::model
    A --> K["Read knowledge"]:::store
    A --> T["Invoke tools"]:::process
    A --> W[["Invoke automation"]]:::process
    A --> H(["Ask assistant / human when needed"]):::actor
    K --> P{"Policy Evaluation"}:::govern
    T --> P
    W --> P
    H --> P
    P -->|"Allowed"| E["Execute"]:::process
    P -->|"Approval"| R["Wait for approval"]:::govern
    P -->|"Denied"| S(["Stop / Escalate"]):::govern
    E --> V["Observe Result"]:::process
    V --> D{"Objective complete?"}:::gate
    D ==>|"No"| A
    D -->|"Yes"| C(["Complete"]):::output

    classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
    classDef gate fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#0B1220
    classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
    classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220

8. Required Cross-Cutting Controls

Every implementation should define:

Authentication method.
Authorization scope.
Secret reference.
Data/knowledge scope.
Tool allowlist.
Human approval points.
Timeout and retry policy.
Maximum steps/iterations.
Cost or token limits where applicable.
Audit events.
Correlation and trace identifiers.
Failure and rollback behavior.
Version of prompt, flow, model configuration, and tool contract.

9. Architectural Non-Goals

This design does not require:

Every assistant to become an agent.
Every automation to use an LLM.
Every REST API to be converted to MCP.
Every agent to run in a sandbox.
Every external AI application to maintain separate user accounts.
Every implementation to share one physical runtime.

The goal is a common Site contract with pluggable runtimes.

1. Architecture Objective​

2. Logical Architecture​

3. Control Planes​

3.1 Definition Plane​

3.2 Runtime Plane​

3.3 Knowledge Plane​

3.4 Identity Plane​

3.5 Experience Plane​

4. Runtime Selection​

5. Common Execution Contract​

6. Boundary Between AI and Automation​

7. Autonomy as an Execution Policy​

8. Required Cross-Cutting Controls​

9. Architectural Non-Goals​