MetaForge System Architecture

Internal Technical Documentation This document describes the internal architecture, component interactions, and data flows within MetaForge.

Overview

MetaForge is structured as a control plane that orchestrates specialist agents and tool adapters to transform human intent into manufacturable hardware artifacts.

1. High-Level System Architecture

The diagram below shows the complete data flow through MetaForge. Key architectural property: IDE Assistants and Domain Agents operate on the Digital Twin concurrently — assistants surface previews and diffs to the engineer while agents read context, run tools, and write artifacts, all against the same shared artifact graph.

flowchart TD
    HUMAN(("Engineer")) -->|"design intent"| UI["IDE / CLI"]
    UI -->|"structured request"| GW["Gateway Service<br/>HTTP · WebSocket · Auth"]

    GW -->|"create session"| ORCH

    subgraph ORCH["Orchestrator"]
        direction LR
        EB["Event Bus"] ---|publish/subscribe| DEP["Dependency Engine"]
        DEP ---|resolve order| SCHED["Scheduler · DAG Runner"]
    end

    ORCH -->|"coordinate"| ASSIST
    ORCH -->|"dispatch tasks"| AGENTS

    subgraph ASSIST["IDE Assistants — concurrent"]
        direction LR
        A_CAD["CAD"]
        A_PCB["PCB"]
        A_FW["Firmware"]
        A_SIM["Simulation"]
    end

    subgraph TWIN["Digital Twin — Single Source of Truth"]
        direction LR
        GRAPH["Artifact Graph"]
        VER["Versioning"]
        CONST["Constraint Engine"]
    end

    subgraph AGENTS["Domain Agents — concurrent"]
        direction LR
        ME["Mechanical"]
        EE["Electronics"]
        FW["Firmware"]
        SIM["Simulation"]
    end

    ASSIST <-->|"read state · show diffs · propose changes"| TWIN
    AGENTS <-->|"read context · write artifacts · validate constraints"| TWIN

    AGENTS -->|"invoke skills"| SR["Skill Registry<br/>Loader · Schema Validator · MCP Bridge"]
    SR -->|"MCP protocol"| MCP["MCP Layer<br/>Client · Protocol · Tool Registry"]
    MCP -->|"execute"| TOOLS

    subgraph TOOLS["External Tools"]
        direction LR
        T_CAD["FreeCAD"]
        T_PCB["KiCad"]
        T_SIM["SPICE"]
        T_FEA["CalculiX"]
        T_API["Supplier APIs"]
    end

    TOOLS -.->|"results"| MCP
    MCP -.->|"structured output"| SR
    SR -.->|"skill output"| AGENTS

    TWIN -.->|"change proposal"| ORCH
    ORCH -.->|"approval request"| GW
    GW -.->|"diff preview"| UI
    UI -.->|"approve / reject"| GW
    GW -.->|"commit change"| TWIN

    GW -->|"write trace"| STORE[".forge/ State<br/>Sessions · Traces · Artifacts"]
    STORE -->|"version"| GIT["Git"]

    style TWIN fill:#2C3E50,color:#fff,stroke:#E67E22,stroke-width:3px
    style ORCH fill:#8e44ad,color:#fff
    style GW fill:#2C3E50,color:#fff
    style HUMAN fill:#E67E22,color:#fff
    style GIT fill:#27ae60,color:#fff
    style ASSIST fill:#3498db,color:#fff,stroke:#3498db
    style AGENTS fill:#3498db,color:#fff,stroke:#3498db

Data flow summary:

2. Component Architecture

2.1 MetaForge CLI

Purpose: Primary user interface and command executor

graph LR
    subgraph "CLI Commands"
        A1[setup]
        A2[onboard]
        A3[gateway]
        A4[doctor]
        A5[run]
        A6[approve]
        A7[status]
    end

    subgraph "CLI Core"
        B[Commander.js<br/>Parser]
        C[HTTP Client<br/>Gateway API]
        D[Terminal UI<br/>Inquirer/Chalk]
    end

    A1 --> B
    A2 --> B
    A3 --> B
    A4 --> B
    A5 --> B
    A6 --> B
    A7 --> B

    B --> C
    B --> D
    C --> E[Gateway Service]

    style B fill:#3498db,color:#fff
    style E fill:#2C3E50,color:#fff

Command Flow:

1. User invokes CLI command
2. Commander.js parses arguments
3. HTTP client sends request to Gateway
4. Terminal UI displays results/prompts

2.2 Gateway Service

