# harold15000/p2pc architecture

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

- Interactive diagram: https://gitdiagram.com/harold15000/p2pc
- Repository: https://github.com/harold15000/p2pc

## Overview

P2PC is a self-hosted batch-job platform: clients submit OCI-image jobs to a control-plane server, which schedules work to enrolled Linux or Windows nodes; agents run jobs in isolated sandboxes and return logs, status and outputs. The graph also preserves the documented CLI, Python SDK, MCP, service/port access and allowlisted egress capabilities. Relationships are limited to README statements and the shown source/index references; several implementation branches are represented at directory level because their source was not sampled.

Main entry points: [`crates/p2pc-server/src/app.rs`](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-server/src/app.rs) (HTTP application), [`crates/p2pc-agent/src/main.rs`](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-agent/src/main.rs) (Node agent), [`crates/p2pc-cli/src/cli.rs`](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-cli/src/cli.rs) (CLI), [`sdk/python/p2pc/client.py`](https://github.com/harold15000/p2pc/blob/main/sdk/python/p2pc/client.py) (Python SDK)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_cli["CLI<br/>[cli.rs]"]
  node_python["Python SDK<br/>[client.py]"]
  node_mcp["MCP server<br/>[server.rs]"]
  node_rest["REST client API<br/>[client.rs]"]
end

subgraph group_control["Control plane"]
  node_server["HTTP application<br/>[app.rs]"]
  node_handlers["API handlers"]
  node_scheduler["Job scheduler<br/>[service.rs]"]
  node_database[("SQLite state")]
  node_gateway["Node and port gateway"]
end

subgraph group_node["Node runtime"]
  node_agent["Node agent<br/>[main.rs]"]
  node_session["Agent connection<br/>[session.rs]"]
  node_executor["Job executor"]
  node_sandbox["Sandbox runtime<br/>[engine.rs]"]
  node_egress["Egress proxy"]
  node_wsl["Windows WSL support<br/>[runner.rs]"]
end

subgraph group_shared["Shared contracts"]
  node_contracts["API and job contracts<br/>[api.rs]"]
end

node_operator(("User or API caller"))
node_job["Containerized job"]
node_internet(("Allowed domains"))

node_operator -->|"uses"| node_cli
node_operator -->|"uses"| node_python
node_operator -->|"invokes"| node_mcp
node_operator -->|"calls"| node_rest
node_cli -->|"submits requests"| node_server
node_python -->|"submits requests"| node_server
node_mcp -->|"submits requests"| node_server
node_rest -->|"sends HTTP"| node_server
node_server -->|"routes"| node_handlers
node_server -->|"writes audit"| node_database
node_scheduler -->|"uses leases"| node_database
node_agent -->|"dials outbound"| node_server
node_agent -->|"runs connection"| node_session
node_session -.->|"dispatches leases"| node_executor
node_executor -->|"runs job"| node_sandbox
node_sandbox -->|"starts container"| node_job
node_job -.->|"requests allowed egress"| node_egress
node_egress -->|"permits domains"| node_internet
node_server -.->|"uses API types"| node_contracts
node_agent -.->|"uses on Windows"| node_wsl
node_server -.->|"provides tunnels"| node_gateway

click node_cli "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-cli/src/cli.rs"
click node_python "https://github.com/harold15000/p2pc/blob/main/sdk/python/p2pc/client.py"
click node_mcp "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-cli/src/mcp/server.rs"
click node_rest "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-client/src/client.rs"
click node_server "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-server/src/app.rs"
click node_handlers "https://github.com/harold15000/p2pc/tree/main/crates/p2pc-server/src"
click node_scheduler "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-server/src/scheduler/service.rs"
click node_database "https://github.com/harold15000/p2pc/tree/main/crates/p2pc-server/src/store"
click node_gateway "https://github.com/harold15000/p2pc/tree/main/crates/p2pc-server/src/gateway"
click node_agent "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-agent/src/main.rs"
click node_session "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-agent/src/connection/session.rs"
click node_executor "https://github.com/harold15000/p2pc/tree/main/crates/p2pc-agent/src/executor"
click node_sandbox "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-agent/src/sandbox/engine.rs"
click node_egress "https://github.com/harold15000/p2pc/tree/main/crates/p2pc-agent/src/egress"
click node_contracts "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-proto/src/api.rs"
click node_wsl "https://github.com/harold15000/p2pc/blob/main/crates/p2pc-wsl/src/runner.rs"

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_cli,node_python,node_mcp,node_rest,node_operator toneBlue
class node_server,node_handlers,node_scheduler,node_database,node_gateway toneAmber
class node_agent,node_session,node_executor,node_sandbox,node_egress,node_wsl toneMint
class node_contracts toneRose
class node_job,node_internet toneIndigo
```

## Components

### Clients

- [CLI](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-cli/src/cli.rs): `crates/p2pc-cli/src/cli.rs`
- [Python SDK](https://github.com/harold15000/p2pc/blob/main/sdk/python/p2pc/client.py): `sdk/python/p2pc/client.py`
- [MCP server](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-cli/src/mcp/server.rs): `crates/p2pc-cli/src/mcp/server.rs`
- [REST client API](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-client/src/client.rs): `crates/p2pc-client/src/client.rs`

### Control plane

- [HTTP application](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-server/src/app.rs): `crates/p2pc-server/src/app.rs`
- [API handlers](https://github.com/harold15000/p2pc/tree/main/crates/p2pc-server/src): `crates/p2pc-server/src`
- [Job scheduler](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-server/src/scheduler/service.rs): `crates/p2pc-server/src/scheduler/service.rs`
- [SQLite state](https://github.com/harold15000/p2pc/tree/main/crates/p2pc-server/src/store): `crates/p2pc-server/src/store`
- [Node and port gateway](https://github.com/harold15000/p2pc/tree/main/crates/p2pc-server/src/gateway): `crates/p2pc-server/src/gateway`

### Node runtime

- [Node agent](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-agent/src/main.rs): `crates/p2pc-agent/src/main.rs`
- [Agent connection](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-agent/src/connection/session.rs): `crates/p2pc-agent/src/connection/session.rs`
- [Job executor](https://github.com/harold15000/p2pc/tree/main/crates/p2pc-agent/src/executor): `crates/p2pc-agent/src/executor`
- [Sandbox runtime](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-agent/src/sandbox/engine.rs): `crates/p2pc-agent/src/sandbox/engine.rs`
- [Egress proxy](https://github.com/harold15000/p2pc/tree/main/crates/p2pc-agent/src/egress): `crates/p2pc-agent/src/egress`
- [Windows WSL support](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-wsl/src/runner.rs): `crates/p2pc-wsl/src/runner.rs`

### Shared contracts

- [API and job contracts](https://github.com/harold15000/p2pc/blob/main/crates/p2pc-proto/src/api.rs): `crates/p2pc-proto/src/api.rs`

### Other components

- **User or API caller**
- **Containerized job**
- **Allowed domains**

## Connections

- User or API caller → CLI: uses (evidence: `README.md`)
- User or API caller → Python SDK: uses (evidence: `README.md`)
- User or API caller → MCP server: invokes (evidence: `README.md`)
- User or API caller → REST client API: calls (evidence: `README.md`)
- CLI → HTTP application: submits requests (evidence: `README.md`)
- Python SDK → HTTP application: submits requests (evidence: `README.md`)
- MCP server → HTTP application: submits requests (evidence: `README.md`)
- REST client API → HTTP application: sends HTTP (evidence: `crates/p2pc-client/src/client.rs`)
- HTTP application → API handlers: routes (evidence: `crates/p2pc-server/src/app.rs`)
- HTTP application → SQLite state: writes audit (evidence: `crates/p2pc-server/src/app.rs`)
- Job scheduler → SQLite state: uses leases (evidence: `crates/p2pc-server/src/scheduler/service.rs`)
- Node agent → HTTP application: dials outbound (evidence: `README.md`)
- Node agent → Agent connection: runs connection (evidence: `crates/p2pc-agent/src/main.rs`)
- Agent connection → Job executor: dispatches leases
- Job executor → Sandbox runtime: runs job (evidence: `crates/p2pc-agent/src/sandbox/engine.rs`)
- Sandbox runtime → Containerized job: starts container (evidence: `README.md`)
- Containerized job → Egress proxy: requests allowed egress (evidence: `README.md`)
- Egress proxy → Allowed domains: permits domains (evidence: `README.md`)
- HTTP application → API and job contracts: uses API types
- Node agent → Windows WSL support: uses on Windows
- HTTP application → Node and port gateway: provides tunnels (evidence: `crates/p2pc-server/src/app.rs`)
