Repository Structure

Production-ready, scalable, and modular layout for the MetaForge platform

Overview
Full Repository Layout
Directory Responsibilities
Skill Directory Convention
1. definition.json Example
Tool Adapter Convention
Related Documents

Overview

The MetaForge platform repository follows a modular monorepo structure. Each top-level directory maps to an architectural layer, enabling independent development, testing, and deployment.

Full Repository Layout

hardware-ai-platform/
│
├── docs/
│   ├── architecture.md
│   ├── twin_schema.md
│   ├── skill_spec.md
│   ├── mcp_spec.md
│   ├── governance.md
│   └── roadmap.md
│
├── digital_twin/
│   ├── thread/                    # L1: Digital Thread (P1)
│   │   ├── models/
│   │   │   ├── artifact.py
│   │   │   ├── constraint.py
│   │   │   ├── relationship.py
│   │   │   └── version.py
│   │   ├── graph_engine.py
│   │   ├── versioning/
│   │   │   ├── branch.py
│   │   │   ├── merge.py
│   │   │   └── diff.py
│   │   ├── constraint_engine/
│   │   │   ├── engine.py
│   │   │   ├── registry.py
│   │   │   ├── evaluators/
│   │   │   │   ├── arithmetic.py
│   │   │   │   ├── coverage.py
│   │   │   │   └── existence.py
│   │   │   └── rules/
│   │   │       ├── electrical.yaml
│   │   │       ├── mechanical.yaml
│   │   │       ├── firmware.yaml
│   │   │       └── cross_domain.yaml
│   │   ├── validation_engine/
│   │   │   ├── schema_validator.py
│   │   │   └── schemas/
│   │   └── api.py
│   ├── models/                    # Twin Model definitions (P2)
│   │   ├── twin_model.py
│   │   ├── behavioral_model.py
│   │   └── model_registry.py
│   ├── sync/                      # L3: Device synchronization (P3)
│   │   ├── mqtt_adapter.py
│   │   ├── telemetry_router.py
│   │   ├── state_aggregator.py
│   │   ├── sync_policy.py
│   │   └── device_registry.py
│   ├── simulation/                # L4: Behavioral simulation (P3-P4)
│   │   ├── engine.py
│   │   ├── model_runner.py
│   │   ├── what_if.py
│   │   ├── calibration.py
│   │   └── models/
│   │       ├── differential_eq.py
│   │       ├── transfer_function.py
│   │       ├── thermal_rc.py
│   │       └── lookup_table.py
│   ├── knowledge/                 # Knowledge Layer: AI memory (P1.5)
│   │   ├── store.py               # pgvector CRUD + semantic search
│   │   ├── embedding_service.py   # Local + cloud embedding abstraction
│   │   ├── consumer.py            # Kafka event processor (KnowledgeConsumer)
│   │   ├── reconciler.py          # Periodic reconciliation (Neo4j ↔ pgvector)
│   │   ├── chunker.py             # Document chunking (PDF/markdown)
│   │   ├── templates.py           # Embedding content templates per knowledge type
│   │   ├── models.py              # Pydantic models
│   │   └── api.py                 # Knowledge query REST API
│   └── events.py                  # Shared event schemas (all layers)
│
├── orchestrator/
│   ├── event_bus/
│   │   ├── bus.py
│   │   ├── events.py
│   │   └── subscribers.py
│   ├── dependency_engine.py
│   ├── workflow_dag.py
│   ├── iteration_controller.py
│   └── scheduler.py
│
├── skill_registry/
│   ├── registry.py
│   ├── loader.py
│   ├── schema_validator.py
│   ├── skill_base.py
│   └── mcp_bridge.py
│
├── domain_agents/
│   ├── shared/                    # Cross-agent shared skills (P1.5)
│   │   └── skills/
│   │       ├── retrieve_knowledge/  # Semantic search over project knowledge
│   │       │   ├── definition.json
│   │       │   ├── SKILL.md
│   │       │   ├── schema.py
│   │       │   ├── handler.py
│   │       │   └── tests.py
│   │       └── ingest_knowledge/    # Document ingestion into knowledge layer
│   │           ├── definition.json
│   │           ├── SKILL.md
│   │           ├── schema.py
│   │           ├── handler.py
│   │           └── tests.py
│   ├── mechanical/
│   │   ├── agent.py
│   │   ├── adapters/
│   │   └── skills/
│   │       ├── validate_stress/
│   │       │   ├── definition.json
│   │       │   ├── SKILL.md
│   │       │   ├── schema.py
│   │       │   ├── handler.py
│   │       │   └── tests.py
│   │       ├── generate_mesh/
│   │       └── check_tolerance/
│   │
│   ├── electronics/
│   │   ├── agent.py
│   │   ├── adapters/
│   │   └── skills/
│   │       ├── run_erc/
│   │       ├── run_drc/
│   │       └── check_power_budget/
│   │
│   ├── firmware/
│   │   ├── agent.py
│   │   ├── adapters/
│   │   └── skills/
│   │       ├── generate_hal/
│   │       ├── scaffold_driver/
│   │       └── configure_rtos/
│   │
│   └── simulation/
│       ├── agent.py
│       ├── adapters/
│       └── skills/
│           ├── run_spice/
│           ├── run_fea/
│           └── run_cfd/
│
├── mcp_core/
│   ├── client.py
│   ├── protocol.py
│   └── schemas.py
│
├── tool_registry/
│   ├── registry.py
│   ├── execution_engine.py
│   ├── tool_metadata.py
│   ├── mcp_server/
│   │   ├── server.py
│   │   └── handlers.py
│   └── tools/
│       ├── calculix/
│       │   ├── adapter.py
│       │   ├── config.py
│       │   └── tests.py
│       ├── freecad/
│       │   ├── adapter.py
│       │   ├── config.py
│       │   └── tests.py
│       ├── kicad/
│       │   ├── adapter.py
│       │   ├── config.py
│       │   └── tests.py
│       └── spice/
│           ├── adapter.py
│           ├── config.py
│           └── tests.py
│
├── ide_assistants/
│   ├── cad_extension/
│   │   ├── freecad_plugin/
│   │   └── solidworks_addin/
│   ├── pcb_extension/
│   │   └── kicad_plugin/
│   ├── vscode_extension/
│   │   ├── src/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── simulation_assistant/
│       └── ui/
│
├── api_gateway/
│   ├── routes/
│   ├── middleware/
│   ├── auth/
│   └── server.py
│
├── cli/
│   ├── commands/
│   ├── config.py
│   └── main.py
│
├── ui/
│   ├── dashboard/
│   ├── components/
│   └── pages/
│
├── observability/
│   ├── bootstrap.py              # OTel SDK initialization
│   ├── logging.py                # structlog → OTel logging bridge
│   ├── tracing.py                # Custom span helpers
│   ├── metrics.py                # Prometheus metric definitions
│   ├── middleware.py              # FastAPI middleware
│   ├── config.py                 # ObservabilityConfig Pydantic model
│   ├── slo/
│   │   ├── definitions.py        # SLO/SLI definitions as code
│   │   └── calculator.py         # Error budget calculation
│   ├── alerting/
│   │   ├── rules.yaml            # Prometheus alerting rules
│   │   └── routes.yaml           # Alertmanager notification routing
│   └── dashboards/
│       ├── system-overview.json   # Grafana: system health
│       ├── agent-performance.json # Grafana: agent metrics
│       ├── data-stores.json       # Grafana: Neo4j/Kafka/pgvector
│       └── slo-overview.json      # Grafana: SLO tracking
│
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
│
├── examples/
│   ├── drone_flight_controller/
│   ├── iot_sensor/
│   └── robot_cell/
│
├── LICENSE
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
└── GOVERNANCE.md