Purpose: Control plane, orchestration, and state management

graph TB
    subgraph "Gateway Core"
        A[HTTP Server<br/>FastAPI]
        B[WebSocket Server<br/>Real-time Updates]
    end

    subgraph "Request Handlers"
        C1[Session Handler]
        C2[Agent Handler]
        C3[Approval Handler]
        C4[Status Handler]
    end

    subgraph "Core Services"
        D1[Session Manager]
        D2[Agent Router]
        D3[Permission Enforcer]
        D4[State Store]
        D5[Trace Logger]
    end

    A --> C1
    A --> C2
    A --> C3
    A --> C4
    B --> C1

    C1 --> D1
    C2 --> D2
    C3 --> D3
    C4 --> D4

    D1 --> D4
    D2 --> D4
    D3 --> D4
    D2 --> D5
    D3 --> D5

    style A fill:#2C3E50,color:#fff
    style D4 fill:#E67E22,color:#fff

API Endpoints (v0.1):

# Session Management
POST   /api/v1/session/create
GET    /api/v1/session/{id}
DELETE /api/v1/session/{id}
GET    /api/v1/sessions

# Agent Execution
POST   /api/v1/agent/run
GET    /api/v1/agent/{id}/status

# Approval Workflow
GET    /api/v1/pending
POST   /api/v1/approve/{session}
POST   /api/v1/reject/{session}

# System Status
GET    /api/v1/status
GET    /api/v1/health

2.3 Agent System

Purpose: Specialist task executors with LLM integration

graph TB
    subgraph "Agent Base (Pydantic AI + Temporal)"
        A[Pydantic AI Agent]
        AR[Temporal Activity<br/>Durable Execution]
        B[LLM Provider<br/>Model-Agnostic]
        B1[openai SDK]
        B2[anthropic SDK]
        C[MCP Toolsets]
        D[Context Manager]
    end

    subgraph "Specialist Agents"
        E1[Requirements Agent<br/>PRD → Constraints]
        E2[Architecture Agent<br/>Constraints → Design]
        E3[Power Agent<br/>Design → Budget]
        E4[Schematic Agent<br/>Design → Plan]
        E5[BOM Agent<br/>Schematic → BOM]
        E6[DFM Agent<br/>PCB → Report]
    end

    A --> AR
    AR --> E1
    AR --> E2
    AR --> E3
    AR --> E4
    AR --> E5
    AR --> E6

    E1 --> B
    E2 --> B
    E3 --> B
    E4 --> B
    E5 --> B
    E6 --> B

    B --> B1
    B --> B2

    E1 --> C
    E2 --> C
    E5 --> C

    B --> D
    C --> D

    style A fill:#9b59b6,color:#fff
    style AR fill:#8e44ad,color:#fff
    style B fill:#3498db,color:#fff

Agent Orchestration (ADR-001): MetaForge uses Pydantic AI as the agent framework layer with Temporal for durable execution and a custom hardware harness on top. Pydantic AI provides typed agent definitions, native MCP connections (FreeCAD, KiCad, SPICE, Neo4j), and Pydantic-validated structured output. Temporal provides crash recovery, deterministic replay, and human-in-the-loop approval gates for long-running hardware design workflows. The custom harness (L4) adds hardware-domain prompt engineering, tool error recovery, design-rule context injection, and EVT/DVT/PVT lifecycle hooks.

Agent Lifecycle:

stateDiagram-v2
    [*] --> Created: Gateway spawns agent
    Created --> Loading: Load context
    Loading --> Executing: Run LLM
    Executing --> Processing: Process response
    Processing --> Validating: Validate output
    Validating --> Completed: Success
    Validating --> Failed: Error
    Completed --> [*]
    Failed --> [*]

    note right of Executing
        Agent calls LLM
        Uses tools as needed
        Generates artifacts
    end note

    note right of Validating
        Schema validation
        Safety checks
        Output verification
    end note

2.4 Tool Adapters

Purpose: Clean interfaces to external tools and services

