🖥 AgenticAI Cluster

Distributed AI compute cluster — nodes, models, tasks, and real-time monitoring

Cluster Nodes

Available Models

Recent Tasks

Event Log

AEEIP — System Dashboard

Automotive Ethernet Engineering Intelligence Platform — Engineering Knowledge Operating System for ADAS HPC Automotive Ethernet

System Boundary

Design Principles

System Architecture (SAD)

Federated MCP architecture — subsystems communicate exclusively through MCP tool invocations via VS Code Copilot. No direct service-to-service coupling.

Architectural Style

System Context

%%{init: {'flowchart': {'nodeSpacing': 42, 'rankSpacing': 52, 'curve': 'basis'}}}%%
flowchart LR
    subgraph IDE["VS Code Copilot"]
      direction TB
      SKILLS["Copilot Agent Skills x4"]
      MCPCFG["mcp.json config"]
    end

    subgraph BACKEND["Backend KBS :8000"]
      direction TB
      API["FastAPI MCP Server"]

      subgraph STORES["Data and Infra Stores"]
        direction LR
        NEO[("Neo4j :7687")]
        QDR[("Qdrant :6333")]
        PG[("PostgreSQL :5432")]
        MINIO[("MinIO :9000")]
        OLLAMA["Ollama :11434"]
      end
    end

    subgraph AETA["AETA Agent :8088"]
      direction TB
      AETASRV["MCP Server"]
      SQLITE[("SQLite")]
    end

    SKILLS -->|"orchestrates"| MCPCFG
    MCPCFG -->|"X-API-Key"| API
    MCPCFG -->|"no auth"| AETASRV
    API --> NEO & QDR & PG & MINIO & OLLAMA
    AETASRV --> SQLITE

    classDef control fill:#1f3a5f,stroke:#63b3ed,stroke-width:1.5px,color:#e2e8f0;
    classDef service fill:#16324f,stroke:#4fa3e3,stroke-width:1.5px,color:#e2e8f0;
    classDef store fill:#1a2a44,stroke:#7dd3fc,stroke-width:1.2px,color:#dbeafe;

    class MCPCFG,SKILLS control;
    class API,AETASRV,OLLAMA service;
    class NEO,QDR,PG,MINIO,SQLITE store;
  

Backend Hexagonal Decomposition

flowchart TB
    subgraph DRIVING["Driving Adapters"]
        REST["REST /api/v1/*"]
        MCP_T["MCP /api/v1/mcp/"]
        ADMIN["/admin"]
        GRAPH["/graph"]
        PORTAL["/portal/"]
    end

    subgraph APP["Application Layer"]
        UC1["GenerateCompletion"]
        UC2["IngestKnowledge"]
        UC3["AgentLoop"]
        UC5["KBSOrchestrator"]
        UC6["RuleEngine"]
    end

    subgraph DOMAIN["Domain Core"]
        ENT["Entities"]
        PORTS["Ports"]
        VO["Value Objects"]
    end

    subgraph DRIVEN["Driven Adapters"]
        A1["Neo4jGraphAdapter"]
        A2["QdrantAdapter"]
        A3["PostgresReviewAdapter"]
        A4["OllamaAdapter"]
        A5["MinIOAdapter"]
        A6["GovernanceTools x12"]
    end

    DRIVING --> APP
    APP --> DOMAIN
    DOMAIN --> DRIVEN
  

Architectural Decisions

Deployment View

Architectural Constraints

Quality Attributes

Software Requirements Specification (SWS)

System-level software requirements per Automotive SPICE SWE.1 — covers cross-cutting requirements spanning both Backend KBS and AETA Agent subsystems.

§4.1 Knowledge Graph

§4.2 Document Categories

§4.3 Governance and Access Control

§4.4 MCP Integration

§4.5 Semantic Retrieval

§4.6 Backup and Recovery

§5 AETA Agent Requirements

§6 Copilot Skill Requirements

