# pvmodayil/agentic-pcb-design-assistant architecture

> Architecture diagram of the GitHub repository pvmodayil/agentic-pcb-design-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pvmodayil/agentic-pcb-design-assistant
- Repository: https://github.com/pvmodayil/agentic-pcb-design-assistant

## Overview

This repository implements a Python-based, agentic PCB design automation system centered on a deterministic, checkpointed workflow rather than a free-form chat application.

#### High-level shape

The architecture is split into four main layers:

1. **Entry / orchestration layer**
   - `src/main.py`
   - `src/orchestrator/`
   - `src/protocols/input_protocol.py`

2. **Agent core**
   - `src/core/`
   - `src/agents/`

3. **Tool execution layer**
   - `src/tools/`
   - `src/infrastructure/`
   - MCP integration via `src/core/mcp_server_builder.py`

4. **Configuration and artifacts**
   - `config/`
   - `src/models/`
   - `outputs/`

The system is built around a PCB-specific agent framework, with the concrete domain example in this repo being a **coupled microstrip design agent**.

---

#### Main subsystems

##### 1) Application entry and orchestration
`src/main.py` is the runtime entry point. It likely loads configuration, constructs the agent stack, and starts the workflow. The `src/orchestrator/` package suggests there is a coordination boundary between:

- user input / task request
- agent state initialization
- repeated tool-usage / reasoning cycles
- checkpoint updates
- final result emission

The `protocols/input_protocol.py` file implies the system expects structured input contracts rather than arbitrary text blobs. This is an important diagram boundary: **input normalization happens before agent execution**.

##### 2) Core agent framework
The `src/core/` package contains the reusable framework pieces that all domain agents depend on:

- `pcb_agent.py`: abstract base agent with workflow control
- `data_models.py`: Pydantic models for checkpoints, actions, results, and state
- `memory_manager.py`: conversation / context retention and summarization
- `message_builder.py`: prompt/message assembly
- `llm_model.py`: LLM integration and model configuration
- `settings.py`: configuration loading
- `tool_registry.py`: centralized tool registration and invocation
- `mcp_server_builder.py`: wrapper for connecting to MCP tools

This layer is the **control plane** of the system. It manages state, checkpoints, and tool selection, while staying independent of any one PCB task.

##### 3) Domain-specific agents
`src/agents/coupled_microstrip_agent.py` is the concrete agent implementation in the repository. It appears to specialize the generic PCB agent framework for a coupled microstrip design workflow.

This specialization likely binds:
- domain-specific checkpoints
- the correct tool set
- domain prompts / reasoning constraints
- domain result formatting

So in a diagram, this should be shown as a **concrete agent instance built on top of the generic PCB agent base**.

##### 4) Tooling and computation layer
The `src/tools/` package contains the actual computational capabilities exposed to the agent:

- `bem_field_solver_simulator.py`
- `coupled_microstrip_parameter_optimizer_tool.py`

These tools are likely invoked by the agent through the tool registry, and they represent the main computational boundary of the system.

The repository also includes:
- `src/models/coupled_microstrip_impedance_predictor_ann.onnx`

That ONNX model is an embedded local ML artifact and should be drawn as a **local inference dependency** used by the microstrip-related tooling or prediction pipeline.

##### 5) External tool integration via MCP
The README states the system integrates with external tools via MCP servers, both local and remote. The code structure supports that through:

- `src/core/mcp_server_builder.py`
- `config/tool_config/*.yaml`

This indicates the agent can call:
- **local stdio-based MCP servers**
- **remote SSE/HTTP-based MCP servers**

This is a key architectural boundary: the core agent does not directly depend on every external tool implementation. Instead, it accesses them through an MCP abstraction.

##### 6) State, memory, and checkpointing
A major design feature is checkpoint-based workflow management. The relevant pieces are:

- `src/core/data_models.py`
- `src/core/memory_manager.py`
- `docs/adr/checkpointing.md`

This means the workflow is not a single linear run. It is a **stateful process** with:
- pending checkpoints
- validation of progress
- accumulated intermediate results
- recovery / continuation support

In a diagram, this is the main persistence/state boundary.

---

#### Primary data flow

A typical execution path looks like this:

1. **Configuration load**
   - YAML under `config/` defines agent behavior, LLM settings, and tool wiring.

2. **Request intake**
   - Structured input arrives via the input protocol and is passed into the orchestrator / main entry point.

