# ahsanka667-ai/tracker architecture

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

- Interactive diagram: https://gitdiagram.com/ahsanka667-ai/tracker
- Repository: https://github.com/ahsanka667-ai/tracker

## Overview

TG Tracker captures ad clicks, associates them with Telegram activity, evaluates configured conversion triggers, records conversions, and sends events to Meta. Users manage accounts, campaigns, triggers, inbox messages, and funnels through the dashboard; the master bot also handles Telegram-based access and reusable invitations. Redis carries click/session payloads and real-time notifications, while PostgreSQL holds product state. The README documents funnel and inbox behavior beyond the sampled source, so those capabilities are represented without asserting unsampled internal call paths.

Main entry points: [`service_a/main.py`](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py) (Web API), [`shared/database.py`](https://github.com/ahsanka667-ai/tracker/blob/main/shared/database.py) (Database access), [`service_b/worker.py`](https://github.com/ahsanka667-ai/tracker/blob/main/service_b/worker.py) (Telegram worker), [`dashboard/index.html`](https://github.com/ahsanka667-ai/tracker/blob/main/dashboard/index.html) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard and API"]
  node_dashboard_ui["Dashboard UI<br/>[index.html]"]
  node_api["Web API<br/>[main.py]"]
  node_ws["WebSocket hub"]
  node_master_bot["Master bot<br/>[bot.py]"]
  node_account_campaign["Accounts and campaigns<br/>[main.py]"]
  node_inbox["Message inbox<br/>[main.py]"]
end

subgraph group_tracking["Telegram tracking"]
  node_click_tracking["Click tracking<br/>[main.py]"]
  node_worker["Telegram worker<br/>[worker.py]"]
  node_meta_dispatch["Meta CAPI<br/>[meta_capi.py]"]
  node_telegram["Telegram"]
  node_meta["Meta platform"]
end

subgraph group_conversion["Conversion analytics"]
  node_funnel["Funnels and steps<br/>[main.py]"]
  node_webhooks["Inbound webhooks<br/>[main.py]"]
  node_conversion_logs[("Conversion logs<br/>[models.py]")]
end

subgraph group_platform["Shared platform"]
  node_db_session["Database access<br/>[database.py]"]
  node_db[("PostgreSQL")]
  node_redis[("Redis")]
end

node_operator(("Tracker user"))
node_telegram_user(("Telegram user"))
node_external_system(("External system"))

node_operator -->|"uses"| node_dashboard_ui
node_dashboard_ui -->|"requests"| node_api
node_api -->|"manages"| node_account_campaign
node_api -->|"serves"| node_inbox
node_api -->|"manages"| node_funnel
node_api -->|"accepts events"| node_webhooks
node_api -->|"handles clicks"| node_click_tracking
node_click_tracking -->|"reads campaign"| node_db_session
node_click_tracking -->|"stores click data"| node_redis
node_click_tracking -->|"redirects visitor"| node_telegram
node_telegram_user -->|"sends activity"| node_telegram
node_telegram -->|"delivers updates"| node_worker
node_worker -->|"consumes click data"| node_redis
node_worker -->|"reads and writes"| node_db_session
node_worker -->|"fires conversions"| node_meta_dispatch
node_meta_dispatch -->|"sends events"| node_meta
node_worker -->|"publishes alerts"| node_redis
node_api -->|"subscribes alerts"| node_redis
node_api -->|"forwards alerts"| node_ws
node_ws -->|"pushes updates"| node_dashboard_ui
node_api -->|"queries and updates"| node_db_session
node_master_bot -->|"manages access"| node_db_session
node_master_bot -->|"serves commands"| node_telegram
node_db_session -->|"reads and writes"| node_db
node_db_session -->|"persists records"| node_conversion_logs
node_external_system -->|"posts conversions"| node_webhooks

click node_dashboard_ui "https://github.com/ahsanka667-ai/tracker/blob/main/dashboard/index.html"
click node_api "https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py"
click node_ws "https://github.com/ahsanka667-ai/tracker/blob/main/service_a/websocket_manager.py"
click node_master_bot "https://github.com/ahsanka667-ai/tracker/blob/main/master_bot/bot.py"
click node_click_tracking "https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py"
click node_worker "https://github.com/ahsanka667-ai/tracker/blob/main/service_b/worker.py"
click node_meta_dispatch "https://github.com/ahsanka667-ai/tracker/blob/main/service_b/meta_capi.py"
click node_account_campaign "https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py"
click node_inbox "https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py"
click node_funnel "https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py"
click node_webhooks "https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py"
click node_conversion_logs "https://github.com/ahsanka667-ai/tracker/blob/main/shared/models.py"
click node_db_session "https://github.com/ahsanka667-ai/tracker/blob/main/shared/database.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_dashboard_ui,node_api,node_ws,node_master_bot,node_account_campaign,node_inbox,node_operator,node_telegram_user toneBlue
class node_click_tracking,node_worker,node_meta_dispatch,node_telegram,node_meta toneAmber
class node_funnel,node_webhooks,node_conversion_logs toneMint
class node_db_session,node_db,node_redis toneRose
class node_external_system toneIndigo
```

## Components

### Dashboard and API

- [Dashboard UI](https://github.com/ahsanka667-ai/tracker/blob/main/dashboard/index.html): `dashboard/index.html`
- [Web API](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py): `service_a/main.py`
- [WebSocket hub](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/websocket_manager.py): `service_a/websocket_manager.py`
- [Master bot](https://github.com/ahsanka667-ai/tracker/blob/main/master_bot/bot.py): `master_bot/bot.py`
- [Accounts and campaigns](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py): `service_a/main.py`
- [Message inbox](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py): `service_a/main.py`

### Telegram tracking

- [Click tracking](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py): `service_a/main.py`
- [Telegram worker](https://github.com/ahsanka667-ai/tracker/blob/main/service_b/worker.py): `service_b/worker.py`
- [Meta CAPI](https://github.com/ahsanka667-ai/tracker/blob/main/service_b/meta_capi.py): `service_b/meta_capi.py`
- **Telegram**
- **Meta platform**

### Conversion analytics

- [Funnels and steps](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py): `service_a/main.py`
- [Inbound webhooks](https://github.com/ahsanka667-ai/tracker/blob/main/service_a/main.py): `service_a/main.py`
- [Conversion logs](https://github.com/ahsanka667-ai/tracker/blob/main/shared/models.py): `shared/models.py`

### Shared platform

- [Database access](https://github.com/ahsanka667-ai/tracker/blob/main/shared/database.py): `shared/database.py`
- **PostgreSQL**
- **Redis**

### Other components

- **Tracker user**
- **Telegram user**
- **External system**

## Connections

- Tracker user → Dashboard UI: uses
- Dashboard UI → Web API: requests
- Web API → Accounts and campaigns: manages
- Web API → Message inbox: serves
- Web API → Funnels and steps: manages
- Web API → Inbound webhooks: accepts events
- Web API → Click tracking: handles clicks
- Click tracking → Database access: reads campaign
- Click tracking → Redis: stores click data
- Click tracking → Telegram: redirects visitor
- Telegram user → Telegram: sends activity
- Telegram → Telegram worker: delivers updates
- Telegram worker → Redis: consumes click data
- Telegram worker → Database access: reads and writes
- Telegram worker → Meta CAPI: fires conversions
- Meta CAPI → Meta platform: sends events
- Telegram worker → Redis: publishes alerts
- Web API → Redis: subscribes alerts
- Web API → WebSocket hub: forwards alerts
- WebSocket hub → Dashboard UI: pushes updates
- Web API → Database access: queries and updates
- Master bot → Database access: manages access
- Master bot → Telegram: serves commands
- Database access → PostgreSQL: reads and writes
- Database access → Conversion logs: persists records
- External system → Inbound webhooks: posts conversions