# abdisamad001/toposcribe-ai architecture

> Architecture diagram of the GitHub repository abdisamad001/toposcribe-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdisamad001/toposcribe-ai
- Repository: https://github.com/abdisamad001/toposcribe-ai

## Overview

TopoScribe AI turns a natural-language campus-network request into a planned topology, device configuration, validation result, and exportable design. The principal workflow runs from the design API through LangGraph’s planning, topology, configuration, and validation stages; users can clarify requirements and work with the resulting topology in the Next.js editor. Separate capabilities cover saved designs, projects, chats, reports, simulation, and optional Packet Tracer verification. Edges reflect excerpts, the source index, or README documentation; unsampled subsystem links are omitted where callers are not evidenced.

Main entry points: [`backend/app/graph/workflow.py`](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/graph/workflow.py) (Agent workflow), [`frontend/src/components/topology/TopologyEditor.tsx`](https://github.com/abdisamad001/toposcribe-ai/blob/main/frontend/src/components/topology/TopologyEditor.tsx) (Topology editor), [`backend/app/agents/planning_agent.py`](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/planning_agent.py) (Requirements planning), [`backend/app/agents/topology_agent.py`](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/topology_agent.py) (Topology generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Design workspace"]
  node_editor["Topology editor<br/>[TopologyEditor.tsx]"]
  node_config_ui["Configuration panel<br/>[ConfigPanel.tsx]"]
  node_pt_ui["Packet Tracer panel"]
end

subgraph group_generation["Design generation"]
  node_design_api["Design endpoint<br/>[design.py]"]
  node_workflow["Agent workflow<br/>[workflow.py]"]
  node_state["Design state<br/>[state.py]"]
  node_planning["Requirements planning<br/>[planning_agent.py]"]
  node_topology_agent["Topology generation<br/>[topology_agent.py]"]
  node_config_agent["Configuration generation<br/>[config_agent.py]"]
  node_validation["Configuration validation"]
  node_llm["LLM client<br/>[llm.py]"]
  node_planning_helpers["Planning helpers"]
end

subgraph group_network["Network outputs"]
  node_layout["Topology layout<br/>[topology_layout.py]"]
  node_config_builder["Config builder<br/>[config_builder.py]"]
  node_cisco["Cisco configuration<br/>[cisco.py]"]
  node_network_model["Network model<br/>[network.py]"]
end

subgraph group_persistence["Saved work"]
  node_database[("Design database<br/>[db.py]")]
  node_resource_apis["Projects, chats, reports"]
end

subgraph group_verification["Simulation and verification"]
  node_simulation_api["Reachability endpoint<br/>[simulate.py]"]
  node_simulation["Reachability simulation<br/>[reachability.py]"]
  node_packet_api["Packet Tracer endpoint<br/>[packettracer.py]"]
  node_pt_client["Packet Tracer client<br/>[client.py]"]
  node_pt_worker["Packet Tracer worker<br/>[mcp_worker.py]"]
end

node_user(("Network designer"))
node_pt_service{{"Packet Tracer bridge"}}

node_user -->|"describes network"| node_editor
node_editor -.->|"requests design"| node_design_api
node_design_api -->|"runs workflow"| node_workflow
node_workflow -->|"dispatches"| node_planning
node_workflow -->|"dispatches"| node_topology_agent
node_workflow -->|"dispatches"| node_config_agent
node_workflow -->|"dispatches"| node_validation
node_planning -->|"calls"| node_llm
node_planning -->|"uses"| node_planning_helpers
node_topology_agent -->|"calls"| node_llm
node_topology_agent -->|"uses"| node_layout
node_config_agent -->|"builds configuration"| node_config_builder
node_validation -->|"checks configuration"| node_cisco
node_workflow -->|"shares state"| node_state
node_state -->|"types topology"| node_network_model
node_layout -->|"produces topology"| node_network_model
node_editor -->|"renders"| node_config_ui
node_editor -->|"renders"| node_pt_ui
node_user -.->|"manages saved work"| node_resource_apis
node_resource_apis -->|"reads and writes"| node_database
node_simulation_api -->|"runs checks"| node_simulation
node_simulation_api -->|"accepts topology"| node_network_model
node_packet_api -->|"requests execution"| node_pt_client
node_pt_client -->|"launches worker"| node_pt_worker
node_pt_worker -->|"calls MCP tools"| node_pt_service
node_editor -.->|"starts verification"| node_pt_client

click node_editor "https://github.com/abdisamad001/toposcribe-ai/blob/main/frontend/src/components/topology/TopologyEditor.tsx"
click node_config_ui "https://github.com/abdisamad001/toposcribe-ai/blob/main/frontend/src/components/topology/ConfigPanel.tsx"
click node_pt_ui "https://github.com/abdisamad001/toposcribe-ai/blob/main/frontend/src/components/topology/PacketTracerPanel.tsx"
click node_design_api "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/api/design.py"
click node_workflow "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/graph/workflow.py"
click node_state "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/graph/state.py"
click node_planning "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/planning_agent.py"
click node_topology_agent "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/topology_agent.py"
click node_config_agent "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/config_agent.py"
click node_validation "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/validation_agent.py"
click node_llm "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/utils/llm.py"
click node_planning_helpers "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/utils/planning_helpers.py"
click node_layout "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/generators/topology_layout.py"
click node_config_builder "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/generators/config_builder.py"
click node_cisco "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/generators/cisco.py"
click node_network_model "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/models/network.py"
click node_database "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/db.py"
click node_resource_apis "https://github.com/abdisamad001/toposcribe-ai/tree/main/backend/app/api"
click node_simulation_api "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/api/simulate.py"
click node_simulation "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/simulation/reachability.py"
click node_packet_api "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/api/packettracer.py"
click node_pt_client "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/integrations/packettracer/client.py"
click node_pt_worker "https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/integrations/packettracer/mcp_worker.py"

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_editor,node_config_ui,node_pt_ui toneBlue
class node_design_api,node_workflow,node_state,node_planning,node_topology_agent,node_config_agent,node_validation,node_llm,node_planning_helpers toneAmber
class node_layout,node_config_builder,node_cisco,node_network_model toneMint
class node_database,node_resource_apis toneRose
class node_simulation_api,node_simulation,node_packet_api,node_pt_client,node_pt_worker,node_user,node_pt_service toneIndigo
```

## Components

### Design workspace

- [Topology editor](https://github.com/abdisamad001/toposcribe-ai/blob/main/frontend/src/components/topology/TopologyEditor.tsx): `frontend/src/components/topology/TopologyEditor.tsx`
- [Configuration panel](https://github.com/abdisamad001/toposcribe-ai/blob/main/frontend/src/components/topology/ConfigPanel.tsx): `frontend/src/components/topology/ConfigPanel.tsx`
- [Packet Tracer panel](https://github.com/abdisamad001/toposcribe-ai/blob/main/frontend/src/components/topology/PacketTracerPanel.tsx): `frontend/src/components/topology/PacketTracerPanel.tsx`

### Design generation

- [Design endpoint](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/api/design.py): `backend/app/api/design.py`
- [Agent workflow](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/graph/workflow.py): `backend/app/graph/workflow.py`
- [Design state](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/graph/state.py): `backend/app/graph/state.py`
- [Requirements planning](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/planning_agent.py): `backend/app/agents/planning_agent.py`
- [Topology generation](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/topology_agent.py): `backend/app/agents/topology_agent.py`
- [Configuration generation](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/config_agent.py): `backend/app/agents/config_agent.py`
- [Configuration validation](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/agents/validation_agent.py): `backend/app/agents/validation_agent.py`
- [LLM client](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/utils/llm.py): `backend/app/utils/llm.py`
- [Planning helpers](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/utils/planning_helpers.py): `backend/app/utils/planning_helpers.py`

### Network outputs

- [Topology layout](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/generators/topology_layout.py): `backend/app/generators/topology_layout.py`
- [Config builder](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/generators/config_builder.py): `backend/app/generators/config_builder.py`
- [Cisco configuration](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/generators/cisco.py): `backend/app/generators/cisco.py`
- [Network model](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/models/network.py): `backend/app/models/network.py`

### Saved work

- [Design database](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/db.py): `backend/app/db.py`
- [Projects, chats, reports](https://github.com/abdisamad001/toposcribe-ai/tree/main/backend/app/api): `backend/app/api`

### Simulation and verification

- [Reachability endpoint](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/api/simulate.py): `backend/app/api/simulate.py`
- [Reachability simulation](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/simulation/reachability.py): `backend/app/simulation/reachability.py`
- [Packet Tracer endpoint](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/api/packettracer.py): `backend/app/api/packettracer.py`
- [Packet Tracer client](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/integrations/packettracer/client.py): `backend/app/integrations/packettracer/client.py`
- [Packet Tracer worker](https://github.com/abdisamad001/toposcribe-ai/blob/main/backend/app/integrations/packettracer/mcp_worker.py): `backend/app/integrations/packettracer/mcp_worker.py`

### Other components

- **Network designer**
- **Packet Tracer bridge**

## Connections

- Network designer → Topology editor: describes network
- Topology editor → Design endpoint: requests design
- Design endpoint → Agent workflow: runs workflow (evidence: `backend/app/api/design.py`)
- Agent workflow → Requirements planning: dispatches (evidence: `backend/app/graph/workflow.py`)
- Agent workflow → Topology generation: dispatches (evidence: `backend/app/graph/workflow.py`)
- Agent workflow → Configuration generation: dispatches (evidence: `backend/app/graph/workflow.py`)
- Agent workflow → Configuration validation: dispatches (evidence: `backend/app/graph/workflow.py`)
- Requirements planning → LLM client: calls (evidence: `backend/app/agents/planning_agent.py`)
- Requirements planning → Planning helpers: uses (evidence: `backend/app/agents/planning_agent.py`)
- Topology generation → LLM client: calls (evidence: `backend/app/agents/topology_agent.py`)
- Topology generation → Topology layout: uses (evidence: `backend/app/agents/topology_agent.py`)
- Configuration generation → Config builder: builds configuration (evidence: `backend/app/agents/config_agent.py`)
- Configuration validation → Cisco configuration: checks configuration (evidence: `backend/app/agents/validation_agent.py`)
- Agent workflow → Design state: shares state (evidence: `backend/app/graph/workflow.py`)
- Design state → Network model: types topology (evidence: `backend/app/graph/state.py`)
- Topology layout → Network model: produces topology (evidence: `backend/app/generators/topology_layout.py`)
- Topology editor → Configuration panel: renders (evidence: `frontend/src/components/topology/TopologyEditor.tsx`)
- Topology editor → Packet Tracer panel: renders (evidence: `frontend/src/components/topology/TopologyEditor.tsx`)
- Network designer → Projects, chats, reports: manages saved work
- Projects, chats, reports → Design database: reads and writes (evidence: `backend/app/api/chats.py`)
- Reachability endpoint → Reachability simulation: runs checks (evidence: `backend/app/api/simulate.py`)
- Reachability endpoint → Network model: accepts topology (evidence: `backend/app/api/simulate.py`)
- Packet Tracer endpoint → Packet Tracer client: requests execution (evidence: `backend/app/api/packettracer.py`)
- Packet Tracer client → Packet Tracer worker: launches worker (evidence: `backend/app/integrations/packettracer/client.py`)
- Packet Tracer worker → Packet Tracer bridge: calls MCP tools (evidence: `backend/app/integrations/packettracer/mcp_worker.py`)
- Topology editor → Packet Tracer client: starts verification
