# sergioyesenin/tg_post_analyzer architecture

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

## Overview

tg_post_analyzer is a Telegram analytics application: it ingests channel posts and comments, links related posts into events and processes, and produces AI-assisted reports for analyst-facing dashboards and detail views. The README documents separate API, scheduler, Telegram-ingestion, and AI-worker runtimes, plus asynchronous jobs for long-running operations. The graph emphasizes the user-facing API-to-workspace flow and the documented analysis stages. Several router and frontend implementation files were not sampled, so their connections are based on README statements; source-level wiring is shown only where the index or excerpts support it.

Main entry points: [`db/models.py`](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/db/models.py) (PostgreSQL data), [`services/pipeline_runtime.py`](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/pipeline_runtime.py) (Pipeline runtime), [`api/routers`](https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/api/routers) (Domain API routes), [`services/reporting.py`](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/reporting.py) (Report generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_spa["React workspace<br/>[App.tsx]"]
  node_workspace["Analytics views"]
  node_report_ui["Reports UI<br/>[ReportsPage.tsx]"]
  node_admin_ui["Admin and ops"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and access"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_domain_routes["Domain API routes"]
end

subgraph group_ingest["Collection and analysis"]
  node_ingestion["Ingestion pipeline<br/>[ingestion_core.py]"]
  node_linking["Post linking<br/>[no_llm_pipeline.py]"]
  node_events["Event building<br/>[build_events.py]"]
  node_processes["Process building<br/>[build_processes.py]"]
  node_dashboards["Dashboard queries"]
end

subgraph group_reports["Reporting and jobs"]
  node_job_store["Job queue<br/>[jobs.py]"]
  node_runtime["Pipeline runtime"]
  node_reporting["Report generation<br/>[reporting.py]"]
  node_report_v2["Report pipelines"]
end

subgraph group_data["Persistence and integrations"]
  node_tg_client["Telegram client<br/>[telegram.py]"]
  node_llm["LLM provider<br/>[openai_client.py]"]
  node_settings["Runtime settings<br/>[settings_store.py]"]
  node_database[("PostgreSQL data<br/>[models.py]")]
end

node_analyst(("Analyst"))
node_telegram{{"Telegram"}}
node_external_llm{{"External LLM<br/>external system"}}

node_analyst -->|"uses"| node_spa
node_spa -.->|"requests"| node_api_client
node_api_client -.->|"calls API"| node_fastapi
node_fastapi -->|"registers routes"| node_auth
node_fastapi -->|"registers routes"| node_domain_routes
node_auth -->|"reads/writes"| node_database
node_domain_routes -.->|"serves dashboards"| node_workspace
node_domain_routes -.->|"serves reports"| node_report_ui
node_domain_routes -.->|"serves admin"| node_admin_ui
node_workspace -.->|"requests data"| node_dashboards
node_telegram -.->|"provides messages"| node_tg_client
node_tg_client -.->|"collects messages"| node_ingestion
node_ingestion -->|"stores posts"| node_database
node_runtime -->|"runs ingestion"| node_ingestion
node_runtime -->|"runs linking"| node_linking
node_runtime -->|"rebuilds events"| node_events
node_runtime -->|"rebuilds processes"| node_processes
node_linking -->|"reads/writes links"| node_database
node_events -->|"reads/writes events"| node_database
node_processes -->|"reads/writes processes"| node_database
node_runtime -.->|"dispatches jobs"| node_job_store
node_job_store -->|"persists jobs"| node_database
node_runtime -.->|"runs reports"| node_reporting
node_reporting -->|"uses pipeline"| node_report_v2
node_report_v2 -->|"requests completions"| node_llm
node_report_v2 -.->|"loads analysis data"| node_database
node_reporting -.->|"stores reports"| node_database
node_llm -.->|"calls provider"| node_external_llm
node_reporting -->|"loads settings"| node_settings
node_settings -->|"reads settings"| node_database
node_dashboards -.->|"queries data"| node_database

click node_spa "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/frontend/src/app/App.tsx"
click node_workspace "https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/frontend/src/modules/workspace"
click node_report_ui "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/frontend/src/modules/reports/ReportsPage.tsx"
click node_admin_ui "https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/frontend/src/modules/admin"
click node_api_client "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/frontend/src/shared/api/client.ts"
click node_fastapi "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/api/main.py"
click node_auth "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/api/routers/auth.py"
click node_domain_routes "https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/api/routers"
click node_tg_client "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/client/telegram.py"
click node_ingestion "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/ingestion_core.py"
click node_linking "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/linking/no_llm_pipeline.py"
click node_events "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/events/build_events.py"
click node_processes "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/processes/build_processes.py"
click node_dashboards "https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/services/dashboard"
click node_job_store "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/jobs.py"
click node_runtime "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/pipeline_runtime.py"
click node_reporting "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/reporting.py"
click node_report_v2 "https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/services/reporting_v2"
click node_llm "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/llm/openai_client.py"
click node_settings "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/settings_store.py"
click node_database "https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/db/models.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_spa,node_workspace,node_report_ui,node_admin_ui,node_api_client toneBlue
class node_fastapi,node_auth,node_domain_routes toneAmber
class node_ingestion,node_linking,node_events,node_processes,node_dashboards toneMint
class node_job_store,node_runtime,node_reporting,node_report_v2 toneRose
class node_tg_client,node_llm,node_settings,node_database,node_analyst,node_telegram,node_external_llm toneIndigo
```

## Components

### Web application

- [React workspace](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Analytics views](https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/frontend/src/modules/workspace): `frontend/src/modules/workspace`
- [Reports UI](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/frontend/src/modules/reports/ReportsPage.tsx): `frontend/src/modules/reports/ReportsPage.tsx`
- [Admin and ops](https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/frontend/src/modules/admin): `frontend/src/modules/admin`
- [API client](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/frontend/src/shared/api/client.ts): `frontend/src/shared/api/client.ts`

### API and access

- [FastAPI application](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/api/main.py): `api/main.py`
- [Authentication](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/api/routers/auth.py): `api/routers/auth.py`
- [Domain API routes](https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/api/routers): `api/routers`

### Collection and analysis

- [Ingestion pipeline](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/ingestion_core.py): `services/ingestion_core.py`
- [Post linking](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/linking/no_llm_pipeline.py): `services/linking/no_llm_pipeline.py`
- [Event building](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/events/build_events.py): `services/events/build_events.py`
- [Process building](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/processes/build_processes.py): `services/processes/build_processes.py`
- [Dashboard queries](https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/services/dashboard): `services/dashboard`

### Reporting and jobs

- [Job queue](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/jobs.py): `services/jobs.py`
- [Pipeline runtime](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/pipeline_runtime.py): `services/pipeline_runtime.py`
- [Report generation](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/reporting.py): `services/reporting.py`
- [Report pipelines](https://github.com/sergioyesenin/tg_post_analyzer/tree/experiment/services/reporting_v2): `services/reporting_v2`

### Persistence and integrations

- [Telegram client](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/client/telegram.py): `client/telegram.py`
- [LLM provider](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/llm/openai_client.py): `services/llm/openai_client.py`
- [Runtime settings](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/services/settings_store.py): `services/settings_store.py`
- [PostgreSQL data](https://github.com/sergioyesenin/tg_post_analyzer/blob/experiment/db/models.py): `db/models.py`

### Other components

- **Analyst**
- **Telegram**
- **External LLM**: external system

## Connections

- Analyst → React workspace: uses (evidence: `README.md`)
- React workspace → API client: requests (evidence: `README.md`)
- API client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Authentication: registers routes (evidence: `api/main.py`)
- FastAPI application → Domain API routes: registers routes (evidence: `api/main.py`)
- Authentication → PostgreSQL data: reads/writes (evidence: `api/routers/auth.py`)
- Domain API routes → Analytics views: serves dashboards (evidence: `README.md`)
- Domain API routes → Reports UI: serves reports (evidence: `README.md`)
- Domain API routes → Admin and ops: serves admin (evidence: `README.md`)
- Analytics views → Dashboard queries: requests data (evidence: `README.md`)
- Telegram → Telegram client: provides messages (evidence: `README.md`)
- Telegram client → Ingestion pipeline: collects messages (evidence: `services/pipeline_runtime.py`)
- Ingestion pipeline → PostgreSQL data: stores posts (evidence: `services/ingestion_core.py`)
- Pipeline runtime → Ingestion pipeline: runs ingestion (evidence: `services/pipeline_runtime.py`)
- Pipeline runtime → Post linking: runs linking (evidence: `services/pipeline_runtime.py`)
- Pipeline runtime → Event building: rebuilds events (evidence: `services/pipeline_runtime.py`)
- Pipeline runtime → Process building: rebuilds processes (evidence: `services/pipeline_runtime.py`)
- Post linking → PostgreSQL data: reads/writes links (evidence: `services/linking/no_llm_pipeline.py`)
- Event building → PostgreSQL data: reads/writes events (evidence: `services/events/build_events.py`)
- Process building → PostgreSQL data: reads/writes processes (evidence: `services/processes/build_processes.py`)
- Pipeline runtime → Job queue: dispatches jobs (evidence: `services/pipeline_runtime.py`)
- Job queue → PostgreSQL data: persists jobs (evidence: `services/jobs.py`)
- Pipeline runtime → Report generation: runs reports (evidence: `services/pipeline_runtime.py`)
- Report generation → Report pipelines: uses pipeline (evidence: `services/reporting.py`)
- Report pipelines → LLM provider: requests completions (evidence: `services/reporting_v2/event_pipeline.py`)
- Report pipelines → PostgreSQL data: loads analysis data (evidence: `services/reporting_v2/event_pipeline.py`)
- Report generation → PostgreSQL data: stores reports (evidence: `services/reporting.py`)
- LLM provider → External LLM: calls provider
- Report generation → Runtime settings: loads settings (evidence: `services/reporting.py`)
- Runtime settings → PostgreSQL data: reads settings (evidence: `services/settings_store.py`)
- Dashboard queries → PostgreSQL data: queries data (evidence: `README.md`)