§7 Non-Functional Requirements

§10 Traceability to Subsystem SWS

Software Architecture Description (SAD)

Backend hexagonal architecture per Automotive SPICE SWE.2 — port-based adapter design with domain isolation

Dynamic View — System Startup

sequenceDiagram
    participant DC as Docker Compose
    participant PG as PostgreSQL
    participant NEO as Neo4j
    participant QDR as Qdrant
    participant BE as Backend FastAPI
    participant DEV as Developer
    participant AETA as AETA Agent

    DC->>PG: start (healthcheck: pg_isready)
    DC->>NEO: start (healthcheck)
    DC->>QDR: start (healthcheck)
    DC->>BE: start (depends_on: healthy)
    BE->>BE: load settings, validate features
    BE->>PG: run Alembic migrations
    BE->>BE: Container.initialize()
    BE->>NEO: verify connection
    BE->>QDR: verify connection
    BE-->>DC: ready

    DEV->>AETA: python -m mcp_servers.aeta.src.mcp_kbs_server --port 8088
    AETA->>AETA: load symbol DB
    AETA-->>DEV: MCP server ready
  

Dynamic View — Knowledge Evolution Flow

sequenceDiagram
    participant DEV as Developer
    participant COP as Copilot Skill
    participant AETA as AETA MCP
    participant BE as Backend MCP
    participant NEO as Neo4j

    DEV->>COP: invoke trace-to-knowledge
    COP->>AETA: trace_full(workspace, source_dir)
    AETA-->>COP: trace chains + coverage
    COP->>AETA: search_code(symbol_name)
    AETA-->>COP: symbol details + call graph
    COP->>COP: generate knowledge evidence (MD)
    COP->>BE: kbs_update(upsert_node, ...)
    BE->>NEO: MERGE node
    BE-->>COP: node created (brief)
    COP->>BE: propose_relation(from, rel, to)
    BE->>NEO: MERGE relation (auto-approve)
    BE-->>COP: relation written
    COP-->>DEV: knowledge graph updated ✓
  

Dynamic View — Governance (Reviewer Path)

sequenceDiagram
    participant REV as Reviewer Agent
    participant BE as Backend MCP
    participant PG as PostgreSQL
    participant ARCH as Architect Agent
    participant NEO as Neo4j
    participant AUDIT as Audit Log

    REV->>BE: propose_relation(from, rel, to) [reviewer]
    BE->>PG: INSERT review_queue (pending)
    BE-->>REV: queued (proposal_id)

    Note over PG: Awaits architect approval

    ARCH->>BE: approve_relation(proposal_id) [architect]
    BE->>PG: UPDATE status=approved
    BE->>NEO: MERGE relation
    BE->>AUDIT: log(approve, architect, id)
    BE-->>ARCH: approved + written ✓
  

Port Interfaces

Skill Orchestration Layer

Software Detailed Design (SDD)

Cross-subsystem interface contracts per Automotive SPICE SWE.3 — MCP transport, graph schema, role model, audit, tool contracts

§2.1 MCP Transport Interface

MCP Client Configuration (mcp.json)

{
  "servers": {
    "local-kbs-mcp": {
      "type": "http",
      "url": "http://localhost:8000/api/v1/mcp/",
      "headers": { "X-API-Key": "<architect-or-admin-key>" }
    },
    "aeta-kbs": {
      "type": "http",
      "url": "http://localhost:8088/mcp/"
    }
  }
}

§2.2 Knowledge Graph Data Model

Node Schema

Allowed Labels (22)

Standard RFC IEEE AUTOSAR ISO Protocol Layer Feature SubFeature Requirement Design Component Service Signal Function ConfigParam SourceFile Rule Evidence Review Finding TestCase

Allowed Relation Types (24)

references implements specifies validates depends_on extends replaces conflicts_with part_of uses defines maps_to traces_to satisfies verifies allocates derives_from refines decomposes contains tests configures instantiates communicates_with