graph TB
    subgraph "Tool Adapter Base"
        A[Tool Interface]
        B[Capability Detection]
        C[Error Handling]
    end

    subgraph "EDA Tools"
        D1[KiCad Adapter]
        D2[Altium Adapter]
        D3[Eagle Adapter]
    end

    subgraph "Simulation & Analysis"
        E1[ngspice Adapter]
        E2[LTspice Adapter]
        E3[Ansys FEA Adapter]
        E4[CalculiX Adapter]
        E5[OpenFOAM Adapter]
    end

    subgraph "Supply Chain APIs"
        F1[Nexar/Octopart API]
        F2[Mouser API]
        F3[Digi-Key API]
        F4[LCSC API]
    end

    subgraph "CAD Tools"
        H1[SOLIDWORKS Adapter]
        H2[Fusion 360 Adapter]
        H3[FreeCAD Adapter]
    end

    subgraph "Firmware Toolchain"
        G1[GCC/ARM Toolchain]
        G2[CMake/Make]
        G3[Flash Tools<br/>OpenOCD/pyOCD]
    end

    subgraph "Lab Automation"
        L1[SCPI/VISA Adapter]
        L2[OpenTAP Adapter]
    end

    subgraph "Manufacturing"
        M1[MacroFab API]
        M2[JLCPCB API]
    end

    subgraph "Data Layer"
        N1[Neo4j Adapter<br/>Digital Thread]
        N2[MinIO Adapter<br/>Object Storage]
    end

    subgraph "CI/CD"
        P1[GitHub Actions]
        P2[GitLab CI]
    end

    A --> D1
    A --> D2
    A --> D3
    A --> E1
    A --> E2
    A --> E3
    A --> F1
    A --> F2
    A --> F3
    A --> F4
    A --> H1
    A --> H2
    A --> H3
    A --> E4
    A --> E5
    A --> G1
    A --> G2
    A --> G3
    A --> L1
    A --> L2
    A --> M1
    A --> M2
    A --> N1
    A --> N2
    A --> P1
    A --> P2

    B --> A
    C --> A

    style A fill:#e67e22,color:#fff
    style N1 fill:#27ae60,color:#fff
    style N2 fill:#27ae60,color:#fff

Agent-Tool Access Matrix

Unified view of which agents access which tool adapters. All agents have access to Neo4jAdapter and MinIOAdapter (Data Layer) for digital thread and artifact storage.

Phase 2 tool expansions for existing agents:

• EE: + KiCad write (schematic generation, PCB auto-routing), Altium, LTspice, LCSC
• FW: + Flash Tools (OpenOCD/pyOCD)
• SIM: + LTspice, Ansys FEA
• TST: + SCPI, VISA, OpenTAP, GitLab CI
• MFG: + MacroFab, JLCPCB
• SC: + LCSC

Example: KiCad Adapter Interface

interface KiCadAdapter extends ToolAdapter {
  // Detection
  detect(): Promise<KiCadInstall | null>;
  getVersion(): Promise<string>;

  // Project Operations
  openProject(path: string): Promise<void>;
  closeProject(): Promise<void>;

  // Schematic Operations
  runERC(): Promise<ERCResult>;
  exportNetlist(format: string): Promise<string>;
  exportBOM(format: string): Promise<BOMData>;

  // PCB Operations
  runDRC(): Promise<DRCResult>;
  exportGerbers(config: GerberConfig): Promise<void>;
  exportPickPlace(): Promise<string>;

  // Utilities
  getComponents(): Promise<Component[]>;
  getPinMapping(): Promise<PinMap>;
}

3. Data Flow Architecture

3.1 Complete Workflow: PRD → Requirements

sequenceDiagram
    participant User
    participant CLI
    participant Gateway
    participant SessionMgr as Session Manager
    participant PermSys as Permission System
    participant Agent as Requirements Agent
    participant LLM as LLM Provider
    participant Store as State Store
    participant FS as File System

    User->>CLI: forge run spec
    CLI->>Gateway: POST /api/v1/agent/run {skill: "spec"}

    Gateway->>SessionMgr: Create session
    SessionMgr->>Store: Write session metadata
    Store-->>SessionMgr: Session ID
    SessionMgr-->>Gateway: Session created

    Gateway->>PermSys: Check permissions
    PermSys-->>Gateway: Read permission OK

    Gateway->>FS: Read PRD.md
    FS-->>Gateway: PRD content

    Gateway->>Agent: Execute(PRD content)
    Agent->>LLM: Prompt with PRD
    LLM-->>Agent: Structured response
    Agent->>Agent: Parse & validate
    Agent-->>Gateway: Artifacts {constraints.json, assumptions.md}

    Gateway->>Store: Write pending changes
    Gateway->>Store: Write trace log
    Store-->>Gateway: Changes staged

    Gateway-->>CLI: Response {session_id, diff, artifacts}
    CLI->>User: Display diff & request approval

    User->>CLI: forge approve
    CLI->>Gateway: POST /api/v1/approve/:session

    Gateway->>PermSys: Check write permission
    PermSys-->>Gateway: Approval required → OK

    Gateway->>FS: Write constraints.json
    Gateway->>FS: Write assumptions.md
    FS-->>Gateway: Files written

    Gateway->>SessionMgr: Mark session complete
    SessionMgr->>Store: Update session status

    Gateway-->>CLI: Success
    CLI-->>User: ✅ Changes applied

