# sayujya-apte/idpv2 architecture

> Architecture diagram of the GitHub repository sayujya-apte/idpv2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sayujya-apte/idpv2
- Repository: https://github.com/sayujya-apte/idpv2

## Overview

vibe_idp runs purpose-specific agents in synchronous communication rounds. The workflow is to define an adjacency-matrix topology and agents, invoke the network runner, let each agent read its inbox and propose messages, then have a centralized router validate recipients and refill inboxes for the next cycle; the run returns a delivery/rejection log that can be summarized. The graph module owns agent dispatch and round control, while the topology and message types support routing. README and sampled source document this flow and Groq-backed agents; links to that external model service are optional integrations.

Main entry points: [`src/vibe_idp/graph.py`](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py) (Router node), [`src/vibe_idp/runner.py`](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/runner.py) (Run network), [`src/vibe_idp/router.py`](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/router.py) (Central router), [`src/vibe_idp/agent.py`](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/agent.py) (Purpose agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Round execution"]
  node_runner["Run network<br/>[runner.py]"]
  node_graph["Round graph<br/>[graph.py]"]
  node_agent_nodes["Agent nodes<br/>[graph.py]"]
  node_router_node["Router node<br/>[graph.py]"]
  node_summary["Log summary<br/>[runner.py]"]
end

subgraph group_messaging["Agents and routing"]
  node_central_router["Central router<br/>[router.py]"]
  node_inboxes[("Per-agent inboxes<br/>[graph.py]")]
  node_run_log[("Run log<br/>[graph.py]")]
end

subgraph group_model["Model integration"]
  node_purpose_agent["Purpose agent<br/>[agent.py]"]
  node_groq(("Groq model"))
end

subgraph group_contracts["Topology and messages"]
  node_topology["Topology rules<br/>[topology.py]"]
  node_message_types["Message records<br/>[types.py]"]
end

node_caller(("Network caller"))

node_caller -->|"invokes"| node_runner
node_runner -->|"builds and invokes"| node_graph
node_graph -->|"dispatches"| node_router_node
node_graph -->|"dispatches"| node_agent_nodes
node_router_node -->|"routes via"| node_central_router
node_central_router -->|"checks permissions"| node_topology
node_central_router -->|"creates records"| node_message_types
node_router_node -->|"refills"| node_inboxes
node_router_node -->|"appends deliveries and rejections"| node_run_log
node_inboxes -->|"provides next-cycle messages"| node_agent_nodes
node_agent_nodes -->|"calls step"| node_purpose_agent
node_purpose_agent -.->|"requests decision"| node_groq
node_purpose_agent -->|"returns outbounds"| node_message_types
node_agent_nodes -->|"writes outboxes"| node_router_node
node_runner -->|"can summarize log"| node_summary
node_run_log -->|"supplies entries"| node_summary

click node_runner "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/runner.py"
click node_graph "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py"
click node_agent_nodes "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py"
click node_router_node "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py"
click node_purpose_agent "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/agent.py"
click node_central_router "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/router.py"
click node_topology "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/topology.py"
click node_message_types "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/types.py"
click node_inboxes "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py"
click node_run_log "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py"
click node_summary "https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/runner.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_runner,node_graph,node_agent_nodes,node_router_node,node_summary toneBlue
class node_central_router,node_inboxes,node_run_log toneAmber
class node_purpose_agent,node_groq toneMint
class node_topology,node_message_types toneRose
class node_caller toneIndigo
```

## Components

### Round execution

- [Run network](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/runner.py): `src/vibe_idp/runner.py`
- [Round graph](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py): `src/vibe_idp/graph.py`
- [Agent nodes](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py): `src/vibe_idp/graph.py`
- [Router node](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py): `src/vibe_idp/graph.py`
- [Log summary](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/runner.py): `src/vibe_idp/runner.py`

### Agents and routing

- [Central router](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/router.py): `src/vibe_idp/router.py`
- [Per-agent inboxes](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py): `src/vibe_idp/graph.py`
- [Run log](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/graph.py): `src/vibe_idp/graph.py`

### Model integration

- [Purpose agent](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/agent.py): `src/vibe_idp/agent.py`
- **Groq model**

### Topology and messages

- [Topology rules](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/topology.py): `src/vibe_idp/topology.py`
- [Message records](https://github.com/sayujya-apte/idpv2/blob/main/src/vibe_idp/types.py): `src/vibe_idp/types.py`

### Other components

- **Network caller**

## Connections

- Network caller → Run network: invokes
- Run network → Round graph: builds and invokes
- Round graph → Router node: dispatches
- Round graph → Agent nodes: dispatches
- Router node → Central router: routes via
- Central router → Topology rules: checks permissions
- Central router → Message records: creates records
- Router node → Per-agent inboxes: refills
- Router node → Run log: appends deliveries and rejections
- Per-agent inboxes → Agent nodes: provides next-cycle messages
- Agent nodes → Purpose agent: calls step
- Purpose agent → Groq model: requests decision
- Purpose agent → Message records: returns outbounds
- Agent nodes → Router node: writes outboxes
- Run network → Log summary: can summarize log
- Run log → Log summary: supplies entries