# teferdet/finances architecture

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

- Interactive diagram: https://gitdiagram.com/teferdet/finances
- Repository: https://github.com/teferdet/finances

## Overview

Finances is a Telegram financial assistant: users request currency and market conversions, manage portfolios and alerts, and receive scheduled updates. Its Python bot routes Telegram interactions to handlers, while background services refresh rates and evaluate alerts. A separate web dashboard exposes administrative views through an API; both the bot and API are configured for MongoDB-backed data. The README also documents in-bot administration, diagnostics, localization, and exports. Some handler, parser, and dashboard-page implementations were not sampled, so their internal connections are omitted or marked unverified.

Main entry points: [`app/services/parser_service.py`](https://github.com/teferdet/finances/blob/main/app/services/parser_service.py) (Rate parser), [`app/bot.py`](https://github.com/teferdet/finances/blob/main/app/bot.py) (Bot dispatcher), [`dashboard/API/Program.cs`](https://github.com/teferdet/finances/blob/main/dashboard/API/Program.cs) (Dashboard API), [`app/services/alert_service.py`](https://github.com/teferdet/finances/blob/main/app/services/alert_service.py) (Alerts and volatility)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram experience"]
  node_bot_runtime["Bot dispatcher<br/>[bot.py]"]
  node_finance_handlers["Finance handlers"]
  node_admin_handler["Admin panel<br/>[admin.py]"]
  node_localization["Localization<br/>[i18n.py]"]
end

subgraph group_finance["Financial services"]
  node_parser_orchestrator["Rate parser<br/>[parser_service.py]"]
  node_fiat_parser["Fiat parser<br/>[fiat_parser.py]"]
  node_crypto_parser["Crypto parser<br/>[crypto_parser.py]"]
  node_stocks_parser["Stocks parser<br/>[stocks_parser.py]"]
  node_alerts["Alerts and volatility<br/>[alert_service.py]"]
  node_portfolio["Portfolio service"]
  node_digest["Digest service<br/>[digest_service.py]"]
  node_analytics["Analytics reporter"]
end

subgraph group_dashboard["Web administration"]
  node_dashboard_ui["Dashboard interface<br/>[App.tsx]"]
  node_dashboard_client["API client<br/>[client.ts]"]
  node_dashboard_api["Dashboard API<br/>[Program.cs]"]
  node_auth_controller["Authentication API<br/>[AuthController.cs]"]
  node_auth_service["OTP and JWT auth<br/>[AuthService.cs]"]
  node_stats_controller["Statistics API<br/>[StatsController.cs]"]
  node_stats_service["Statistics service<br/>[StatsService.cs]"]
  node_users_controller["User data API<br/>[UsersController.cs]"]
  node_user_service["User data service<br/>[UserDataService.cs]"]
end

subgraph group_platform["Shared platform"]
  node_mongo[("Bot data store<br/>[db.py]")]
  node_redis_cache["Redis cache adapter<br/>[redis_client.py]"]
  node_memory_cache["Memory cache<br/>[cache.py]"]
  node_runtime_config["Runtime configuration<br/>[config.py]"]
  node_dashboard_store[("Dashboard data store<br/>[MongoContext.cs]")]
  node_user_entity["User entity<br/>[User.cs]"]
end

node_telegram_user(("Telegram user"))
node_dashboard_user(("Dashboard user"))

node_telegram_user -->|"sends requests"| node_bot_runtime
node_bot_runtime -->|"routes updates"| node_finance_handlers
node_bot_runtime -->|"starts workers"| node_parser_orchestrator
node_bot_runtime -->|"starts workers"| node_alerts
node_bot_runtime -->|"starts worker"| node_digest
node_bot_runtime -->|"starts reporter"| node_analytics
node_finance_handlers -->|"requests conversions"| node_parser_orchestrator
node_parser_orchestrator -->|"reads and writes rates"| node_mongo
node_parser_orchestrator -->|"delegates fetching"| node_fiat_parser
node_parser_orchestrator -->|"delegates fetching"| node_crypto_parser
node_parser_orchestrator -->|"delegates fetching"| node_stocks_parser
node_parser_orchestrator -->|"checks prices"| node_alerts
node_alerts -->|"reads price data"| node_mongo
node_finance_handlers -.->|"manages portfolios"| node_portfolio
node_finance_handlers -.->|"manages alerts"| node_alerts
node_digest -->|"uses alert service"| node_alerts
node_analytics -.->|"reads activity data"| node_mongo
node_admin_handler -->|"reads admin statistics"| node_mongo
node_admin_handler -->|"gets translated text"| node_localization
node_admin_handler -.->|"exports admin data"| node_dashboard_api
node_parser_orchestrator -->|"uses cache"| node_redis_cache
node_redis_cache -->|"falls back to"| node_memory_cache
node_dashboard_user -.->|"uses dashboard"| node_dashboard_ui
node_dashboard_ui -.->|"uses API client"| node_dashboard_client
node_dashboard_client -.->|"calls API"| node_dashboard_api
node_dashboard_api -->|"registers routes"| node_auth_controller
node_dashboard_api -->|"registers routes"| node_stats_controller
node_dashboard_api -->|"registers routes"| node_users_controller
node_auth_controller -->|"delegates authentication"| node_auth_service
node_auth_service -->|"stores OTP data"| node_dashboard_store
node_stats_controller -->|"requests statistics"| node_stats_service
node_stats_service -->|"queries metrics"| node_dashboard_store
node_users_controller -->|"delegates user queries"| node_user_service
node_user_service -->|"queries user data"| node_dashboard_store
node_user_service -->|"maps user records"| node_user_entity

click node_bot_runtime "https://github.com/teferdet/finances/blob/main/app/bot.py"
click node_finance_handlers "https://github.com/teferdet/finances/tree/main/app/handlers"
click node_admin_handler "https://github.com/teferdet/finances/blob/main/app/handlers/admin.py"
click node_localization "https://github.com/teferdet/finances/blob/main/app/i18n.py"
click node_parser_orchestrator "https://github.com/teferdet/finances/blob/main/app/services/parser_service.py"
click node_fiat_parser "https://github.com/teferdet/finances/blob/main/app/services/fiat_parser.py"
click node_crypto_parser "https://github.com/teferdet/finances/blob/main/app/services/crypto_parser.py"
click node_stocks_parser "https://github.com/teferdet/finances/blob/main/app/services/stocks_parser.py"
click node_alerts "https://github.com/teferdet/finances/blob/main/app/services/alert_service.py"
click node_portfolio "https://github.com/teferdet/finances/blob/main/app/services/portfolio_service.py"
click node_digest "https://github.com/teferdet/finances/blob/main/app/services/digest_service.py"
click node_analytics "https://github.com/teferdet/finances/blob/main/app/services/analytics_reporter.py"
click node_mongo "https://github.com/teferdet/finances/blob/main/app/db.py"
click node_redis_cache "https://github.com/teferdet/finances/blob/main/app/redis_client.py"
click node_memory_cache "https://github.com/teferdet/finances/blob/main/app/cache.py"
click node_runtime_config "https://github.com/teferdet/finances/blob/main/app/config.py"
click node_dashboard_ui "https://github.com/teferdet/finances/blob/main/dashboard/frontend/src/App.tsx"
click node_dashboard_client "https://github.com/teferdet/finances/blob/main/dashboard/frontend/src/api/client.ts"
click node_dashboard_api "https://github.com/teferdet/finances/blob/main/dashboard/API/Program.cs"
click node_auth_controller "https://github.com/teferdet/finances/blob/main/dashboard/API/Controllers/AuthController.cs"
click node_auth_service "https://github.com/teferdet/finances/blob/main/dashboard/API/Services/AuthService.cs"
click node_stats_controller "https://github.com/teferdet/finances/blob/main/dashboard/API/Controllers/StatsController.cs"
click node_stats_service "https://github.com/teferdet/finances/blob/main/dashboard/API/Services/StatsService.cs"
click node_users_controller "https://github.com/teferdet/finances/blob/main/dashboard/API/Controllers/UsersController.cs"
click node_user_service "https://github.com/teferdet/finances/blob/main/dashboard/API/Services/UserDataService.cs"
click node_dashboard_store "https://github.com/teferdet/finances/blob/main/dashboard/API/Repositories/MongoContext.cs"
click node_user_entity "https://github.com/teferdet/finances/blob/main/dashboard/API/Models/Entities/User.cs"

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_bot_runtime,node_finance_handlers,node_admin_handler,node_localization,node_telegram_user,node_dashboard_user toneBlue
class node_parser_orchestrator,node_fiat_parser,node_crypto_parser,node_stocks_parser,node_alerts,node_portfolio,node_digest,node_analytics toneAmber
class node_dashboard_ui,node_dashboard_client,node_dashboard_api,node_auth_controller,node_auth_service,node_stats_controller,node_stats_service,node_users_controller,node_user_service toneMint
class node_mongo,node_redis_cache,node_memory_cache,node_runtime_config,node_dashboard_store,node_user_entity toneRose
```

## Components

### Telegram experience

- [Bot dispatcher](https://github.com/teferdet/finances/blob/main/app/bot.py): `app/bot.py`
- [Finance handlers](https://github.com/teferdet/finances/tree/main/app/handlers): `app/handlers`
- [Admin panel](https://github.com/teferdet/finances/blob/main/app/handlers/admin.py): `app/handlers/admin.py`
- [Localization](https://github.com/teferdet/finances/blob/main/app/i18n.py): `app/i18n.py`

### Financial services

- [Rate parser](https://github.com/teferdet/finances/blob/main/app/services/parser_service.py): `app/services/parser_service.py`
- [Fiat parser](https://github.com/teferdet/finances/blob/main/app/services/fiat_parser.py): `app/services/fiat_parser.py`
- [Crypto parser](https://github.com/teferdet/finances/blob/main/app/services/crypto_parser.py): `app/services/crypto_parser.py`
- [Stocks parser](https://github.com/teferdet/finances/blob/main/app/services/stocks_parser.py): `app/services/stocks_parser.py`
- [Alerts and volatility](https://github.com/teferdet/finances/blob/main/app/services/alert_service.py): `app/services/alert_service.py`
- [Portfolio service](https://github.com/teferdet/finances/blob/main/app/services/portfolio_service.py): `app/services/portfolio_service.py`
- [Digest service](https://github.com/teferdet/finances/blob/main/app/services/digest_service.py): `app/services/digest_service.py`
- [Analytics reporter](https://github.com/teferdet/finances/blob/main/app/services/analytics_reporter.py): `app/services/analytics_reporter.py`

### Web administration

- [Dashboard interface](https://github.com/teferdet/finances/blob/main/dashboard/frontend/src/App.tsx): `dashboard/frontend/src/App.tsx`
- [API client](https://github.com/teferdet/finances/blob/main/dashboard/frontend/src/api/client.ts): `dashboard/frontend/src/api/client.ts`
- [Dashboard API](https://github.com/teferdet/finances/blob/main/dashboard/API/Program.cs): `dashboard/API/Program.cs`
- [Authentication API](https://github.com/teferdet/finances/blob/main/dashboard/API/Controllers/AuthController.cs): `dashboard/API/Controllers/AuthController.cs`
- [OTP and JWT auth](https://github.com/teferdet/finances/blob/main/dashboard/API/Services/AuthService.cs): `dashboard/API/Services/AuthService.cs`
- [Statistics API](https://github.com/teferdet/finances/blob/main/dashboard/API/Controllers/StatsController.cs): `dashboard/API/Controllers/StatsController.cs`
- [Statistics service](https://github.com/teferdet/finances/blob/main/dashboard/API/Services/StatsService.cs): `dashboard/API/Services/StatsService.cs`
- [User data API](https://github.com/teferdet/finances/blob/main/dashboard/API/Controllers/UsersController.cs): `dashboard/API/Controllers/UsersController.cs`
- [User data service](https://github.com/teferdet/finances/blob/main/dashboard/API/Services/UserDataService.cs): `dashboard/API/Services/UserDataService.cs`

### Shared platform

- [Bot data store](https://github.com/teferdet/finances/blob/main/app/db.py): `app/db.py`
- [Redis cache adapter](https://github.com/teferdet/finances/blob/main/app/redis_client.py): `app/redis_client.py`
- [Memory cache](https://github.com/teferdet/finances/blob/main/app/cache.py): `app/cache.py`
- [Runtime configuration](https://github.com/teferdet/finances/blob/main/app/config.py): `app/config.py`
- [Dashboard data store](https://github.com/teferdet/finances/blob/main/dashboard/API/Repositories/MongoContext.cs): `dashboard/API/Repositories/MongoContext.cs`
- [User entity](https://github.com/teferdet/finances/blob/main/dashboard/API/Models/Entities/User.cs): `dashboard/API/Models/Entities/User.cs`

### Other components

- **Telegram user**
- **Dashboard user**

## Connections

- Telegram user → Bot dispatcher: sends requests (evidence: `README.md`)
- Bot dispatcher → Finance handlers: routes updates (evidence: `app/bot.py`)
- Bot dispatcher → Rate parser: starts workers (evidence: `app/__main__.py`)
- Bot dispatcher → Alerts and volatility: starts workers (evidence: `app/__main__.py`)
- Bot dispatcher → Digest service: starts worker (evidence: `app/__main__.py`)
- Bot dispatcher → Analytics reporter: starts reporter (evidence: `app/__main__.py`)
- Finance handlers → Rate parser: requests conversions (evidence: `app/handlers/inline_query.py`)
- Rate parser → Bot data store: reads and writes rates (evidence: `app/services/parser_service.py`)
- Rate parser → Fiat parser: delegates fetching (evidence: `app/services/parser_service.py`)
- Rate parser → Crypto parser: delegates fetching (evidence: `app/services/parser_service.py`)
- Rate parser → Stocks parser: delegates fetching (evidence: `app/services/parser_service.py`)
- Rate parser → Alerts and volatility: checks prices (evidence: `app/services/parser_service.py`)
- Alerts and volatility → Bot data store: reads price data (evidence: `app/services/alert_service.py`)
- Finance handlers → Portfolio service: manages portfolios
- Finance handlers → Alerts and volatility: manages alerts
- Digest service → Alerts and volatility: uses alert service (evidence: `app/services/digest_service.py`)
- Analytics reporter → Bot data store: reads activity data
- Admin panel → Bot data store: reads admin statistics (evidence: `app/handlers/admin.py`)
- Admin panel → Localization: gets translated text (evidence: `app/handlers/admin.py`)
- Admin panel → Dashboard API: exports admin data
- Rate parser → Redis cache adapter: uses cache (evidence: `app/services/parser_service.py`)
- Redis cache adapter → Memory cache: falls back to (evidence: `app/redis_client.py`)
- Dashboard user → Dashboard interface: uses dashboard
- Dashboard interface → API client: uses API client
- API client → Dashboard API: calls API
- Dashboard API → Authentication API: registers routes (evidence: `dashboard/API/Program.cs`)
- Dashboard API → Statistics API: registers routes (evidence: `dashboard/API/Program.cs`)
- Dashboard API → User data API: registers routes (evidence: `dashboard/API/Program.cs`)
- Authentication API → OTP and JWT auth: delegates authentication (evidence: `dashboard/API/Controllers/AuthController.cs`)
- OTP and JWT auth → Dashboard data store: stores OTP data (evidence: `dashboard/API/Services/AuthService.cs`)
- Statistics API → Statistics service: requests statistics (evidence: `dashboard/API/Controllers/StatsController.cs`)
- Statistics service → Dashboard data store: queries metrics (evidence: `dashboard/API/Services/StatsService.cs`)
- User data API → User data service: delegates user queries (evidence: `dashboard/API/Controllers/UsersController.cs`)
- User data service → Dashboard data store: queries user data (evidence: `dashboard/API/Services/UserDataService.cs`)
- User data service → User entity: maps user records (evidence: `dashboard/API/Services/UserDataService.cs`)
