# marcpage/libranet architecture

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

- Interactive diagram: https://gitdiagram.com/marcpage/libranet
- Repository: https://github.com/marcpage/libranet

## Overview

Libranet is a decentralized, HTTP-based content-sharing node. A browser or peer requests content from a node; content is identified and checked by its bytes, read locally or sought from peers, then served or relayed. Nodes also accept and store content, self-organize storage, and expose application, backup, identity, drop, and Karma capabilities. The graph reflects documented runtime boundaries and event relationships; several feature implementations are represented by their exact source directories because their files were not sampled.

Main entry points: [`src/libranet/webserver/server.py`](https://github.com/marcpage/libranet/blob/main/src/libranet/webserver/server.py) (HTTP API), [`src/libranet/messaging/events.py`](https://github.com/marcpage/libranet/blob/main/src/libranet/messaging/events.py) (Event messaging), [`src/libranet/connections/peer_session.py`](https://github.com/marcpage/libranet/blob/main/src/libranet/connections/peer_session.py) (Peer connections), [`src/libranet/fetcher/module.py`](https://github.com/marcpage/libranet/blob/main/src/libranet/fetcher/module.py) (Content fetching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP and applications"]
  node_http_api["HTTP API<br/>[server.py]"]
  node_search_handler["Search requests<br/>[search_handler.py]"]
  node_applications["Web applications<br/>[packaged.py]"]
  node_unbundler["Application resolution<br/>[module.py]"]
end

subgraph group_content["Content and bundles"]
  node_content_id["Content identifiers<br/>[content_id.py]"]
  node_cas[("Content store<br/>[store.py]")]
  node_bundles["Bundle encoding<br/>[layering.py]"]
  node_bundle_storage["Bundle storage<br/>[storing.py]"]
  node_shunned["Shunned content<br/>[shunned.py]"]
end

subgraph group_network["Peer network"]
  node_connections["Peer connections<br/>[peer_session.py]"]
  node_fetcher["Content fetching<br/>[module.py]"]
  node_messaging["Event messaging<br/>[events.py]"]
  node_identity["Node identity<br/>[node_identity.py]"]
end

subgraph group_operations["Node operations"]
  node_stats[("Network statistics<br/>[database.py]")]
  node_eviction["Storage eviction<br/>[module.py]"]
  node_supervisor["Process supervision"]
  node_configuration["Node configuration<br/>[models.py]"]
end

subgraph group_features["Product features"]
  node_backup["Encrypted backups"]
  node_drops["Named drops<br/>[drop_handler.py]"]
  node_karma["Karma fairness"]
  node_identity_features["People and trust"]
end

node_browser(("Browser or client"))

node_browser -->|"requests content"| node_http_api
node_search_handler -->|"publishes search"| node_messaging
node_http_api -->|"publishes data events"| node_messaging
node_http_api -->|"resolves app paths"| node_unbundler
node_applications -->|"stores app bundles"| node_bundle_storage
node_unbundler -->|"loads bundle parts"| node_bundles
node_bundles -->|"names content"| node_content_id
node_bundle_storage -.->|"writes objects"| node_cas
node_http_api -->|"serves stored data"| node_cas
node_search_handler -->|"filters results"| node_shunned
node_fetcher -->|"requests fetches"| node_connections
node_connections -->|"reports fetch result"| node_fetcher
node_http_api -->|"announces missing data"| node_fetcher
node_http_api -->|"announces searches"| node_connections
node_connections -->|"publishes peer events"| node_messaging
node_messaging -->|"delivers events"| node_stats
node_stats -->|"updates node lists"| node_connections
node_identity -->|"publishes public key"| node_cas
node_eviction -->|"requests storage ranking"| node_stats
node_supervisor -->|"starts dispatcher"| node_messaging
node_backup -->|"tracks stored content"| node_content_id
node_http_api -->|"dispatches backup events"| node_backup
node_drops -->|"publishes drop events"| node_messaging
node_http_api -->|"dispatches Karma events"| node_karma
node_identity_features -.->|"provides identity API"| node_http_api
node_configuration -->|"configures node startup"| node_supervisor

click node_http_api "https://github.com/marcpage/libranet/blob/main/src/libranet/webserver/server.py"
click node_search_handler "https://github.com/marcpage/libranet/blob/main/src/libranet/webserver/search_handler.py"
click node_applications "https://github.com/marcpage/libranet/blob/main/src/libranet/applications/packaged.py"
click node_unbundler "https://github.com/marcpage/libranet/blob/main/src/libranet/unbundler/module.py"
click node_content_id "https://github.com/marcpage/libranet/blob/main/src/libranet/cas/content_id.py"
click node_cas "https://github.com/marcpage/libranet/blob/main/src/libranet/cas/store.py"
click node_bundles "https://github.com/marcpage/libranet/blob/main/src/libranet/bundle/layering.py"
click node_bundle_storage "https://github.com/marcpage/libranet/blob/main/src/libranet/bundle/storing.py"
click node_shunned "https://github.com/marcpage/libranet/blob/main/src/libranet/cas/shunned.py"
click node_connections "https://github.com/marcpage/libranet/blob/main/src/libranet/connections/peer_session.py"
click node_fetcher "https://github.com/marcpage/libranet/blob/main/src/libranet/fetcher/module.py"
click node_messaging "https://github.com/marcpage/libranet/blob/main/src/libranet/messaging/events.py"
click node_identity "https://github.com/marcpage/libranet/blob/main/src/libranet/identity/node_identity.py"
click node_stats "https://github.com/marcpage/libranet/blob/main/src/libranet/stats/database.py"
click node_eviction "https://github.com/marcpage/libranet/blob/main/src/libranet/eviction/module.py"
click node_supervisor "https://github.com/marcpage/libranet/blob/main/src/libranet/supervision/process_supervisor.py"
click node_configuration "https://github.com/marcpage/libranet/blob/main/src/libranet/config/models.py"
click node_backup "https://github.com/marcpage/libranet/tree/main/src/libranet/backup"
click node_drops "https://github.com/marcpage/libranet/blob/main/src/libranet/webserver/drop_handler.py"
click node_karma "https://github.com/marcpage/libranet/tree/main/src/libranet/karma"
click node_identity_features "https://github.com/marcpage/libranet/tree/main/src/libranet/identity"

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_http_api,node_search_handler,node_applications,node_unbundler,node_browser toneBlue
class node_content_id,node_cas,node_bundles,node_bundle_storage,node_shunned toneAmber
class node_connections,node_fetcher,node_messaging,node_identity toneMint
class node_stats,node_eviction,node_supervisor,node_configuration toneRose
class node_backup,node_drops,node_karma,node_identity_features toneIndigo
```

## Components

### HTTP and applications

- [HTTP API](https://github.com/marcpage/libranet/blob/main/src/libranet/webserver/server.py): `src/libranet/webserver/server.py`
- [Search requests](https://github.com/marcpage/libranet/blob/main/src/libranet/webserver/search_handler.py): `src/libranet/webserver/search_handler.py`
- [Web applications](https://github.com/marcpage/libranet/blob/main/src/libranet/applications/packaged.py): `src/libranet/applications/packaged.py`
- [Application resolution](https://github.com/marcpage/libranet/blob/main/src/libranet/unbundler/module.py): `src/libranet/unbundler/module.py`

### Content and bundles

- [Content identifiers](https://github.com/marcpage/libranet/blob/main/src/libranet/cas/content_id.py): `src/libranet/cas/content_id.py`
- [Content store](https://github.com/marcpage/libranet/blob/main/src/libranet/cas/store.py): `src/libranet/cas/store.py`
- [Bundle encoding](https://github.com/marcpage/libranet/blob/main/src/libranet/bundle/layering.py): `src/libranet/bundle/layering.py`
- [Bundle storage](https://github.com/marcpage/libranet/blob/main/src/libranet/bundle/storing.py): `src/libranet/bundle/storing.py`
- [Shunned content](https://github.com/marcpage/libranet/blob/main/src/libranet/cas/shunned.py): `src/libranet/cas/shunned.py`

### Peer network

- [Peer connections](https://github.com/marcpage/libranet/blob/main/src/libranet/connections/peer_session.py): `src/libranet/connections/peer_session.py`
- [Content fetching](https://github.com/marcpage/libranet/blob/main/src/libranet/fetcher/module.py): `src/libranet/fetcher/module.py`
- [Event messaging](https://github.com/marcpage/libranet/blob/main/src/libranet/messaging/events.py): `src/libranet/messaging/events.py`
- [Node identity](https://github.com/marcpage/libranet/blob/main/src/libranet/identity/node_identity.py): `src/libranet/identity/node_identity.py`

### Node operations

- [Network statistics](https://github.com/marcpage/libranet/blob/main/src/libranet/stats/database.py): `src/libranet/stats/database.py`
- [Storage eviction](https://github.com/marcpage/libranet/blob/main/src/libranet/eviction/module.py): `src/libranet/eviction/module.py`
- [Process supervision](https://github.com/marcpage/libranet/blob/main/src/libranet/supervision/process_supervisor.py): `src/libranet/supervision/process_supervisor.py`
- [Node configuration](https://github.com/marcpage/libranet/blob/main/src/libranet/config/models.py): `src/libranet/config/models.py`

### Product features

- [Encrypted backups](https://github.com/marcpage/libranet/tree/main/src/libranet/backup): `src/libranet/backup`
- [Named drops](https://github.com/marcpage/libranet/blob/main/src/libranet/webserver/drop_handler.py): `src/libranet/webserver/drop_handler.py`
- [Karma fairness](https://github.com/marcpage/libranet/tree/main/src/libranet/karma): `src/libranet/karma`
- [People and trust](https://github.com/marcpage/libranet/tree/main/src/libranet/identity): `src/libranet/identity`

### Other components

- **Browser or client**

## Connections

- Browser or client → HTTP API: requests content (evidence: `README.md`)
- Search requests → Event messaging: publishes search (evidence: `src/libranet/webserver/search_handler.py`)
- HTTP API → Event messaging: publishes data events (evidence: `src/libranet/messaging/events.py`)
- HTTP API → Application resolution: resolves app paths
- Web applications → Bundle storage: stores app bundles (evidence: `src/libranet/applications/packaged.py`)
- Application resolution → Bundle encoding: loads bundle parts (evidence: `src/libranet/unbundler/module.py`)
- Bundle encoding → Content identifiers: names content (evidence: `src/libranet/bundle/layering.py`)
- Bundle storage → Content store: writes objects
- HTTP API → Content store: serves stored data (evidence: `src/libranet/webserver/server.py`)
- Search requests → Shunned content: filters results (evidence: `src/libranet/webserver/search_handler.py`)
- Content fetching → Peer connections: requests fetches
- Peer connections → Content fetching: reports fetch result
- HTTP API → Content fetching: announces missing data
- HTTP API → Peer connections: announces searches
- Peer connections → Event messaging: publishes peer events (evidence: `src/libranet/messaging/events.py`)
- Event messaging → Network statistics: delivers events (evidence: `src/libranet/messaging/events.py`)
- Network statistics → Peer connections: updates node lists
- Node identity → Content store: publishes public key (evidence: `src/libranet/identity/node_identity.py`)
- Storage eviction → Network statistics: requests storage ranking (evidence: `src/libranet/eviction/module.py`)
- Process supervision → Event messaging: starts dispatcher
- Encrypted backups → Content identifiers: tracks stored content (evidence: `src/libranet/backup/tasks.py`)
- HTTP API → Encrypted backups: dispatches backup events
- Named drops → Event messaging: publishes drop events (evidence: `src/libranet/webserver/drop_handler.py`)
- HTTP API → Karma fairness: dispatches Karma events
- People and trust → HTTP API: provides identity API (evidence: `src/libranet/webserver/server.py`)
- Node configuration → Process supervision: configures node startup (evidence: `src/libranet/supervision/process_supervisor.py`)