3.2 Session Lifecycle

stateDiagram-v2
    [*] --> Created: CLI request
    Created --> Running: Agent starts
    Running --> Processing: Agent executing
    Processing --> PendingApproval: Has file changes
    Processing --> Completed: No changes needed
    PendingApproval --> Approved: User approves
    PendingApproval --> Rejected: User rejects
    Approved --> Applying: Writing files
    Applying --> Completed: Success
    Applying --> Failed: Write error
    Running --> Failed: Agent error
    Completed --> [*]
    Failed --> [*]
    Rejected --> [*]

    note right of Created
        Session metadata:
        - ID, timestamp
        - Skill name
        - Input files
        - User context
    end note

    note right of PendingApproval
        Staged changes:
        - Diffs
        - New files
        - Safety warnings
    end note

    note right of Completed
        Final state:
        - Artifacts committed
        - Trace logged
        - Git commit (optional)
    end note

3.3 Agent Execution Flow

flowchart TD
    A[Agent Invoked] --> B{Load Context}
    B --> C[Read Input Files]
    C --> D[Build Prompt]
    D --> E{Has Tools?}

    E -->|Yes| F[Register Tools]
    E -->|No| G[Call LLM]
    F --> G

    G --> H{Tool Calls?}
    H -->|Yes| I[Execute Tools]
    I --> J{More Calls?}
    J -->|Yes| G
    J -->|No| K[Parse Response]

    H -->|No| K

    K --> L{Validate Output}
    L -->|Invalid| M[Retry with Feedback]
    M --> G

    L -->|Valid| N[Generate Artifacts]
    N --> O{Safety Check}

    O -->|Fail| P[Reject & Log]
    O -->|Pass| Q[Stage Changes]

    Q --> R[Return to Gateway]
    P --> S[Return Error]

    style G fill:#3498db,color:#fff
    style O fill:#e74c3c,color:#fff
    style Q fill:#27ae60,color:#fff

3.4 Multi-Agent Workflow

flowchart TD
    A[User: forge run architecture] --> B[Gateway]

    B --> C{Dependencies Met?}
    C -->|No constraints.json| D[Error: Run spec first]
    C -->|Yes| E[Spawn Architecture Agent]

    E --> F[Architecture Agent]
    F --> G[Generate Block Diagram]
    G --> H[Select Components]
    H --> I[Create architecture.md]

    I --> J[Stage for Approval]
    J --> K{User Approves?}

    K -->|No| L[Discard]
    K -->|Yes| M[Write Files]

    M --> N{Next Workflow?}
    N -->|User: forge run schematic-plan| O[Spawn Schematic Agent]
    N -->|Stop| P[Done]

    O --> Q[Schematic Agent]
    Q --> R[Read architecture.md]
    R --> S[Plan Schematic Approach]
    S --> T[Stage for Approval]

    T --> U{Approve?}
    U -->|Yes| V[Write schematic-plan.md]
    U -->|No| L

    V --> P

    style B fill:#2C3E50,color:#fff
    style F fill:#9b59b6,color:#fff
    style Q fill:#9b59b6,color:#fff

4. Workspace & State Management

4.1 Workspace Structure

graph TD
    A[Project Root] --> B[User Files]
    A --> C[Generated]
    A --> D[.forge/]

    B --> B1[PRD.md]
    B --> B2[decisions.md]

    C --> C1[constraints.json]
    C --> C2[architecture.md]
    C --> C3[eda/]
    C --> C4[bom/]
    C --> C5[firmware/]
    C --> C6[manufacturing/]

    D --> D1[config.json]
    D --> D2[sessions/]
    D --> D3[runs/]
    D --> D4[traces/]
    D --> D5[artifacts/]

    D2 --> D2A[session-123/<br/>metadata.json<br/>trace.jsonl<br/>artifacts/]

    D4 --> D4A[2024-02-03.jsonl]

    style A fill:#E67E22,color:#fff
    style D fill:#2C3E50,color:#fff
    style D1 fill:#F39C12,color:#000

Directory Details:

