# alternetproject/poc architecture

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

- Interactive diagram: https://gitdiagram.com/alternetproject/poc
- Repository: https://github.com/alternetproject/poc

## Overview

Alternet is a Python HTTPS retrieval system that finds relay peers, routes a client connection through them, and fetches HTTPS content over the resulting tunnel. Its runtime also includes peer-to-peer discovery, discovery services with contact storage, and an HTTP carrier for gateway transport. The tree and excerpts also identify experiments for resilience, recovery races, shared endpoints, transport, and wire filtering; these are shown as validation scenarios rather than runtime stages. Several experiment implementations and some runtime details were not sampled, so uncertain connections are omitted.

Main entry points: [`alternet/client.py`](https://github.com/alternetproject/poc/blob/main/alternet/client.py) (HTTPS fetch), [`alternet/lab.py`](https://github.com/alternetproject/poc/blob/main/alternet/lab.py) (Local lab), [`experiments/transport_carrier.py`](https://github.com/alternetproject/poc/blob/main/experiments/transport_carrier.py) (Carrier experiment), [`experiments/recovery_race.py`](https://github.com/alternetproject/poc/blob/main/experiments/recovery_race.py) (Recovery race)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and routing"]
  node_config["Configuration<br/>[config.py]"]
  node_fetch["HTTPS fetch<br/>[client.py]"]
  node_routing["Route selection<br/>[routing.py]"]
  node_demo["Client demo<br/>[demo.py]"]
end

subgraph group_peers["Relay network"]
  node_node["Relay node<br/>[node.py]"]
  node_peerdisc["Peer exchange<br/>[peer_discovery.py]"]
  node_carrier["HTTP carrier<br/>[http_carrier.py]"]
  node_peer_demo["Peer demo<br/>[peer_demo.py]"]
end

subgraph group_discovery["Discovery services"]
  node_discovery_service["Discovery service<br/>[discovery.py]"]
  node_contact_store[("Contact store<br/>[discovery_store.py]")]
  node_discovery_demo["Discovery demo<br/>[discovery_demo.py]"]
end

subgraph group_experiments["Network experiments"]
  node_lab["Local lab<br/>[lab.py]"]
  node_resilience["Entry resilience"]
  node_recovery["Recovery race<br/>[recovery_race.py]"]
  node_shared["Shared endpoint<br/>[shared_endpoint.py]"]
  node_transport["Carrier experiment"]
  node_wire["Wire filter<br/>[wire_filter.py]"]
end

node_user(("Application"))
node_origin(("HTTPS origin"))

node_user -->|"requests fetch"| node_fetch
node_fetch -->|"uses settings"| node_config
node_fetch -->|"opens route"| node_routing
node_fetch -->|"fetches HTTPS"| node_origin
node_node -->|"starts exchange"| node_peerdisc
node_discovery_service -->|"stores contacts"| node_contact_store
node_discovery_service -->|"creates sessions"| node_carrier
node_demo -->|"calls fetch"| node_fetch
node_demo -->|"starts lab"| node_lab
node_discovery_demo -->|"calls fetch"| node_fetch
node_discovery_demo -->|"uses discovery"| node_discovery_service
node_discovery_demo -->|"starts lab"| node_lab
node_peer_demo -->|"calls fetch"| node_fetch
node_peer_demo -->|"uses peers"| node_peerdisc
node_peer_demo -->|"starts lab"| node_lab
node_resilience -->|"measures retrieval"| node_fetch
node_resilience -->|"starts services"| node_lab
node_resilience -->|"filters traffic"| node_wire
node_recovery -->|"measures retrieval"| node_fetch
node_recovery -->|"starts services"| node_lab
node_recovery -->|"reuses scenarios"| node_resilience
node_recovery -->|"filters traffic"| node_wire
node_shared -->|"tests routing"| node_fetch
node_shared -->|"starts services"| node_lab
node_shared -->|"filters traffic"| node_wire
node_transport -->|"tests transport"| node_fetch
node_transport -->|"tests carrier"| node_carrier
node_transport -->|"starts services"| node_lab
node_transport -->|"tests routes"| node_routing
node_transport -->|"uses endpoint case"| node_shared

click node_config "https://github.com/alternetproject/poc/blob/main/alternet/config.py"
click node_fetch "https://github.com/alternetproject/poc/blob/main/alternet/client.py"
click node_routing "https://github.com/alternetproject/poc/blob/main/alternet/routing.py"
click node_node "https://github.com/alternetproject/poc/blob/main/alternet/node.py"
click node_peerdisc "https://github.com/alternetproject/poc/blob/main/alternet/peer_discovery.py"
click node_carrier "https://github.com/alternetproject/poc/blob/main/alternet/http_carrier.py"
click node_discovery_service "https://github.com/alternetproject/poc/blob/main/alternet/discovery.py"
click node_contact_store "https://github.com/alternetproject/poc/blob/main/alternet/discovery_store.py"
click node_discovery_demo "https://github.com/alternetproject/poc/blob/main/alternet/discovery_demo.py"
click node_peer_demo "https://github.com/alternetproject/poc/blob/main/alternet/peer_demo.py"
click node_demo "https://github.com/alternetproject/poc/blob/main/alternet/demo.py"
click node_lab "https://github.com/alternetproject/poc/blob/main/alternet/lab.py"
click node_resilience "https://github.com/alternetproject/poc/blob/main/experiments/entry_resilience.py"
click node_recovery "https://github.com/alternetproject/poc/blob/main/experiments/recovery_race.py"
click node_shared "https://github.com/alternetproject/poc/blob/main/experiments/shared_endpoint.py"
click node_transport "https://github.com/alternetproject/poc/blob/main/experiments/transport_carrier.py"
click node_wire "https://github.com/alternetproject/poc/blob/main/experiments/wire_filter.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_config,node_fetch,node_routing,node_demo toneBlue
class node_node,node_peerdisc,node_carrier,node_peer_demo toneAmber
class node_discovery_service,node_contact_store,node_discovery_demo toneMint
class node_lab,node_resilience,node_recovery,node_shared,node_transport,node_wire toneRose
class node_user,node_origin toneIndigo
```

## Components

### Client and routing

- [Configuration](https://github.com/alternetproject/poc/blob/main/alternet/config.py): `alternet/config.py`
- [HTTPS fetch](https://github.com/alternetproject/poc/blob/main/alternet/client.py): `alternet/client.py`
- [Route selection](https://github.com/alternetproject/poc/blob/main/alternet/routing.py): `alternet/routing.py`
- [Client demo](https://github.com/alternetproject/poc/blob/main/alternet/demo.py): `alternet/demo.py`

### Relay network

- [Relay node](https://github.com/alternetproject/poc/blob/main/alternet/node.py): `alternet/node.py`
- [Peer exchange](https://github.com/alternetproject/poc/blob/main/alternet/peer_discovery.py): `alternet/peer_discovery.py`
- [HTTP carrier](https://github.com/alternetproject/poc/blob/main/alternet/http_carrier.py): `alternet/http_carrier.py`
- [Peer demo](https://github.com/alternetproject/poc/blob/main/alternet/peer_demo.py): `alternet/peer_demo.py`

### Discovery services

- [Discovery service](https://github.com/alternetproject/poc/blob/main/alternet/discovery.py): `alternet/discovery.py`
- [Contact store](https://github.com/alternetproject/poc/blob/main/alternet/discovery_store.py): `alternet/discovery_store.py`
- [Discovery demo](https://github.com/alternetproject/poc/blob/main/alternet/discovery_demo.py): `alternet/discovery_demo.py`

### Network experiments

- [Local lab](https://github.com/alternetproject/poc/blob/main/alternet/lab.py): `alternet/lab.py`
- [Entry resilience](https://github.com/alternetproject/poc/blob/main/experiments/entry_resilience.py): `experiments/entry_resilience.py`
- [Recovery race](https://github.com/alternetproject/poc/blob/main/experiments/recovery_race.py): `experiments/recovery_race.py`
- [Shared endpoint](https://github.com/alternetproject/poc/blob/main/experiments/shared_endpoint.py): `experiments/shared_endpoint.py`
- [Carrier experiment](https://github.com/alternetproject/poc/blob/main/experiments/transport_carrier.py): `experiments/transport_carrier.py`
- [Wire filter](https://github.com/alternetproject/poc/blob/main/experiments/wire_filter.py): `experiments/wire_filter.py`

### Other components

- **Application**
- **HTTPS origin**

## Connections

- Application → HTTPS fetch: requests fetch (evidence: `alternet/client.py`)
- HTTPS fetch → Configuration: uses settings (evidence: `alternet/client.py`)
- HTTPS fetch → Route selection: opens route (evidence: `alternet/client.py`)
- HTTPS fetch → HTTPS origin: fetches HTTPS (evidence: `alternet/client.py`)
- Relay node → Peer exchange: starts exchange (evidence: `alternet/node.py`)
- Discovery service → Contact store: stores contacts (evidence: `alternet/discovery.py`)
- Discovery service → HTTP carrier: creates sessions (evidence: `alternet/discovery.py`)
- Client demo → HTTPS fetch: calls fetch (evidence: `alternet/demo.py`)
- Client demo → Local lab: starts lab (evidence: `alternet/demo.py`)
- Discovery demo → HTTPS fetch: calls fetch (evidence: `alternet/discovery_demo.py`)
- Discovery demo → Discovery service: uses discovery (evidence: `alternet/discovery_demo.py`)
- Discovery demo → Local lab: starts lab (evidence: `alternet/discovery_demo.py`)
- Peer demo → HTTPS fetch: calls fetch (evidence: `alternet/peer_demo.py`)
- Peer demo → Peer exchange: uses peers (evidence: `alternet/peer_demo.py`)
- Peer demo → Local lab: starts lab (evidence: `alternet/peer_demo.py`)
- Entry resilience → HTTPS fetch: measures retrieval (evidence: `experiments/entry_resilience.py`)
- Entry resilience → Local lab: starts services (evidence: `experiments/entry_resilience.py`)
- Entry resilience → Wire filter: filters traffic (evidence: `experiments/entry_resilience.py`)
- Recovery race → HTTPS fetch: measures retrieval (evidence: `experiments/recovery_race.py`)
- Recovery race → Local lab: starts services (evidence: `experiments/recovery_race.py`)
- Recovery race → Entry resilience: reuses scenarios (evidence: `experiments/recovery_race.py`)
- Recovery race → Wire filter: filters traffic (evidence: `experiments/recovery_race.py`)
- Shared endpoint → HTTPS fetch: tests routing (evidence: `experiments/shared_endpoint.py`)
- Shared endpoint → Local lab: starts services (evidence: `experiments/shared_endpoint.py`)
- Shared endpoint → Wire filter: filters traffic (evidence: `experiments/shared_endpoint.py`)
- Carrier experiment → HTTPS fetch: tests transport (evidence: `experiments/transport_carrier.py`)
- Carrier experiment → HTTP carrier: tests carrier (evidence: `experiments/transport_carrier.py`)
- Carrier experiment → Local lab: starts services (evidence: `experiments/transport_carrier.py`)
- Carrier experiment → Route selection: tests routes (evidence: `experiments/transport_carrier.py`)
- Carrier experiment → Shared endpoint: uses endpoint case (evidence: `experiments/transport_carrier.py`)