3. **Agent construction**
   - The system builds a concrete agent, such as the coupled microstrip agent, using the core PCB agent base and the selected tool set.

4. **State initialization**
   - Checkpoints, memory, and run state are initialized from the core data models.

5. **Reasoning and tool selection**
   - The LLM-backed agent formulates actions using prompt/message construction and memory context.

6. **Tool execution**
   - The tool registry dispatches to local tools or MCP-connected external tools.
   - Some tools may use the ONNX model or simulator/optimizer components.

7. **Checkpoint update**
   - Results are validated and written back into the checkpoint/state model.
   - The memory manager may summarize older context to keep the workflow bounded.

8. **Final output**
   - Completed results are stored or emitted, with outputs likely landing under `outputs/`.

---

#### Important architectural boundaries

##### Control plane vs execution plane
- **Control plane**: `core/`, `orchestrator/`, checkpoint models, memory, prompt/message construction.
- **Execution plane**: `tools/`, MCP-connected services, ONNX model inference, simulators, optimizers.

This is one of the most important boundaries in the repo.

##### Generic framework vs domain specialization
- Generic reusable agent machinery lives in `src/core/`.
- Concrete PCB tasks live in `src/agents/` and `src/tools/`.

This separation makes it possible to add new PCB agents without rewriting the workflow engine.

##### Internal tools vs external services
- Internal tools are implemented directly in Python under `src/tools/`.
- External capabilities are wrapped via MCP in `mcp_server_builder.py`.

This keeps the agent’s tool API stable even if the underlying service is local or remote.

##### Short-term context vs long-running state
- Short-term context is handled by the memory manager.
- Long-running progress is represented by checkpoints and data models.

This distinction is central to how the workflow survives multi-step design tasks.

---

#### Configuration and runtime assets

The `config/` directory is significant to the architecture:

- `config/llm_config.yaml` — LLM/model selection and settings
- `config/agent_config/coupled_microstrip_agent.yaml` — domain agent setup
- `config/tool_config/bem_field_solver_simulator.yaml`
- `config/tool_config/coupled_microstrip_parameter_optimizer.yaml`

These files suggest the system is designed to be **configuration-driven**, where agent behavior and tool exposure can be changed without code changes.

The `outputs/` directory is the likely sink for generated artifacts, reports, intermediate results, or simulation outputs.

---

#### What to draw in an architecture diagram

If you are diagramming this repo, the most accurate top-level picture is:

- A **Python application entry point**
- Feeding an **orchestrator**
- Which constructs a **PCB agent framework instance**
- That agent uses:
  - **LLM integration**
  - **memory and checkpoint state**
  - **tool registry**
  - **MCP connectors**
- Tools then call:
  - **local simulators/optimizers**
  - **remote MCP services**
  - **embedded ONNX inference**
- Results flow back through checkpoints and memory into final outputs

---

#### Notable repo-specific observations

- The README describes the project as “agentic PCB design automation,” and the source tree confirms a **specific domain agent** for **coupled microstrip** work.
- The architecture emphasizes **deterministic workflow control** over autonomous free-form agent behavior.
- The presence of `docs/adr/checkpointing.md` indicates checkpointing is not incidental; it is a first-class architectural decision.
- The `config/` layout suggests the repo is intended to be reconfigured for different agents/tools, even though the included implementation is centered on one PCB domain.