project/
├── PRD.md                      # User-written requirements
├── constraints.json            # Generated by requirements agent
├── decisions.md                # Design decision log
│
├── eda/                        # EDA tool files
│   └── kicad/
│       ├── board.kicad_sch
│       └── board.kicad_pcb
│
├── bom/                        # Bill of materials
│   ├── bom.csv
│   ├── alternates.csv
│   └── costing.json
│
├── firmware/                   # Firmware source
│   ├── src/
│   ├── pinmap.json
│   └── CMakeLists.txt
│
├── manufacturing/              # Manufacturing outputs
│   ├── gerbers/
│   ├── pick_place.csv
│   └── assembly_notes.md
│
├── tests/                      # Test plans
│   └── bringup.md
│
└── .forge/                     # MetaForge internal state
    ├── config.json             # Workspace config
    │
    ├── sessions/               # Active & completed sessions
    │   └── abc123/
    │       ├── metadata.json   # Session info
    │       ├── trace.jsonl     # Execution trace
    │       └── artifacts/      # Staged changes
    │
    ├── runs/                   # Historical run data
    │   └── run-456.json
    │
    ├── traces/                 # Daily trace logs
    │   └── 2024-02-03.jsonl
    │
    └── artifacts/              # Cached artifacts
        └── component-db.json

4.2 State Store Schema