§2.2.5 Category Derivation Algorithm

CATEGORY_PATTERNS = [
    (r"^rfc-\d+",           "RFC"),
    (r"^refs-ietf-",        "RFC"),
    (r"^ieee-",             "IEEE"),
    (r"^refs-ieee-",        "IEEE"),
    (r"^autosar-sws-",      "Classic_AUTOSAR"),
    (r"^ar-",               "Classic_AUTOSAR"),
    (r"^ecuc-",             "Classic_AUTOSAR"),
    (r"^autosar-ap-",       "Adaptive_AUTOSAR"),
    (r"^ara-",              "Adaptive_AUTOSAR"),
    (r"^qnx-",             "QNX"),
    (r"^secoc-|^csm-|^tls-|^idsm-|^macsec-", "CyberSecurity"),
    (r"^iso-26262|^asil-|^fusa-",             "FUSA"),
]

def derive_category(ext_id: str, label: str) -> str:
    for pattern, category in CATEGORY_PATTERNS:
        if re.match(pattern, ext_id, re.IGNORECASE):
            return category
    return LABEL_DEFAULTS.get(label, "General")

§2.3 Role and Permission Model

Auto-Approve Logic

# In ProposeRelationTool.execute():
caller_role_rank = ROLE_RANKS[current_api_key.role]

if caller_role_rank >= ROLE_RANKS["architect"]:  # rank >= 3
    # Direct write — no review queue
    self._graph.upsert_relation(from_ext_id, rel_type, to_ext_id, properties)
    return ToolResult(content=f"Auto-approved: {from_ext_id} —[{rel_type}]→ {to_ext_id}")
else:
    # Queue for review
    self._review.create_proposal(from_ext_id, rel_type, to_ext_id, properties, caller)
    return ToolResult(content=f"Queued for architect approval: proposal #{id}")

§2.4 Audit and Review Queue (PostgreSQL)

CREATE TABLE review_queue (
    id            SERIAL PRIMARY KEY,
    from_ext_id   VARCHAR(256) NOT NULL,
    relation_type VARCHAR(64)  NOT NULL,
    to_ext_id     VARCHAR(256) NOT NULL,
    properties    JSONB,
    proposer      VARCHAR(256) NOT NULL,
    status        VARCHAR(16)  NOT NULL DEFAULT 'pending',
    reviewer      VARCHAR(256),
    review_reason TEXT,
    created_at    TIMESTAMP DEFAULT NOW(),
    reviewed_at   TIMESTAMP
);