Directory Responsibilities

`digital_twin/` — Digital Twin

The single source of truth for all design state, structured as layered subdirectories that mirror the Digital Twin Evolution architecture.

Directory	Layer	Purpose
`thread/`	L1 (P1)	Digital Thread: artifact graph, versioning, constraint engine, validation
`thread/models/`	L1	Data models for artifacts, constraints, relationships, versions
`thread/graph_engine.py`	L1	Core graph operations (create, query, traverse)
`thread/versioning/`	L1	Branch, merge, and diff operations on design state
`thread/constraint_engine/`	L1	Cross-domain engineering constraint evaluation (YAML rules, Cypher queries)
`thread/validation_engine/`	L1	Schema validation for all artifact types
`thread/api.py`	L1	Public API for twin operations
`models/`	L2 (P2)	Twin Model definitions: product schemas, behavioral models, model registry
`sync/`	L3 (P3)	Device synchronization: MQTT adapter, telemetry routing, state aggregation
`simulation/`	L4 (P3-P4)	Behavioral simulation: model execution, what-if analysis, calibration
`knowledge/`	All (P1.5)	Knowledge Layer: pgvector store, embedding service, Kafka consumer, document chunker, REST API
`events.py`	All	Shared event schemas (GraphEvent, TelemetryEvent) used across all layers

`orchestrator/` — Workflow Coordination

Manages multi-agent execution and design iteration.

Directory	Purpose
`event_bus/`	Publish/subscribe for design change events
`dependency_engine.py`	Inter-agent and inter-skill dependency resolution
`workflow_dag.py`	DAG definition and execution for complex workflows
`iteration_controller.py`	Propose-validate-refine loop management
`scheduler.py`	Agent execution queuing and prioritization

Agent execution uses Pydantic AI for typed agent definitions and MCP tool connections, with Temporal for durable workflow coordination. See ADR-001: Agent Orchestration for the full architecture decision.

`skill_registry/` — Skill Management

Central catalog and loader for all domain skills.

File	Purpose
`registry.py`	Skill catalog with discovery and lookup
`loader.py`	Dynamic skill loading from definition files
`schema_validator.py`	Input/output schema validation
`skill_base.py`	Abstract base class all skills extend
`mcp_bridge.py`	Translates skill tool calls to MCP protocol

