# s0md3v/orbit architecture

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

- Interactive diagram: https://gitdiagram.com/s0md3v/orbit
- Repository: https://github.com/s0md3v/orbit

## Overview

Orbit is a command-line blockchain wallet investigation tool. A user supplies seed addresses and crawl options; the runtime ranks addresses, recursively fetches transaction histories, builds a weighted wallet graph, then prepares it for Quark visualization and optionally exports JSON or GraphML. The in-memory wallet map is the central state. README capabilities include adjustable depth, per-address limits, top-wallet selection, graph viewing, and export formats. Quark is downloaded at runtime when absent; its implementation is not in this repository, so viewer internals are not represented.

Main entry points: [`orbit.py`](https://github.com/s0md3v/orbit/blob/master/orbit.py) (CLI workflow), [`core/getTransactions.py`](https://github.com/s0md3v/orbit/blob/master/core/getTransactions.py) (Transaction parsing), [`core/utils.py`](https://github.com/s0md3v/orbit/blob/master/core/utils.py) (Wallet ranking), [`core/requester.py`](https://github.com/s0md3v/orbit/blob/master/core/requester.py) (Blockchain requester)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Crawl orchestration"]
  node_cli["CLI workflow<br/>[orbit.py]"]
  node_wallet_state["Wallet map<br/>[orbit.py]"]
  node_ranking["Wallet ranking<br/>[utils.py]"]
  node_discovery["Address discovery<br/>[utils.py]"]
  node_crawl["Concurrent crawl<br/>[orbit.py]"]
end

subgraph group_collection["Transaction collection"]
  node_transaction_fetch["Transaction parsing<br/>[getTransactions.py]"]
  node_page_limit["Page calculation<br/>[utils.py]"]
  node_requester["Blockchain requester<br/>[requester.py]"]
end

subgraph group_graph["Graph preparation"]
  node_graph_build["Wallet graph build<br/>[orbit.py]"]
  node_location["Node placement<br/>[utils.py]"]
end

subgraph group_delivery["Visualization and export"]
  node_graph_prepare["Viewer data setup<br/>[prepareGraph.py]"]
  node_quark_setup["Quark setup<br/>[getQuark.py]"]
  node_quark_viewer["Quark viewer"]
  node_exporter["JSON / GraphML export<br/>[exporter.py]"]
end

node_user(("Investigator"))
node_blockchain_api["Blockchain.info"]
node_browser(("Web browser"))
node_output_file["Export file"]

node_user -->|"supplies seeds/options"| node_cli
node_cli -->|"ensures viewer"| node_quark_setup
node_cli -->|"ranks wallets"| node_ranking
node_ranking -->|"returns ranked map"| node_wallet_state
node_cli -->|"finds unprocessed"| node_discovery
node_discovery -->|"reads addresses"| node_wallet_state
node_cli -->|"dispatches crawl"| node_crawl
node_crawl -->|"submits addresses"| node_transaction_fetch
node_transaction_fetch -->|"calculates pages"| node_page_limit
node_transaction_fetch -->|"requests address history"| node_requester
node_requester -->|"fetches transactions"| node_blockchain_api
node_transaction_fetch -->|"records interactions"| node_wallet_state
node_transaction_fetch -->|"marks processed"| node_wallet_state
node_cli -->|"builds graph data"| node_graph_build
node_graph_build -->|"reads ranked map"| node_wallet_state
node_graph_build -->|"assigns coordinates"| node_location
node_cli -->|"prepares viewer data"| node_graph_prepare
node_graph_prepare -->|"sets graph source"| node_quark_viewer
node_quark_setup -.->|"installs if missing"| node_quark_viewer
node_cli -->|"opens viewer"| node_browser
node_quark_viewer -->|"renders graph"| node_browser
node_cli -.->|"exports graph"| node_exporter
node_exporter -.->|"writes JSON or GraphML"| node_output_file

click node_cli "https://github.com/s0md3v/orbit/blob/master/orbit.py"
click node_wallet_state "https://github.com/s0md3v/orbit/blob/master/orbit.py"
click node_ranking "https://github.com/s0md3v/orbit/blob/master/core/utils.py"
click node_discovery "https://github.com/s0md3v/orbit/blob/master/core/utils.py"
click node_crawl "https://github.com/s0md3v/orbit/blob/master/orbit.py"
click node_transaction_fetch "https://github.com/s0md3v/orbit/blob/master/core/getTransactions.py"
click node_page_limit "https://github.com/s0md3v/orbit/blob/master/core/utils.py"
click node_requester "https://github.com/s0md3v/orbit/blob/master/core/requester.py"
click node_graph_build "https://github.com/s0md3v/orbit/blob/master/orbit.py"
click node_location "https://github.com/s0md3v/orbit/blob/master/core/utils.py"
click node_graph_prepare "https://github.com/s0md3v/orbit/blob/master/core/prepareGraph.py"
click node_quark_setup "https://github.com/s0md3v/orbit/blob/master/core/getQuark.py"
click node_exporter "https://github.com/s0md3v/orbit/blob/master/core/exporter.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_cli,node_wallet_state,node_ranking,node_discovery,node_crawl,node_browser toneBlue
class node_transaction_fetch,node_page_limit,node_requester toneAmber
class node_graph_build,node_location toneMint
class node_graph_prepare,node_quark_setup,node_quark_viewer,node_exporter toneRose
class node_user,node_blockchain_api,node_output_file toneIndigo
```

## Components

### Crawl orchestration

- [CLI workflow](https://github.com/s0md3v/orbit/blob/master/orbit.py): `orbit.py`
- [Wallet map](https://github.com/s0md3v/orbit/blob/master/orbit.py): `orbit.py`
- [Wallet ranking](https://github.com/s0md3v/orbit/blob/master/core/utils.py): `core/utils.py`
- [Address discovery](https://github.com/s0md3v/orbit/blob/master/core/utils.py): `core/utils.py`
- [Concurrent crawl](https://github.com/s0md3v/orbit/blob/master/orbit.py): `orbit.py`

### Transaction collection

- [Transaction parsing](https://github.com/s0md3v/orbit/blob/master/core/getTransactions.py): `core/getTransactions.py`
- [Page calculation](https://github.com/s0md3v/orbit/blob/master/core/utils.py): `core/utils.py`
- [Blockchain requester](https://github.com/s0md3v/orbit/blob/master/core/requester.py): `core/requester.py`

### Graph preparation

- [Wallet graph build](https://github.com/s0md3v/orbit/blob/master/orbit.py): `orbit.py`
- [Node placement](https://github.com/s0md3v/orbit/blob/master/core/utils.py): `core/utils.py`

### Visualization and export

- [Viewer data setup](https://github.com/s0md3v/orbit/blob/master/core/prepareGraph.py): `core/prepareGraph.py`
- [Quark setup](https://github.com/s0md3v/orbit/blob/master/core/getQuark.py): `core/getQuark.py`
- **Quark viewer**
- [JSON / GraphML export](https://github.com/s0md3v/orbit/blob/master/core/exporter.py): `core/exporter.py`

### Other components

- **Investigator**
- **Blockchain.info**
- **Web browser**
- **Export file**

## Connections

- Investigator → CLI workflow: supplies seeds/options
- CLI workflow → Quark setup: ensures viewer
- CLI workflow → Wallet ranking: ranks wallets
- Wallet ranking → Wallet map: returns ranked map
- CLI workflow → Address discovery: finds unprocessed
- Address discovery → Wallet map: reads addresses
- CLI workflow → Concurrent crawl: dispatches crawl
- Concurrent crawl → Transaction parsing: submits addresses
- Transaction parsing → Page calculation: calculates pages
- Transaction parsing → Blockchain requester: requests address history
- Blockchain requester → Blockchain.info: fetches transactions
- Transaction parsing → Wallet map: records interactions
- Transaction parsing → Wallet map: marks processed
- CLI workflow → Wallet graph build: builds graph data
- Wallet graph build → Wallet map: reads ranked map
- Wallet graph build → Node placement: assigns coordinates
- CLI workflow → Viewer data setup: prepares viewer data
- Viewer data setup → Quark viewer: sets graph source
- Quark setup → Quark viewer: installs if missing
- CLI workflow → Web browser: opens viewer
- Quark viewer → Web browser: renders graph
- CLI workflow → JSON / GraphML export: exports graph
- JSON / GraphML export → Export file: writes JSON or GraphML