# hcftrize/tokerize architecture

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

- Interactive diagram: https://gitdiagram.com/hcftrize/tokerize
- Repository: https://github.com/hcftrize/tokerize

## Overview

Tokerize combines a Telegram community and market-intelligence bot, governance data tooling, and a read-only Explorize API. The main user workflow is a Telegram message routed to a command, which fetches market or community data, formats a reply, and sends it back. Governance scripts separately scrape and maintain bond data consumed by the bot; Explorize serves database-backed market and wallet views. Some routing and subsystems are unsampled, so their documented presence is shown without guessing internal calls.

Main entry points: [`api/rizeby/telegram.py`](https://github.com/hcftrize/tokerize/blob/main/api/rizeby/telegram.py) (Webhook Handler), [`rizeby-bot/utils/github_data.py`](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/github_data.py) (Community Data Client), [`api/explorize/_db.js`](https://github.com/hcftrize/tokerize/blob/main/api/explorize/_db.js) (Read-only DB Layer), [`rizeby-bot/commands/market.py`](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/market.py) (Market Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Telegram Bot"]
  node_webhook["Webhook Handler<br/>[telegram.py]"]
  node_govcmd["Governance Commands<br/>[governance.py]"]
  node_ecosystem["Ecosystem Commands<br/>[ecosystem.py]"]
  node_govnews["Canton Commands<br/>[canton_gov.py]"]
  node_cantonnews["Canton News<br/>[cantonnews.py]"]
  node_fun["Fun Commands<br/>[fun.py]"]
end

subgraph group_market["Market Data"]
  node_pricecmd["Price Commands<br/>[price.py]"]
  node_marketcmd["Market Commands<br/>[market.py]"]
  node_dexcmd["DEX Commands<br/>[dex.py]"]
  node_clockcmd["Canton Clock<br/>[cclock.py]"]
  node_cg["CoinGecko Client<br/>[coingecko.py]"]
  node_gt["GeckoTerminal Client<br/>[geckoterminal.py]"]
  node_dp["DexPaprika Client<br/>[dexpaprika.py]"]
  node_format["Message Formatters<br/>[formatters.py]"]
end

subgraph group_governance["Governance Data"]
  node_githubdata["Community Data Client<br/>[github_data.py]"]
  node_scraper["Governance Scraper"]
  node_compute["Bond State Compute"]
  node_bootstrap["Bond Bootstrap"]
  node_updater["Governance Updater"]
  node_auditor["Bond State Audit"]
end

subgraph group_explorize["Explorize API"]
  node_exploremarket["Market Views<br/>[market.js]"]
  node_holders["Holder Views<br/>[holders.js]"]
  node_transfers["Transfer Views<br/>[transfers.js]"]
  node_wallet["Wallet Views<br/>[wallet.js]"]
  node_bonds["Bond Helpers<br/>[_bonds.js]"]
  node_db["Read-only DB Layer<br/>[_db.js]"]
end

node_user(("Telegram User"))
node_pg[("PostgreSQL")]
node_github["GitHub Raw Data"]
node_telegramapi["Telegram API"]

node_user -.->|"sends message"| node_webhook
node_webhook -->|"routes commands"| node_govcmd
node_webhook -->|"routes commands"| node_ecosystem
node_webhook -->|"routes commands"| node_govnews
node_webhook -->|"routes commands"| node_cantonnews
node_webhook -->|"routes commands"| node_fun
node_webhook -->|"routes commands"| node_pricecmd
node_webhook -->|"routes commands"| node_marketcmd
node_webhook -->|"routes commands"| node_dexcmd
node_webhook -->|"routes commands"| node_clockcmd
node_webhook -->|"sends replies"| node_telegramapi
node_govcmd -->|"loads bond data"| node_githubdata
node_ecosystem -->|"loads entities"| node_githubdata
node_govnews -->|"loads community data"| node_githubdata
node_cantonnews -->|"loads news data"| node_githubdata
node_pricecmd -->|"fetches prices"| node_cg
node_pricecmd -->|"formats output"| node_format
node_marketcmd -->|"fetches market data"| node_cg
node_marketcmd -->|"formats output"| node_format
node_marketcmd -->|"loads history"| node_githubdata
node_dexcmd -->|"fetches pool data"| node_gt
node_dexcmd -->|"fetches trade data"| node_dp
node_dexcmd -->|"formats output"| node_format
node_githubdata -->|"fetches JSON"| node_github
node_bootstrap -->|"uses computation"| node_compute
node_exploremarket -->|"queries database"| node_db
node_holders -->|"queries database"| node_db
node_transfers -->|"queries database"| node_db
node_wallet -->|"queries database"| node_db
node_wallet -->|"uses bond helpers"| node_bonds
node_holders -->|"uses bond helpers"| node_bonds
node_db -->|"queries"| node_pg

click node_webhook "https://github.com/hcftrize/tokerize/blob/main/api/rizeby/telegram.py"
click node_govcmd "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/governance.py"
click node_ecosystem "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/ecosystem.py"
click node_govnews "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/canton_gov.py"
click node_cantonnews "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/cantonnews.py"
click node_fun "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/fun.py"
click node_pricecmd "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/price.py"
click node_marketcmd "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/market.py"
click node_dexcmd "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/dex.py"
click node_clockcmd "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/cclock.py"
click node_cg "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/coingecko.py"
click node_gt "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/geckoterminal.py"
click node_dp "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/dexpaprika.py"
click node_format "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/formatters.py"
click node_githubdata "https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/github_data.py"
click node_scraper "https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/scrape_governance.py"
click node_compute "https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/compute_bond_states.py"
click node_bootstrap "https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/bootstrap_bond_states.py"
click node_updater "https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/update_governance.py"
click node_auditor "https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/audit_bond_states.py"
click node_exploremarket "https://github.com/hcftrize/tokerize/blob/main/api/explorize/market.js"
click node_holders "https://github.com/hcftrize/tokerize/blob/main/api/explorize/holders.js"
click node_transfers "https://github.com/hcftrize/tokerize/blob/main/api/explorize/transfers.js"
click node_wallet "https://github.com/hcftrize/tokerize/blob/main/api/explorize/wallet.js"
click node_bonds "https://github.com/hcftrize/tokerize/blob/main/api/explorize/_bonds.js"
click node_db "https://github.com/hcftrize/tokerize/blob/main/api/explorize/_db.js"

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_webhook,node_govcmd,node_ecosystem,node_govnews,node_cantonnews,node_fun,node_user toneBlue
class node_pricecmd,node_marketcmd,node_dexcmd,node_clockcmd,node_cg,node_gt,node_dp,node_format,node_pg toneAmber
class node_githubdata,node_scraper,node_compute,node_bootstrap,node_updater,node_auditor,node_telegramapi toneMint
class node_exploremarket,node_holders,node_transfers,node_wallet,node_bonds,node_db toneRose
class node_github toneIndigo
```

## Components

### Telegram Bot

- [Webhook Handler](https://github.com/hcftrize/tokerize/blob/main/api/rizeby/telegram.py): `api/rizeby/telegram.py`
- [Governance Commands](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/governance.py): `rizeby-bot/commands/governance.py`
- [Ecosystem Commands](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/ecosystem.py): `rizeby-bot/commands/ecosystem.py`
- [Canton Commands](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/canton_gov.py): `rizeby-bot/commands/canton_gov.py`
- [Canton News](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/cantonnews.py): `rizeby-bot/commands/cantonnews.py`
- [Fun Commands](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/fun.py): `rizeby-bot/commands/fun.py`

### Market Data

- [Price Commands](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/price.py): `rizeby-bot/commands/price.py`
- [Market Commands](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/market.py): `rizeby-bot/commands/market.py`
- [DEX Commands](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/dex.py): `rizeby-bot/commands/dex.py`
- [Canton Clock](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/commands/cclock.py): `rizeby-bot/commands/cclock.py`
- [CoinGecko Client](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/coingecko.py): `rizeby-bot/utils/coingecko.py`
- [GeckoTerminal Client](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/geckoterminal.py): `rizeby-bot/utils/geckoterminal.py`
- [DexPaprika Client](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/dexpaprika.py): `rizeby-bot/utils/dexpaprika.py`
- [Message Formatters](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/formatters.py): `rizeby-bot/utils/formatters.py`

### Governance Data

- [Community Data Client](https://github.com/hcftrize/tokerize/blob/main/rizeby-bot/utils/github_data.py): `rizeby-bot/utils/github_data.py`
- [Governance Scraper](https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/scrape_governance.py): `rize-governance-hub/scrape_governance.py`
- [Bond State Compute](https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/compute_bond_states.py): `rize-governance-hub/compute_bond_states.py`
- [Bond Bootstrap](https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/bootstrap_bond_states.py): `rize-governance-hub/bootstrap_bond_states.py`
- [Governance Updater](https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/update_governance.py): `rize-governance-hub/update_governance.py`
- [Bond State Audit](https://github.com/hcftrize/tokerize/blob/main/rize-governance-hub/audit_bond_states.py): `rize-governance-hub/audit_bond_states.py`

### Explorize API

- [Market Views](https://github.com/hcftrize/tokerize/blob/main/api/explorize/market.js): `api/explorize/market.js`
- [Holder Views](https://github.com/hcftrize/tokerize/blob/main/api/explorize/holders.js): `api/explorize/holders.js`
- [Transfer Views](https://github.com/hcftrize/tokerize/blob/main/api/explorize/transfers.js): `api/explorize/transfers.js`
- [Wallet Views](https://github.com/hcftrize/tokerize/blob/main/api/explorize/wallet.js): `api/explorize/wallet.js`
- [Bond Helpers](https://github.com/hcftrize/tokerize/blob/main/api/explorize/_bonds.js): `api/explorize/_bonds.js`
- [Read-only DB Layer](https://github.com/hcftrize/tokerize/blob/main/api/explorize/_db.js): `api/explorize/_db.js`

### Other components

- **Telegram User**
- **PostgreSQL**
- **GitHub Raw Data**
- **Telegram API**

## Connections

- Telegram User → Webhook Handler: sends message
- Webhook Handler → Governance Commands: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Ecosystem Commands: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Canton Commands: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Canton News: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Fun Commands: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Price Commands: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Market Commands: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → DEX Commands: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Canton Clock: routes commands (evidence: `api/rizeby/telegram.py`)
- Webhook Handler → Telegram API: sends replies (evidence: `api/rizeby/telegram.py`)
- Governance Commands → Community Data Client: loads bond data (evidence: `rizeby-bot/commands/governance.py`)
- Ecosystem Commands → Community Data Client: loads entities (evidence: `rizeby-bot/commands/ecosystem.py`)
- Canton Commands → Community Data Client: loads community data (evidence: `rizeby-bot/commands/canton_gov.py`)
- Canton News → Community Data Client: loads news data (evidence: `rizeby-bot/commands/cantonnews.py`)
- Price Commands → CoinGecko Client: fetches prices (evidence: `rizeby-bot/commands/price.py`)
- Price Commands → Message Formatters: formats output (evidence: `rizeby-bot/commands/price.py`)
- Market Commands → CoinGecko Client: fetches market data (evidence: `rizeby-bot/commands/market.py`)
- Market Commands → Message Formatters: formats output (evidence: `rizeby-bot/commands/market.py`)
- Market Commands → Community Data Client: loads history (evidence: `rizeby-bot/commands/market.py`)
- DEX Commands → GeckoTerminal Client: fetches pool data (evidence: `rizeby-bot/commands/dex.py`)
- DEX Commands → DexPaprika Client: fetches trade data (evidence: `rizeby-bot/commands/dex.py`)
- DEX Commands → Message Formatters: formats output (evidence: `rizeby-bot/commands/dex.py`)
- Community Data Client → GitHub Raw Data: fetches JSON (evidence: `rizeby-bot/utils/github_data.py`)
- Bond Bootstrap → Bond State Compute: uses computation (evidence: `rize-governance-hub/bootstrap_bond_states.py`)
- Market Views → Read-only DB Layer: queries database (evidence: `api/explorize/market.js`)
- Holder Views → Read-only DB Layer: queries database (evidence: `api/explorize/holders.js`)
- Transfer Views → Read-only DB Layer: queries database (evidence: `api/explorize/transfers.js`)
- Wallet Views → Read-only DB Layer: queries database (evidence: `api/explorize/wallet.js`)
- Wallet Views → Bond Helpers: uses bond helpers (evidence: `api/explorize/wallet.js`)
- Holder Views → Bond Helpers: uses bond helpers (evidence: `api/explorize/holders.js`)
- Read-only DB Layer → PostgreSQL: queries (evidence: `api/explorize/_db.js`)