`domain_agents/` — Engineering Agents

The shared/skills/ directory contains cross-agent skills available to all domain agents:

Skill	Phase	Purpose
`retrieve_knowledge`	P1.5	Semantic search over project knowledge via pgvector
`ingest_knowledge`	P2.5	Document ingestion (datasheets, app notes) into the knowledge layer

See AI Memory & Knowledge for full skill specifications.

Each agent directory follows a consistent structure:

domain_agents/<domain>/
├── agent.py              # Pydantic AI agent definition (Agent, deps_type, output_type, mcp_servers)
├── adapters/             # Domain-specific adapters
└── skills/
    └── <skill_name>/
        ├── definition.json   # Skill metadata and configuration
        ├── SKILL.md          # Human-readable skill documentation
        ├── schema.py         # Zod-equivalent input/output schemas
        ├── handler.py        # Skill execution logic
        └── tests.py          # Skill-specific tests

`mcp_core/` — MCP Protocol

Model Context Protocol client and schema definitions.

File	Purpose
`client.py`	MCP client for tool communication
`protocol.py`	Wire protocol implementation
`schemas.py`	MCP message schemas

`tool_registry/` — Tool Integration

MCP-based tool access layer with containerized execution.

Directory	Purpose
`registry.py`	Available tool catalog with capabilities
`execution_engine.py`	Tool invocation, timeout, retry logic
`tool_metadata.py`	Tool version, platform, capability metadata
`mcp_server/`	MCP server implementation for tool adapters
`tools/`	Individual tool adapter implementations

`observability/` — System Observability

Unified logging, metrics, and distributed tracing infrastructure. See System Observability for the full architecture.

Directory	Purpose
`bootstrap.py`	OpenTelemetry SDK initialization (TracerProvider, MeterProvider, LoggerProvider)
`logging.py`	structlog processor that injects `trace_id`/`span_id` into every log line
`tracing.py`	Custom span helpers for agent, skill, tool, and data store instrumentation
`metrics.py`	All Prometheus metric definitions (~30 metrics across subsystems)
`middleware.py`	FastAPI middleware for automatic request tracing and metrics
`config.py`	`ObservabilityConfig` Pydantic model for centralized configuration
`slo/`	SLO/SLI definitions as code with error budget calculators
`alerting/`	Prometheus alerting rules and Alertmanager notification routing
`dashboards/`	Grafana dashboard JSON definitions (system, agent, data store, SLO)

`ide_assistants/` — Human Interface

IDE-embedded assistants for each engineering domain.

Directory	Purpose
`cad_extension/`	FreeCAD plugin, SolidWorks add-in
`pcb_extension/`	KiCad plugin for PCB assistance
`vscode_extension/`	VS Code extension for firmware development
`simulation_assistant/`	Standalone simulation setup and analysis UI

Skill Directory Convention

Every skill follows a strict structure to enable auto-discovery:

skills/<skill_name>/
├── definition.json    # Machine-readable metadata
├── SKILL.md           # Human-readable documentation
├── schema.py          # Input/output schemas (Zod-style)
├── handler.py         # Execution logic
└── tests.py           # Unit + integration tests

`definition.json` Example

{
  "name": "validate_stress",
  "version": "1.0.0",
  "domain": "mechanical",
  "description": "Run FEA stress analysis on a CAD model",
  "tools_required": ["calculix"],
  "input_schema": "schema.ValidateStressInput",
  "output_schema": "schema.ValidateStressOutput",
  "timeout_seconds": 300,
  "idempotent": true
}

Tool Adapter Convention

Each tool adapter in tool_registry/tools/ follows:

tools/<tool_name>/
├── adapter.py     # ToolAdapter implementation
├── config.py      # Default configuration
└── tests.py       # Adapter tests (unit + mock)

Adapters must:

Implement the ToolAdapter interface
Provide MCP schema definitions
Be containerizable (Docker)
Pass integration tests

Document	Description
System Vision	Architectural principles and layer overview
Architecture Overview	Detailed component interactions
Digital Twin Evolution	Full twin architecture matching the `digital_twin/` directory structure
Graph Schema	Node types and relationships implemented in the thread layer
Constraint Engine	Engineering constraints in `thread/constraint_engine/`
AI Memory & Knowledge	Knowledge Layer in `digital_twin/knowledge/` and shared skills in `domain_agents/shared/skills/`
System Observability	Observability infrastructure in `observability/` — OTel SDK, metrics, tracing, alerting, dashboards
Execution Roadmap	When each component gets built
Governance	Contribution rules for each directory

Document Version: v1.1 Last Updated: 2026-02-28

← System Vision

Architecture Overview →

Repository Structure

Table of Contents

Overview

Full Repository Layout

Directory Responsibilities

digital_twin/ — Digital Twin

orchestrator/ — Workflow Coordination

skill_registry/ — Skill Management

domain_agents/ — Engineering Agents

mcp_core/ — MCP Protocol

tool_registry/ — Tool Integration

observability/ — System Observability

ide_assistants/ — Human Interface