CREATE TABLE audit_log (
    id         SERIAL PRIMARY KEY,
    action     VARCHAR(64)  NOT NULL,  -- propose|approve|reject|direct_write|delete
    actor      VARCHAR(256) NOT NULL,
    target     TEXT         NOT NULL,
    details    JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

§3.1 Backend MCP Tool Contracts

Tool: kbs_update — Direct graph mutation (admin only)

Input:
  action: "upsert_node" | "delete_node" | "upsert_relation" | "delete_relation"

  upsert_node:  { label, ext_id, properties: {title, description?, category?} }
  delete_node:  { ext_id }
  upsert_relation: { from_ext_id, relation_type, to_ext_id, properties? }
  delete_relation: { from_ext_id, relation_type, to_ext_id }

Output:
  "Upserted: RFC / Requirement / RFC9293-MUST-19 — TCP MUST send RST"

Tool: propose_relation — Governed relation creation

Input:
  from_ext_id: str
  relation_type: str (from allowed types)
  to_ext_id: str
  properties: dict (optional)
  evidence: str (justification text)

Output (architect+): "Auto-approved: {from} —[{rel}]→ {to}"
Output (reviewer):   "Queued: proposal #{id} pending architect approval"

Tool: trace_protocol — N-hop graph traversal

Input:
  start_node: str (ext_id)
  hops: int (1-5, default 2)
  direction: "outgoing" | "incoming" | "both" (default "both")

Output:
  List of nodes with brief, grouped by hop distance
  Includes: ext_id, title, category, label, description, relations

Tool: kbs_search — Semantic vector retrieval

Input:
  query: str
  top_k: int (default 10)
  source_filter: str (optional, e.g. "rfc", "ieee")

Output:
  Ranked list of document chunks with score, source, and content

§5 Database Migration Strategy (Alembic)

§6 Configuration Management

§7 Design Traceability

Admin — API Key & User Management

Manage API keys and user accounts for Backend KBS

Review Queue — Knowledge Graph Governance

Review, approve, or reject proposed graph changes (relations, KA candidates, rules)

MCP Tool Catalog

Complete tool surface exposed via Model Context Protocol — 12 Backend + 9 AETA tools

Roles & Governance

5-level role hierarchy with graduated permission escalation — enforcement at auth middleware and tool level

Permission Matrix

Enforcement Points

Governance Flow

flowchart LR
    REV["Reviewer\n(propose)"] -->|queue| RQ[(review_queue\npending)]
    RQ -->|approve| ARCH["Architect\n(approve)"]
    ARCH -->|write| NEO1[(Neo4j)]

    ARCH2["Architect\n(propose)"] -->|auto-approve| NEO2[(Neo4j)]

    ADM["Admin\n(kbs_update)"] -->|direct write| NEO3[(Neo4j)]
  

API Key Binding

# Master key (env ADMIN_MASTER_KEY) → always admin, no DB lookup
# Regular keys → role in PostgreSQL api_keys.role (VARCHAR 32)

# MCP config:
"headers": { "X-API-Key": "sk-..." }

# Create via REST:
POST /api/v1/api-keys { "name": "bot", "role": "architect" }

# Create via Admin UI:
http://localhost:8000/portal/ → Admin → Connect → Create Key

Categories & Graph Schema

Document classification taxonomy, graph validation rules, and label-pair constraints

Document Categories

Brief Display Format

"{category} / {label} / {title} — {first sentence of description}"

Examples:
  "RFC / Requirement / RFC9293-MUST-19 — TCP MUST send RST when receiving invalid segment"
  "Classic_AUTOSAR / ConfigParam / TcpIpTcpCongestionAvoidanceEnabled — Enables AIMD algorithm"
  "IEEE / Feature / TSN Credit-Based Shaper — Traffic shaping for AVB streams"

Label-Pair Rule Validation

label_pair_rules:
  - { from_label: Feature,     relation: contains,         to_label: SubFeature }
  - { from_label: Requirement, relation: traces_to,        to_label: Design }
  - { from_label: Design,      relation: implements,       to_label: Component }
  - { from_label: Component,   relation: uses,             to_label: Function }
  - { from_label: TestCase,    relation: verifies,         to_label: Requirement }
  - { from_label: ConfigParam, relation: configures,       to_label: SubFeature }
  - { from_label: Standard,    relation: specifies,        to_label: Protocol }
  - { from_label: Protocol,    relation: defines,          to_label: Feature }
  - { from_label: SourceFile,  relation: implements,       to_label: Function }
  - { from_label: Evidence,    relation: derives_from,     to_label: SourceFile }
  - { from_label: Finding,     relation: references,       to_label: Rule }
  # ... (full list in config/rules/knowledge_graph_rules.yaml)

Knowledge Graph Rules YAML Structure

labels:
  - name: Feature
    description: "High-level system feature"
    required_properties: [ext_id, title]
    optional_properties: [category, description]

categories:
  - name: RFC
    patterns: ["^rfc-\\d+", "^refs-ietf-"]
  - name: IEEE
    patterns: ["^ieee-", "^refs-ieee-"]
  # ...

relations:
  - name: references
    description: "General reference link"
  - name: implements
    description: "Implementation relationship"
  # ...

Endpoint Configuration

Configure the connection endpoints for Knowledge Graph (remote Backend KBS) and Traceability Graph (local AETA).