# zone24uzz/tg-auto architecture

> Architecture diagram of the GitHub repository zone24uzz/tg-auto, 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/zone24uzz/tg-auto
- Repository: https://github.com/zone24uzz/tg-auto

## Overview

This is a Telegram account auto-responder with business-bot and opt-in userbot transports. Incoming messages are normalized and persisted, queued, then processed through rules, media understanding, personal-question triage, AI generation, response safeguards and Telegram delivery; uncertain or personal cases are handed to the owner through the admin bot. The README documents these capabilities, but unsampled modules limit which internal calls can be asserted, so some documented links are dashed. PostgreSQL supports durable queueing and encrypted history; the admin surface also manages settings, rules, history, privacy and usage.

Main entry points: [`src/responder/pipeline.ts`](https://github.com/zone24uzz/tg-auto/blob/main/src/responder/pipeline.ts) (Reply pipeline), [`src/telegram/main/business.handlers.ts`](https://github.com/zone24uzz/tg-auto/blob/main/src/telegram/main/business.handlers.ts) (Business updates), [`src/database/client.ts`](https://github.com/zone24uzz/tg-auto/blob/main/src/database/client.ts) (PostgreSQL), [`src/ai/router/ai-router.ts`](https://github.com/zone24uzz/tg-auto/blob/main/src/ai/router/ai-router.ts) (AI router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Telegram ingress"]
  node_entry["Runtime entry<br/>[main.ts]"]
  node_business["Business updates"]
  node_userbot["Userbot transport"]
end

subgraph group_reply["Reply processing"]
  node_pipeline["Reply pipeline<br/>[pipeline.ts]"]
  node_rules["Rules and modes<br/>[rules.engine.ts]"]
  node_policy["Response policy<br/>[response-policy.ts]"]
  node_sender["Telegram sender<br/>[reply-sender.ts]"]
end

subgraph group_ai_media["AI and media"]
  node_media["Media understanding<br/>[media.service.ts]"]
  node_classifier["Personal triage<br/>[classifier.ts]"]
  node_context["Prompt context<br/>[context-builder.ts]"]
  node_ai["AI router<br/>[ai-router.ts]"]
  node_providers["AI providers"]
end

subgraph group_owner_admin["Owner controls"]
  node_attention["Owner attention"]
  node_admin["Admin bot"]
  node_settings["Settings and rules UI"]
end

subgraph group_platform["Data and operations"]
  node_messages[("Message history")]
  node_queue["Postgres job queue<br/>[pg-queue.ts]"]
  node_worker["Worker runner<br/>[worker-runner.ts]"]
  node_storage[("Raw media storage<br/>[storage.ts]")]
  node_audit[("Audit log<br/>[audit.service.ts]")]
  node_privacy["Privacy and retention<br/>[privacy.service.ts]"]
  node_stats[("Usage statistics<br/>[usage.service.ts]")]
  node_db[("PostgreSQL<br/>[client.ts]")]
end

node_telegram(("Telegram chats"))

node_telegram -->|"sends updates"| node_business
node_entry -->|"starts"| node_business
node_entry -->|"starts"| node_admin
node_telegram -.->|"MTProto chats"| node_userbot
node_business -->|"stores messages"| node_messages
node_business -->|"enqueues work"| node_queue
node_worker -->|"claims jobs"| node_queue
node_worker -.->|"runs replies"| node_pipeline
node_pipeline -->|"checks rules"| node_rules
node_pipeline -->|"processes media"| node_media
node_pipeline -->|"triages questions"| node_classifier
node_pipeline -->|"builds context"| node_context
node_pipeline -.->|"requests generation"| node_ai
node_ai -.->|"dispatches calls"| node_providers
node_pipeline -.->|"filters reply"| node_policy
node_pipeline -.->|"sends reply"| node_sender
node_pipeline -->|"queues owner cases"| node_attention
node_attention -->|"notifies owner"| node_admin
node_admin -.->|"routes controls"| node_settings
node_settings -.->|"records changes"| node_audit
node_privacy -.->|"deletes user data"| node_messages
node_privacy -.->|"cleans media"| node_storage
node_media -.->|"retains media"| node_storage
node_messages -->|"reads and writes"| node_db
node_queue -->|"persists jobs"| node_db
node_audit -->|"writes audit rows"| node_db
node_stats -.->|"records usage"| node_db
node_ai -->|"tracks usage"| node_stats

click node_entry "https://github.com/zone24uzz/tg-auto/blob/main/src/main.ts"
click node_business "https://github.com/zone24uzz/tg-auto/blob/main/src/telegram/main/business.handlers.ts"
click node_userbot "https://github.com/zone24uzz/tg-auto/tree/main/src/telegram/userbot"
click node_messages "https://github.com/zone24uzz/tg-auto/blob/main/src/messages/message.repository.ts"
click node_queue "https://github.com/zone24uzz/tg-auto/blob/main/src/queues/pg-queue.ts"
click node_worker "https://github.com/zone24uzz/tg-auto/blob/main/src/workers/worker-runner.ts"
click node_pipeline "https://github.com/zone24uzz/tg-auto/blob/main/src/responder/pipeline.ts"
click node_rules "https://github.com/zone24uzz/tg-auto/blob/main/src/rules/rules.engine.ts"
click node_media "https://github.com/zone24uzz/tg-auto/blob/main/src/media/media.service.ts"
click node_storage "https://github.com/zone24uzz/tg-auto/blob/main/src/media/storage/storage.ts"
click node_classifier "https://github.com/zone24uzz/tg-auto/blob/main/src/classifiers/classifier.ts"
click node_context "https://github.com/zone24uzz/tg-auto/blob/main/src/conversations/context-builder.ts"
click node_ai "https://github.com/zone24uzz/tg-auto/blob/main/src/ai/router/ai-router.ts"
click node_providers "https://github.com/zone24uzz/tg-auto/tree/main/src/ai/providers"
click node_policy "https://github.com/zone24uzz/tg-auto/blob/main/src/responder/response-policy.ts"
click node_sender "https://github.com/zone24uzz/tg-auto/blob/main/src/responder/reply-sender.ts"
click node_attention "https://github.com/zone24uzz/tg-auto/blob/main/src/owner-attention/attention.service.ts"
click node_admin "https://github.com/zone24uzz/tg-auto/tree/main/src/telegram/admin"
click node_settings "https://github.com/zone24uzz/tg-auto/tree/main/src/telegram/admin/views"
click node_audit "https://github.com/zone24uzz/tg-auto/blob/main/src/audit/audit.service.ts"
click node_privacy "https://github.com/zone24uzz/tg-auto/blob/main/src/privacy/privacy.service.ts"
click node_stats "https://github.com/zone24uzz/tg-auto/blob/main/src/statistics/usage.service.ts"
click node_db "https://github.com/zone24uzz/tg-auto/blob/main/src/database/client.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_entry,node_business,node_userbot toneBlue
class node_pipeline,node_rules,node_policy,node_sender toneAmber
class node_media,node_classifier,node_context,node_ai,node_providers toneMint
class node_attention,node_admin,node_settings toneRose
class node_messages,node_queue,node_worker,node_storage,node_audit,node_privacy,node_stats,node_db,node_telegram toneIndigo
```

## Components

### Telegram ingress

- [Runtime entry](https://github.com/zone24uzz/tg-auto/blob/main/src/main.ts): `src/main.ts`
- [Business updates](https://github.com/zone24uzz/tg-auto/blob/main/src/telegram/main/business.handlers.ts): `src/telegram/main/business.handlers.ts`
- [Userbot transport](https://github.com/zone24uzz/tg-auto/tree/main/src/telegram/userbot): `src/telegram/userbot`

### Reply processing

- [Reply pipeline](https://github.com/zone24uzz/tg-auto/blob/main/src/responder/pipeline.ts): `src/responder/pipeline.ts`
- [Rules and modes](https://github.com/zone24uzz/tg-auto/blob/main/src/rules/rules.engine.ts): `src/rules/rules.engine.ts`
- [Response policy](https://github.com/zone24uzz/tg-auto/blob/main/src/responder/response-policy.ts): `src/responder/response-policy.ts`
- [Telegram sender](https://github.com/zone24uzz/tg-auto/blob/main/src/responder/reply-sender.ts): `src/responder/reply-sender.ts`

### AI and media

- [Media understanding](https://github.com/zone24uzz/tg-auto/blob/main/src/media/media.service.ts): `src/media/media.service.ts`
- [Personal triage](https://github.com/zone24uzz/tg-auto/blob/main/src/classifiers/classifier.ts): `src/classifiers/classifier.ts`
- [Prompt context](https://github.com/zone24uzz/tg-auto/blob/main/src/conversations/context-builder.ts): `src/conversations/context-builder.ts`
- [AI router](https://github.com/zone24uzz/tg-auto/blob/main/src/ai/router/ai-router.ts): `src/ai/router/ai-router.ts`
- [AI providers](https://github.com/zone24uzz/tg-auto/tree/main/src/ai/providers): `src/ai/providers`

### Owner controls

- [Owner attention](https://github.com/zone24uzz/tg-auto/blob/main/src/owner-attention/attention.service.ts): `src/owner-attention/attention.service.ts`
- [Admin bot](https://github.com/zone24uzz/tg-auto/tree/main/src/telegram/admin): `src/telegram/admin`
- [Settings and rules UI](https://github.com/zone24uzz/tg-auto/tree/main/src/telegram/admin/views): `src/telegram/admin/views`

### Data and operations

- [Message history](https://github.com/zone24uzz/tg-auto/blob/main/src/messages/message.repository.ts): `src/messages/message.repository.ts`
- [Postgres job queue](https://github.com/zone24uzz/tg-auto/blob/main/src/queues/pg-queue.ts): `src/queues/pg-queue.ts`
- [Worker runner](https://github.com/zone24uzz/tg-auto/blob/main/src/workers/worker-runner.ts): `src/workers/worker-runner.ts`
- [Raw media storage](https://github.com/zone24uzz/tg-auto/blob/main/src/media/storage/storage.ts): `src/media/storage/storage.ts`
- [Audit log](https://github.com/zone24uzz/tg-auto/blob/main/src/audit/audit.service.ts): `src/audit/audit.service.ts`
- [Privacy and retention](https://github.com/zone24uzz/tg-auto/blob/main/src/privacy/privacy.service.ts): `src/privacy/privacy.service.ts`
- [Usage statistics](https://github.com/zone24uzz/tg-auto/blob/main/src/statistics/usage.service.ts): `src/statistics/usage.service.ts`
- [PostgreSQL](https://github.com/zone24uzz/tg-auto/blob/main/src/database/client.ts): `src/database/client.ts`

### Other components

- **Telegram chats**

## Connections

- Telegram chats → Business updates: sends updates (evidence: `README.md`)
- Runtime entry → Business updates: starts (evidence: `src/main.ts`)
- Runtime entry → Admin bot: starts (evidence: `src/main.ts`)
- Telegram chats → Userbot transport: MTProto chats (evidence: `README.md`)
- Business updates → Message history: stores messages (evidence: `src/telegram/main/business.handlers.ts`)
- Business updates → Postgres job queue: enqueues work (evidence: `src/telegram/main/business.handlers.ts`)
- Worker runner → Postgres job queue: claims jobs (evidence: `src/workers/worker-runner.ts`)
- Worker runner → Reply pipeline: runs replies
- Reply pipeline → Rules and modes: checks rules (evidence: `src/responder/pipeline.ts`)
- Reply pipeline → Media understanding: processes media (evidence: `src/responder/pipeline.ts`)
- Reply pipeline → Personal triage: triages questions (evidence: `src/responder/pipeline.ts`)
- Reply pipeline → Prompt context: builds context (evidence: `src/responder/pipeline.ts`)
- Reply pipeline → AI router: requests generation
- AI router → AI providers: dispatches calls
- Reply pipeline → Response policy: filters reply (evidence: `src/responder/pipeline.ts`)
- Reply pipeline → Telegram sender: sends reply (evidence: `src/responder/pipeline.ts`)
- Reply pipeline → Owner attention: queues owner cases (evidence: `src/responder/pipeline.ts`)
- Owner attention → Admin bot: notifies owner (evidence: `src/owner-attention/attention.service.ts`)
- Admin bot → Settings and rules UI: routes controls (evidence: `src/telegram/admin/views/main.ts`)
- Settings and rules UI → Audit log: records changes
- Privacy and retention → Message history: deletes user data
- Privacy and retention → Raw media storage: cleans media (evidence: `src/privacy/privacy.service.ts`)
- Media understanding → Raw media storage: retains media (evidence: `src/media/media.service.ts`)
- Message history → PostgreSQL: reads and writes (evidence: `src/messages/message.repository.ts`)
- Postgres job queue → PostgreSQL: persists jobs (evidence: `src/queues/pg-queue.ts`)
- Audit log → PostgreSQL: writes audit rows (evidence: `src/audit/audit.service.ts`)
- Usage statistics → PostgreSQL: records usage (evidence: `src/statistics/usage.service.ts`)
- AI router → Usage statistics: tracks usage (evidence: `src/ai/router/ai-router.ts`)