erDiagram
    CONFIG {
        string version
        string workspace_path
        object gateway_config
        object permissions
        object tools
    }

    SESSION {
        string id
        string skill
        string status
        datetime created
        datetime updated
        object input
        object output
        array traces
    }

    TRACE {
        datetime timestamp
        string session_id
        string agent
        string action
        object data
        string level
    }

    ARTIFACT {
        string path
        string type
        string content
        string hash
        datetime created
    }

    CONFIG ||--o{ SESSION : configures
    SESSION ||--|{ TRACE : contains
    SESSION ||--o{ ARTIFACT : produces

5. Permission & Safety Model

5.1 Permission Flow

flowchart TD
    A[Request Received] --> B{Request Type?}

    B -->|Read| C{File Accessible?}
    C -->|Yes| D[Allow]
    C -->|No| E[Reject: Access Denied]

    B -->|Write| F{Requires Approval?}
    F -->|Yes| G{Approved?}
    F -->|No| H{Safe Operation?}

    G -->|Yes| I[Execute & Log]
    G -->|No| J[Stage for Review]

    H -->|Yes| I
    H -->|No| K[Reject: Unsafe]

    B -->|Execute| L{Tool Safe?}
    L -->|Yes| M{Has Permission?}
    L -->|No| N[Reject: Dangerous Tool]

    M -->|Yes| I
    M -->|No| O[Require Explicit Grant]

    I --> P[Write Trace]
    J --> Q[Notify User]

    D --> R[Success]
    E --> S[Error]
    K --> S
    N --> S
    P --> R

    style D fill:#27ae60,color:#fff
    style E fill:#e74c3c,color:#fff
    style I fill:#3498db,color:#fff
    style J fill:#f39c12,color:#000

5.2 Permission Levels

graph LR
    subgraph "Permission Hierarchy"
        A[Read Only] --> B[Propose]
        B --> C[Write]
        C --> D[Execute]
        D --> E[Admin]
    end

    A -.->|Can| A1[Read files<br/>Run checks<br/>View status]
    B -.->|Can| B1[+ Stage changes<br/>+ Generate artifacts]
    C -.->|Can| C1[+ Write files<br/>+ Modify state]
    D -.->|Can| D1[+ Run tools<br/>+ External calls]
    E -.->|Can| E1[+ Config changes<br/>+ Full control]

    style A fill:#95a5a6,color:#fff
    style B fill:#3498db,color:#fff
    style C fill:#f39c12,color:#000
    style D fill:#e67e22,color:#fff
    style E fill:#e74c3c,color:#fff

Permission Matrix:

5.3 Safety Checks

flowchart TD
    A[Agent Output] --> B{Schema Valid?}
    B -->|No| C[Reject]
    B -->|Yes| D{Contains Secrets?}

    D -->|Yes| E[Warn & Redact]
    D -->|No| F{File Size OK?}

    F -->|No| G[Reject: Too Large]
    F -->|Yes| H{Path Safe?}

    H -->|No| I[Reject: Path Traversal]
    H -->|Yes| J{Overwrites Exist?}

    J -->|Yes| K[Require Explicit Approval]
    J -->|No| L{Destructive?}

    L -->|Yes| M[Warn User]
    L -->|No| N[Stage Changes]

    K --> O{Approved?}
    O -->|Yes| N
    O -->|No| C

    M --> N
    N --> P[Apply]

    style C fill:#e74c3c,color:#fff
    style G fill:#e74c3c,color:#fff
    style I fill:#e74c3c,color:#fff
    style P fill:#27ae60,color:#fff

6. Technology Stack

6.1 Implementation Stack (v0.1)

Backend: Python — The hardware tool ecosystem (FreeCAD, KiCad IPC, OpenFOAM, CalculiX, ngspice) has Python-native APIs. FastAPI provides OpenAPI generation, async support, and type safety via Pydantic.

Frontend: TypeScript — Dashboard (React), VS Code extension, and CLI remain TypeScript.

graph TB
    subgraph "Frontend (TypeScript)"
        A1[CLI - TypeScript]
        A2[Dashboard - React]
        A3[VS Code Extension]
    end

    subgraph "Backend (Python)"
        B1[Gateway - FastAPI]
        B2[Pydantic Validation]
        B3[Async Python]
    end

    subgraph "Agent Runtime (Python)"
        C1[Pydantic AI Framework]
        C2[MCP Tool Connections]
        C3[Temporal Activities]
        C4[openai + anthropic SDKs]
    end

    subgraph "Storage"
        D1[Neo4j - Graph DB]
        D2[MinIO - Object Store]
        D3[Kafka - Event Bus]
        D4[Git]
        D5["pgvector - Knowledge Store"]
    end

    subgraph "Observability"
        O1[OpenTelemetry SDK]
        O2[OTel Collector]
        O3[Prometheus - Metrics]
        O4[Grafana Tempo - Traces]
        O5[Grafana Loki - Logs]
        O6[Grafana - Dashboards]
    end

    subgraph "External Tools"
        E1[KiCad Python API]
        E2[ngspice]
        E3[FreeCAD / CalculiX]
        E4[Supplier REST APIs]
    end

    A1 --> B1
    A2 --> B1
    B1 --> C3
    C3 --> C2
    C2 --> C4
    C3 --> B2
    B1 --> D1
    B1 --> D2
    B1 --> D3
    B1 --> D4
    B1 --> D5
    B1 --> O1
    C1 --> O1
    O1 --> O2
    O2 --> O3
    O2 --> O4
    O2 --> O5
    O3 --> O6
    O4 --> O6
    O5 --> O6
    C1 --> E1
    C1 --> E2
    C1 --> E3
    C1 --> E4

    style B1 fill:#2C3E50,color:#fff
    style C1 fill:#9b59b6,color:#fff
    style C2 fill:#3498db,color:#fff
    style D1 fill:#27ae60,color:#fff
    style O1 fill:#E67E22,color:#fff
    style O6 fill:#27ae60,color:#fff

Phase 1 implements the Digital Thread foundation (L1). See Digital Twin Evolution for the full roadmap through L2-L4.

6.2 Dependencies

CLI (TypeScript):

• commander — CLI framework
• inquirer — Interactive prompts
• chalk — Terminal colors
• axios — HTTP client

Gateway (Python):

• fastapi — Async HTTP framework with OpenAPI
• uvicorn — ASGI server
• pydantic — Schema validation and serialization
• structlog — Structured logging
• websockets — WebSocket support
• opentelemetry-sdk — Distributed tracing and metrics instrumentation
• opentelemetry-instrumentation-fastapi — Auto-instrumentation for FastAPI request tracing

Agents (Python — Pydantic AI framework + Temporal, see ADR-001):

• pydantic-ai — Agent framework: typed agent definitions, MCP connections, structured output validation
• temporalio — Durable execution: long-running workflows, crash recovery, approval gates
• openai — OpenAI API client (used by Pydantic AI as LLM provider)
• anthropic — Anthropic API client (used by Pydantic AI as LLM provider)
• pydantic — Domain model validation (shared with Pydantic AI)

Tool Adapters (registered via ToolRegistry, available to agents):

EDA Tools:

• KiCadAdapter — Schematic/PCB: ERC, DRC, BOM export, Gerber export, netlist export, pin mapping (Phase 1 read-only; Phase 2 adds schematic generation, PCB auto-routing)
• AltiumAdapter — Enterprise EDA: design rule checks, variant management, release management (Phase 2)
• EagleAdapter — Legacy EDA support (Phase 2)

Simulation Tools:

• NGSpiceAdapter — Circuit simulation: DC operating point, AC frequency response, transient analysis (Phase 1)
• LTspiceAdapter — SPICE simulation alternative (Phase 2)
• CalculiXAdapter — Open-source FEA solver: static stress, modal, thermal analysis via Abaqus-compatible .inp files (Phase 2, ME Agent)
• OpenFOAMAdapter — Open-source CFD: thermal/flow simulation via buoyantSimpleFoam, snappyHexMesh meshing (Phase 2, ME Agent)
• AnsysFEAAdapter — Finite element analysis: static stress, modal, thermal, vibration (Phase 2, SIM/ROB/REL Agents)

Supply Chain APIs:

• DigiKeyAdapter — Part search, real-time pricing, stock levels, lifecycle status, lead times, RoHS compliance (Phase 1)
• MouserAdapter — Part search, pricing, stock, on-order quantities, dual-sourcing (Phase 1)
• NexarAdapter — Octopart GraphQL API: aggregated part data, lifecycle tracking, cross-distributor pricing, alternates (Phase 1)
• LCSCAdapter — Low-cost component sourcing, JLCPCB parts integration (Phase 2)

CAD Tools:

• FreeCADAdapter — Open-source parametric CAD via headless freecadcmd: STEP/STL export, mesh generation, boolean operations, Python scripting API (Phase 2, ME Agent)
• SolidWorksAdapter — Mechanical CAD via COM API: STEP export, drawings, mechanical BOM, DFM checks (Phase 2, ID Agent)
• Fusion360Adapter — Cloud parametric CAD: model export, parametric updates, version control (Phase 2, ID Agent)

Lab Automation:

• SCPIAdapter — IVI/SCPI instrument control: oscilloscopes, spectrum analyzers, power supplies, multimeters (Phase 2)
• VISAAdapter — NI-VISA hardware abstraction: USB/GPIB/LAN instrument communication (Phase 2)
• OpenTAPAdapter — Automated test sequencing: test plans, measurement procedures, result capture (Phase 2)

Manufacturing:

• MacroFabAdapter — PCB fab/assembly: quoting, ordering, build tracking, yield reporting (Phase 2)
• JLCPCBAdapter — Low-cost PCB fabrication: design upload, quoting, order submission (Phase 2)

Firmware Toolchain:

• GCCToolchainAdapter — ARM cross-compilation, linking, symbol generation (Phase 1)
• CMakeAdapter — Build system configuration, incremental builds, dependency tracking (Phase 1)
• FlashToolAdapter — Firmware deployment via OpenOCD/pyOCD: flash programming, debug connection (Phase 2)

Data Layer:

• Neo4jAdapter — Digital thread graph database: requirement traceability, EOL risk detection, coverage analysis, impact queries (Phase 1)
• MinIOAdapter — S3-compatible object storage: CAD files, EDA projects, simulation results, test logs, Gerbers (Phase 1)
• pgvector (PostgreSQL extension) — Semantic knowledge store: design decision embeddings, session summaries, datasheet chunks, RAG retrieval for agent prompting (Phase 1.5). See AI Memory & Knowledge

CI/CD Integration:

• GitHubActionsAdapter — Webhook-based test result ingestion, artifact download, JUnit/pytest parsing, requirement-to-test linking (Phase 1)
• GitLabCIAdapter — Alternative CI/CD: pipeline events, build artifacts, test reports (Phase 2)

Utility Packages (Python):

• subprocess / asyncio.create_subprocess_exec — Safe subprocess execution for tool invocation
• pathlib / glob — File pattern matching and artifact discovery
• watchfiles — File system watching for design change detection. Powers the Assistant Mode ingest pipeline: detects human edits in KiCad/FreeCAD/VS Code and routes them through adapter parsers into the event stream
• paho-mqtt / aiomqtt — MQTT client for device telemetry (L3)

7. Design Principles & Patterns

7.1 Core Principles

mindmap
    root((MetaForge<br/>Principles))
        Local-First
            No cloud dependency
            Works offline
            Data sovereignty
        Git-Native
            Version all artifacts
            Diffs for review
            Commit history
        Transparent
            Traceable operations
            Audit logs
            Explainable decisions
        Safe
            Explicit approval
            No destructive actions
            Rollback capable
        Composable
            Skills as units
            Workflows as chains
            Extensible architecture

7.2 Architectural Patterns

1. Command Pattern (CLI)

interface Command {
  name: string;
  execute(args: Args): Promise<Result>;
}

2. Adapter Pattern (Tools)

interface ToolAdapter {
  detect(): Promise<boolean>;
  execute(action: Action): Promise<Result>;
}

3. Chain of Responsibility (Permissions)

interface PermissionHandler {
  next?: PermissionHandler;
  handle(request: Request): boolean;
}

4. Observer Pattern (Sessions)

interface SessionObserver {
  onStateChange(session: Session): void;
}

5. Strategy Pattern (Agents)

interface AgentStrategy {
  execute(context: Context): Promise<Artifacts>;
}

6. Pure Function Pattern (Skills)

Skills are deterministic, stateless capability modules invoked by agents. They produce structured outputs given the same inputs and must never have side effects.

class Skill(ABC):
    """Base class for all skills. Skills are pure — no side effects."""

    @abstractmethod
    async def execute(self, input: SkillInput) -> SkillOutput:
        """Pure execution: same input always produces same output."""
        ...

    # Skills must NEVER:
    # - Trigger another agent
    # - Emit events to the event bus
    # - Call MCP tools directly (agents do this via the MCP bridge)
    # - Persist state or write to any store
    # - Access the network or external services

Only agents orchestrate, decide, emit mutation proposals, and trigger artifact projection. Skills provide the analytical capabilities agents use to reason about engineering problems.

7. Projection Pattern (Visualization)

All UI surfaces — dashboard, 3D viewer, status panels — are read-only projections of the Digital Twin’s semantic state. The UI never computes domain logic; it subscribes to state changes and renders them.

8. Deployment Architecture

8.1 Local Deployment (v0.1)

graph TB
    subgraph "User Machine"
        A[Terminal] --> B[MetaForge CLI]
        B <--> C[Gateway Process]

        C --> D[.forge/ State]
        C --> E[Git Repo]
        C --> F[KiCad Install]
        C --> G[Text Editor]

        C <--> H[OpenAI API]
        C <--> I[Anthropic API]
    end

    style A fill:#E67E22,color:#fff
    style C fill:#2C3E50,color:#fff

8.2 Future: Team Deployment

graph TB
    subgraph "Client Machines"
        A1[User 1 CLI]
        A2[User 2 CLI]
        A3[User 3 CLI]
    end

    subgraph "Shared Server"
        B[Gateway Service]
        C[Redis Cache]
        D[PostgreSQL]
    end

    subgraph "Shared Storage"
        E[Git Remote]
        F[Artifact Store]
    end

    A1 <--> B
    A2 <--> B
    A3 <--> B

    B --> C
    B --> D
    B <--> E
    B <--> F

    style B fill:#2C3E50,color:#fff

9. Scalability Considerations

9.1 Performance Targets (v0.1)

9.2 Resource Limits

10. Future Enhancements

10.1 Planned Features

timeline
    title MetaForge Roadmap
    section v0.2
        Gateway HTTP : Requirements Agent : KiCad Read
    section v0.3
        Architecture Agent : Power Agent : BOM Agent
    section v0.4
        Schematic Agent : DFM Agent : Supplier Integration
    section v0.5
        Firmware Scaffolding : Bring-up Agent : Reality Feedback
    section v1.0
        Multi-user : Cloud Sync : Advanced Agents

10.2 Extension Points

1. Custom Agents: Plugin system for domain-specific agents
2. Tool Adapters: Support for additional EDA tools
3. LLM Providers: Pluggable LLM backends
4. Storage Backends: Database options for scale
5. Web UI: Optional web interface for teams

Appendix: Key Data Structures

Session Metadata

interface Session {
  id: string;
  skill: string;
  status: SessionStatus;
  created: Date;
  updated: Date;
  input: {
    files: string[];
    args: Record<string, any>;
  };
  output: {
    artifacts: Artifact[];
    errors: Error[];
  };
  traces: Trace[];
}

Trace Entry

interface Trace {
  timestamp: Date;
  session_id: string;
  agent: string;
  action: string;
  data: any;
  level: 'debug' | 'info' | 'warn' | 'error';
}

Artifact

interface Artifact {
  path: string;
  type: 'file' | 'directory';
  content?: string;
  hash: string;
  size: number;
  created: Date;
}

Related Architecture Documentation

Platform Vision & Structure

Digital Twin Architecture

Testing & Quality

Architecture Decision Records (ADRs)

Advanced Topics

Agent Specifications

Research & Framework

Document Version: v0.5 Last Updated: 2026-03-07 Status: Internal Architecture Documentation

← Home • Quick Start →