Main entry points: [`src/core/pcb_agent.py`](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/pcb_agent.py) (PCB agent), [`src/orchestrator`](https://github.com/pvmodayil/agentic-pcb-design-assistant/tree/HEAD/src/orchestrator) (Orchestrator), [`src/core/tool_registry.py`](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/tool_registry.py) (Tool registry), [`src/agents/coupled_microstrip_agent.py`](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/agents/coupled_microstrip_agent.py) (Coupled agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Entry & orchestration"
  node_main["Main<br/>python entrypoint<br/>[main.py]"]
  node_orchestrator["Orchestrator<br/>workflow coordinator"]
  node_input_protocol["Input protocol<br/>request contract<br/>[input_protocol.py]"]
end

subgraph "Agent core"
  node_pcb_agent["PCB agent<br/>agent base<br/>[pcb_agent.py]"]
  node_data_models["State models<br/>pydantic models<br/>[data_models.py]"]
  node_memory_manager["Memory<br/>context manager<br/>[memory_manager.py]"]
  node_message_builder["Prompt builder<br/>message assembly<br/>[message_builder.py]"]
  node_llm_model["LLM model<br/>model adapter<br/>[llm_model.py]"]
  node_tool_registry["Tool registry<br/>tool dispatcher<br/>[tool_registry.py]"]
  node_mcp_builder["MCP bridge<br/>integration builder"]
  node_coupled_agent["Coupled agent<br/>domain agent"]
end

subgraph "Execution layer"
  node_bem_tool["BEM solver<br/>simulation tool"]
  node_optimizer_tool["Optimizer<br/>design tool"]
  node_onnx_model(("ANN model<br/>ml artifact"))
end

subgraph "Config & artifacts"
  node_agent_config["Agent config<br/>yaml config"]
  node_llm_config["LLM config<br/>yaml config<br/>[llm_config.yaml]"]
  node_tool_configs["Tool configs<br/>yaml config set"]
  node_outputs[("Outputs<br/>artifact sink")]
end

node_main -->|"starts"| node_orchestrator
node_main -->|"loads"| node_llm_config
node_orchestrator -->|"normalizes"| node_input_protocol
node_orchestrator -->|"constructs"| node_coupled_agent
node_coupled_agent -->|"extends"| node_pcb_agent
node_coupled_agent -->|"uses"| node_agent_config
node_coupled_agent -->|"invokes"| node_tool_registry
node_pcb_agent -->|"tracks"| node_data_models
node_pcb_agent -->|"updates"| node_memory_manager
node_pcb_agent -->|"builds"| node_message_builder
node_pcb_agent -->|"queries"| node_llm_model
node_tool_registry -->|"dispatches"| node_bem_tool
node_tool_registry -->|"dispatches"| node_optimizer_tool
node_tool_registry -->|"bridges"| node_mcp_builder
node_mcp_builder -->|"loads"| node_tool_configs
node_bem_tool -->|"uses"| node_onnx_model
node_optimizer_tool -->|"uses"| node_onnx_model
node_data_models -->|"persists"| node_outputs
node_orchestrator -->|"emits"| node_outputs

click node_main "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/main.py"
click node_orchestrator "https://github.com/pvmodayil/agentic-pcb-design-assistant/tree/main/src/orchestrator"
click node_input_protocol "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/protocols/input_protocol.py"
click node_pcb_agent "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/core/pcb_agent.py"
click node_data_models "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/core/data_models.py"
click node_memory_manager "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/core/memory_manager.py"
click node_message_builder "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/core/message_builder.py"
click node_llm_model "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/core/llm_model.py"
click node_tool_registry "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/core/tool_registry.py"
click node_mcp_builder "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/core/mcp_server_builder.py"
click node_coupled_agent "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/agents/coupled_microstrip_agent.py"
click node_bem_tool "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/tools/bem_field_solver_simulator.py"
click node_optimizer_tool "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/tools/coupled_microstrip_parameter_optimizer_tool.py"
click node_onnx_model "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/src/models/coupled_microstrip_impedance_predictor_ann.onnx"
click node_agent_config "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/config/agent_config/coupled_microstrip_agent.yaml"
click node_llm_config "https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/main/config/llm_config.yaml"
click node_tool_configs "https://github.com/pvmodayil/agentic-pcb-design-assistant/tree/main/config/tool_config"
click node_outputs "https://github.com/pvmodayil/agentic-pcb-design-assistant/tree/main/outputs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_orchestrator,node_input_protocol toneBlue
class node_pcb_agent,node_data_models,node_memory_manager,node_message_builder,node_llm_model,node_tool_registry,node_mcp_builder,node_coupled_agent toneAmber
class node_bem_tool,node_optimizer_tool,node_onnx_model toneMint
class node_agent_config,node_llm_config,node_tool_configs,node_outputs toneRose
```

## Components

### Entry & orchestration

Runtime entry, request normalization, and workflow coordination.

- [Main](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/main.py): python entrypoint · Application startup and top-level runtime wiring. · `src/main.py`
- [Orchestrator](https://github.com/pvmodayil/agentic-pcb-design-assistant/tree/HEAD/src/orchestrator): workflow coordinator · Coordinates request intake, agent execution, and checkpointed run flow. · `src/orchestrator`
- [Input protocol](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/protocols/input_protocol.py): request contract · Structured input schema for incoming tasks. · `src/protocols/input_protocol.py`

### Agent core

Reusable PCB agent control plane: state, prompts, LLM, and tool dispatch.

- [PCB agent](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/pcb_agent.py): agent base · Abstract workflow engine for deterministic agent execution. · `src/core/pcb_agent.py`
- [State models](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/data_models.py): pydantic models · Checkpoints, actions, results, and run state definitions. · `src/core/data_models.py`
- [Memory](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/memory_manager.py): context manager · Context retention and summarization for long-running runs. · `src/core/memory_manager.py`
- [Prompt builder](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/message_builder.py): message assembly · Builds LLM-facing prompts and messages from state and context. · `src/core/message_builder.py`
- [LLM model](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/llm_model.py): model adapter · LLM integration and model configuration wrapper. · `src/core/llm_model.py`
- [Tool registry](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/tool_registry.py): tool dispatcher · Registers tools and routes agent actions to executors. · `src/core/tool_registry.py`
- [MCP bridge](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/core/mcp_server_builder.py): integration builder · Constructs connections to local and remote MCP tool servers. · `src/core/mcp_server_builder.py`
- [Coupled agent](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/agents/coupled_microstrip_agent.py): domain agent · Concrete PCB agent for coupled microstrip design workflows. · `src/agents/coupled_microstrip_agent.py`

### Execution layer

Domain computation tools, embedded models, and external tool connectivity.

- [BEM solver](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/tools/bem_field_solver_simulator.py): simulation tool · Field solver / simulator used by the agent for electromagnetic analysis. · `src/tools/bem_field_solver_simulator.py`
- [Optimizer](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/tools/coupled_microstrip_parameter_optimizer_tool.py): design tool · Parameter optimization tool for coupled microstrip design. · `src/tools/coupled_microstrip_parameter_optimizer_tool.py`
- [ANN model](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/src/models/coupled_microstrip_impedance_predictor_ann.onnx): ml artifact · Embedded impedance predictor used by the microstrip tooling pipeline. · `src/models/coupled_microstrip_impedance_predictor_ann.onnx`

### Config & artifacts

Configuration inputs and generated outputs.

- [Agent config](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/config/agent_config/coupled_microstrip_agent.yaml): yaml config · Domain agent configuration for coupled microstrip execution. · `config/agent_config/coupled_microstrip_agent.yaml`
- [LLM config](https://github.com/pvmodayil/agentic-pcb-design-assistant/blob/HEAD/config/llm_config.yaml): yaml config · Model selection and LLM runtime settings. · `config/llm_config.yaml`
- [Tool configs](https://github.com/pvmodayil/agentic-pcb-design-assistant/tree/HEAD/config/tool_config): yaml config set · Configuration for simulator and optimizer tool wiring. · `config/tool_config`
- [Outputs](https://github.com/pvmodayil/agentic-pcb-design-assistant/tree/HEAD/outputs): artifact sink · Generated reports, intermediate results, and final artifacts. · `outputs`

## Connections

- Main → Orchestrator: starts · Runtime entry hands off execution to orchestration.
- Main → LLM config: loads · Startup reads model/runtime configuration.
- Orchestrator → Input protocol: normalizes · Structured request input is validated before execution.
- Orchestrator → Coupled agent: constructs · Builds the concrete domain agent for the task.
- Coupled agent → PCB agent: extends · Domain agent specializes the reusable PCB workflow engine.
- Coupled agent → Agent config: uses · Domain behavior is driven by configuration.
- Coupled agent → Tool registry: invokes · Agent actions are dispatched through the registry.
- PCB agent → State models: tracks · Workflow state and checkpoints are represented by data models.
- PCB agent → Memory: updates · Agent maintains bounded conversational context.
- PCB agent → Prompt builder: builds · Prompt and message construction for each reasoning step.
- PCB agent → LLM model: queries · LLM-backed reasoning and action selection.
- Tool registry → BEM solver: dispatches · Registry routes calls to local simulation tooling.
- Tool registry → Optimizer: dispatches · Registry routes calls to optimization tooling.
- Tool registry → MCP bridge: bridges · Registry can connect to tools exposed over MCP.
- MCP bridge → Tool configs: loads · MCP connections are configured from tool YAML.
- BEM solver → ANN model: uses · Simulation/prediction pipeline may depend on local ML inference.
- Optimizer → ANN model: uses · Optimization can incorporate the embedded predictor.
- State models → Outputs: persists · Checkpointed results and final artifacts are written out.
- Orchestrator → Outputs: emits · Completed runs produce output artifacts.
