# fdsapoawa/telegram-rate-relay architecture

> Architecture diagram of the GitHub repository fdsapoawa/telegram-rate-relay, 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/fdsapoawa/telegram-rate-relay
- Repository: https://github.com/fdsapoawa/telegram-rate-relay

## Overview

RateRelay is a Cloudflare Worker Telegram bot for currency and crypto conversions. Telegram webhook updates enter the Worker and are routed to message-command, private-chat, or Inline handling; conversion requests are parsed, user defaults and time zones are resolved, a selected rate source is queried, and the result is formatted and returned through Telegram. Separate capabilities include saved per-user preferences, four rate providers, configurable quote caching, and health checks. The graph follows the sampled entry point and core modules; provider integrations and Durable Object storage are evidenced by source excerpts, while README statements establish webhook and product behavior.

Main entry points: [`src/providers/registry.ts`](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/registry.ts) (Rate service), [`src/index.ts`](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/index.ts) (Worker routes), [`src/app.ts`](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/app.ts) (Update handling), [`src/settings.ts`](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/settings.ts) (User settings store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Worker Entry"]
  node_worker["Worker routes<br/>[index.ts]"]
end

subgraph group_bot["Bot Experience"]
  node_update_handler["Update handling<br/>[app.ts]"]
  node_request_parser["Conversion parser<br/>[parser.ts]"]
  node_result_format["Result formatting<br/>[format.ts]"]
  node_telegram_client["Telegram client<br/>[telegram.ts]"]
end

subgraph group_rates["Rate Retrieval"]
  node_rate_service["Rate service<br/>[registry.ts]"]
  node_quote_cache["Quote cache<br/>[cache.ts]"]
  node_provider_types["Provider utilities<br/>[types.ts]"]
  node_coinbase["Coinbase rates<br/>[coinbase.ts]"]
  node_binance["Binance rates<br/>[binance.ts]"]
  node_kraken["Kraken rates<br/>[kraken.ts]"]
  node_frankfurter["Frankfurter rates<br/>[frankfurter.ts]"]
end

subgraph group_prefs["Preferences and Time"]
  node_settings_store["User settings store<br/>[settings.ts]"]
  node_timezone["Time zone utilities<br/>[timezone.ts]"]
end

node_telegram_user(("Telegram user"))
node_telegram_platform["Telegram API"]
node_market_apis["Rate provider APIs"]
node_durable_storage[("Durable Object storage")]

node_telegram_user -->|"sends updates"| node_telegram_platform
node_telegram_platform -->|"posts webhook"| node_worker
node_worker -->|"dispatches updates"| node_update_handler
node_worker -->|"creates service"| node_rate_service
node_worker -->|"creates client"| node_telegram_client
node_worker -->|"creates store"| node_settings_store
node_update_handler -->|"parses requests"| node_request_parser
node_update_handler -->|"reads and saves"| node_settings_store
node_update_handler -->|"formats quotes"| node_result_format
node_update_handler -->|"sends responses"| node_telegram_client
node_request_parser -->|"normalizes zones"| node_timezone
node_result_format -->|"labels zones"| node_timezone
node_rate_service -->|"caches quotes"| node_quote_cache
node_rate_service -->|"dispatches quotes"| node_coinbase
node_rate_service -->|"dispatches quotes"| node_binance
node_rate_service -->|"dispatches quotes"| node_kraken
node_rate_service -->|"dispatches quotes"| node_frankfurter
node_coinbase -->|"fetches rates"| node_market_apis
node_binance -->|"fetches tickers"| node_market_apis
node_kraken -->|"fetches tickers"| node_market_apis
node_frankfurter -->|"fetches reference rates"| node_market_apis
node_settings_store -->|"reads and writes"| node_durable_storage

click node_worker "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/index.ts"
click node_update_handler "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/app.ts"
click node_request_parser "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/parser.ts"
click node_result_format "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/format.ts"
click node_telegram_client "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/telegram.ts"
click node_rate_service "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/registry.ts"
click node_quote_cache "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/cache.ts"
click node_provider_types "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/types.ts"
click node_coinbase "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/coinbase.ts"
click node_binance "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/binance.ts"
click node_kraken "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/kraken.ts"
click node_frankfurter "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/frankfurter.ts"
click node_settings_store "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/settings.ts"
click node_timezone "https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/timezone.ts"

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_worker,node_telegram_user toneBlue
class node_update_handler,node_request_parser,node_result_format,node_telegram_client,node_durable_storage toneAmber
class node_rate_service,node_quote_cache,node_provider_types,node_coinbase,node_binance,node_kraken,node_frankfurter,node_telegram_platform,node_market_apis toneMint
class node_settings_store,node_timezone toneRose
```

## Components

### Worker Entry

- [Worker routes](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/index.ts): `src/index.ts`

### Bot Experience

- [Update handling](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/app.ts): `src/app.ts`
- [Conversion parser](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/parser.ts): `src/parser.ts`
- [Result formatting](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/format.ts): `src/format.ts`
- [Telegram client](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/telegram.ts): `src/telegram.ts`

### Rate Retrieval

- [Rate service](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/registry.ts): `src/providers/registry.ts`
- [Quote cache](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/cache.ts): `src/providers/cache.ts`
- [Provider utilities](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/types.ts): `src/providers/types.ts`
- [Coinbase rates](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/coinbase.ts): `src/providers/coinbase.ts`
- [Binance rates](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/binance.ts): `src/providers/binance.ts`
- [Kraken rates](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/kraken.ts): `src/providers/kraken.ts`
- [Frankfurter rates](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/providers/frankfurter.ts): `src/providers/frankfurter.ts`

### Preferences and Time

- [User settings store](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/settings.ts): `src/settings.ts`
- [Time zone utilities](https://github.com/fdsapoawa/telegram-rate-relay/blob/main/src/timezone.ts): `src/timezone.ts`

### Other components

- **Telegram user**
- **Telegram API**
- **Rate provider APIs**
- **Durable Object storage**

## Connections

- Telegram user → Telegram API: sends updates (evidence: `README.md`)
- Telegram API → Worker routes: posts webhook (evidence: `README.md`)
- Worker routes → Update handling: dispatches updates (evidence: `src/index.ts`)
- Worker routes → Rate service: creates service (evidence: `src/index.ts`)
- Worker routes → Telegram client: creates client (evidence: `src/index.ts`)
- Worker routes → User settings store: creates store (evidence: `src/index.ts`)
- Update handling → Conversion parser: parses requests (evidence: `src/app.ts`)
- Update handling → User settings store: reads and saves (evidence: `src/app.ts`)
- Update handling → Result formatting: formats quotes (evidence: `src/app.ts`)
- Update handling → Telegram client: sends responses (evidence: `src/app.ts`)
- Conversion parser → Time zone utilities: normalizes zones (evidence: `src/parser.ts`)
- Result formatting → Time zone utilities: labels zones (evidence: `src/format.ts`)
- Rate service → Quote cache: caches quotes (evidence: `src/providers/registry.ts`)
- Rate service → Coinbase rates: dispatches quotes (evidence: `src/providers/registry.ts`)
- Rate service → Binance rates: dispatches quotes (evidence: `src/providers/registry.ts`)
- Rate service → Kraken rates: dispatches quotes (evidence: `src/providers/registry.ts`)
- Rate service → Frankfurter rates: dispatches quotes (evidence: `src/providers/registry.ts`)
- Coinbase rates → Rate provider APIs: fetches rates (evidence: `src/providers/coinbase.ts`)
- Binance rates → Rate provider APIs: fetches tickers (evidence: `src/providers/binance.ts`)
- Kraken rates → Rate provider APIs: fetches tickers (evidence: `src/providers/kraken.ts`)
- Frankfurter rates → Rate provider APIs: fetches reference rates (evidence: `src/providers/frankfurter.ts`)
- User settings store → Durable Object storage: reads and writes (evidence: `src/settings.ts`)
