# zaitherop/voxscope architecture

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

- Interactive diagram: https://gitdiagram.com/zaitherop/voxscope
- Repository: https://github.com/zaitherop/voxscope

## Overview

VoxScope is an analytics layer for collected Telegram data: scheduled workers enrich posts and derive trend and network intelligence, while a protected FastAPI surface serves analyses and reports. PostgreSQL is the shared persistence layer; the README documents sentiment, emotion, topics, embeddings, demographics, trends, link analysis, influence, and narrative reporting. The graph includes those documented capabilities, but unsampled implementations are represented at their exact enclosing directories. The tree does not expose dashboard application source, so it is not modeled as an internal component.

Main entry points: [`backend/database/repository.py`](https://github.com/zaitherop/voxscope/blob/main/backend/database/repository.py) (Analytics repository), [`backend/api/main.py`](https://github.com/zaitherop/voxscope/blob/main/backend/api/main.py) (FastAPI application), [`backend/workers/analyze_posts.py`](https://github.com/zaitherop/voxscope/blob/main/backend/workers/analyze_posts.py) (Post analysis job), [`backend/api/routers/analytics.py`](https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/analytics.py) (Analytics routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_scheduler["Job scheduler<br/>[scheduler.py]"]
  node_analyze["Post analysis job<br/>[analyze_posts.py]"]
  node_graphjob["Graph build job<br/>[build_graph.py]"]
  node_trendjob["Trend job<br/>[compute_trends.py]"]
end

subgraph group_analysis["Post analysis"]
  node_preprocess["Text preprocessing<br/>[preprocess.py]"]
  node_sentiment["Sentiment analysis"]
  node_emotion["Emotion analysis<br/>[emotion_service.py]"]
  node_topic["Topic classification<br/>[topic_service.py]"]
  node_embedding["Post embeddings"]
  node_modelregistry["Model registry<br/>[registry.py]"]
end

subgraph group_intelligence["Network intelligence"]
  node_demographics["Demographics"]
  node_graphservice["Interaction graph<br/>[graph_service.py]"]
  node_influence["Influence scoring"]
  node_trends["Trend detection<br/>[trend_service.py]"]
  node_narrative["Narrative reports"]
  node_llm["Ollama client<br/>[llm_client.py]"]
end

subgraph group_storage["Persistence"]
  node_repository["Analytics repository<br/>[repository.py]"]
  node_postgres[("PostgreSQL<br/>[connection.py]")]
end

subgraph group_api["API surface"]
  node_api["FastAPI application<br/>[main.py]"]
  node_analytics["Analytics routes<br/>[analytics.py]"]
  node_trendroutes["Trend routes<br/>[trends.py]"]
  node_networkroutes["Network routes<br/>[network.py]"]
  node_userroutes["User routes<br/>[users.py]"]
  node_narrativeroutes["Narrative routes<br/>[narrative.py]"]
  node_auth["Admin authentication<br/>[auth.py]"]
end

node_collector(("Telegram collector"))
node_ollama["Ollama service"]
node_dashboard(("Dashboard client"))

node_collector -.->|"stores collected posts"| node_postgres
node_scheduler -->|"dispatches"| node_analyze
node_scheduler -->|"dispatches"| node_graphjob
node_scheduler -->|"dispatches"| node_trendjob
node_analyze -->|"analyzes sentiment"| node_sentiment
node_analyze -->|"analyzes emotion"| node_emotion
node_analyze -->|"classifies topics"| node_topic
node_analyze -->|"embeds posts"| node_embedding
node_analyze -->|"loads and saves"| node_repository
node_preprocess -->|"detects language"| node_modelregistry
node_sentiment -->|"cleans text"| node_preprocess
node_sentiment -->|"loads classifier"| node_modelregistry
node_sentiment -->|"persists results"| node_repository
node_emotion -->|"cleans text"| node_preprocess
node_emotion -->|"loads classifier"| node_modelregistry
node_emotion -->|"persists results"| node_repository
node_topic -->|"uses similarity"| node_embedding
node_topic -->|"loads classifier"| node_modelregistry
node_topic -->|"cleans text"| node_preprocess
node_topic -->|"persists results"| node_repository
node_embedding -->|"loads encoder"| node_modelregistry
node_embedding -->|"uses normalized text"| node_preprocess
node_embedding -->|"reads and writes"| node_repository
node_graphjob -->|"builds profiles"| node_demographics
node_graphjob -->|"builds network"| node_graphservice
node_graphjob -->|"scores authors"| node_influence
node_graphjob -->|"loads and saves"| node_repository
node_graphservice -->|"reads posts and saves edges"| node_repository
node_influence -->|"uses graph metrics"| node_graphservice
node_influence -->|"reads and saves scores"| node_repository
node_trendjob -->|"computes trends"| node_trends
node_trendjob -->|"generates reports"| node_narrative
node_trendjob -->|"loads and saves"| node_repository
node_trends -->|"reads and saves trends"| node_repository
node_narrative -->|"loads facts and saves report"| node_repository
node_narrative -->|"summarizes facts"| node_llm
node_llm -->|"requests generation"| node_ollama
node_api -->|"mounts routes"| node_analytics
node_api -->|"mounts routes"| node_trendroutes
node_api -->|"mounts routes"| node_networkroutes
node_api -->|"mounts routes"| node_userroutes
node_api -->|"mounts routes"| node_narrativeroutes
node_api -->|"applies protection"| node_auth
node_analytics -->|"queries analyses"| node_repository
node_analytics -->|"runs analysis"| node_sentiment
node_analytics -->|"runs analysis"| node_emotion
node_analytics -->|"runs classification"| node_topic
node_analytics -->|"normalizes text"| node_preprocess

click node_scheduler "https://github.com/zaitherop/voxscope/blob/main/backend/workers/scheduler.py"
click node_analyze "https://github.com/zaitherop/voxscope/blob/main/backend/workers/analyze_posts.py"
click node_graphjob "https://github.com/zaitherop/voxscope/blob/main/backend/workers/build_graph.py"
click node_trendjob "https://github.com/zaitherop/voxscope/blob/main/backend/workers/compute_trends.py"
click node_preprocess "https://github.com/zaitherop/voxscope/blob/main/backend/services/preprocess.py"
click node_sentiment "https://github.com/zaitherop/voxscope/blob/main/backend/services/sentiment_service.py"
click node_emotion "https://github.com/zaitherop/voxscope/blob/main/backend/services/emotion_service.py"
click node_topic "https://github.com/zaitherop/voxscope/blob/main/backend/services/topic_service.py"
click node_embedding "https://github.com/zaitherop/voxscope/blob/main/backend/services/embedding_service.py"
click node_modelregistry "https://github.com/zaitherop/voxscope/blob/main/backend/models/registry.py"
click node_demographics "https://github.com/zaitherop/voxscope/blob/main/backend/services/demographics_service.py"
click node_graphservice "https://github.com/zaitherop/voxscope/blob/main/backend/services/graph_service.py"
click node_influence "https://github.com/zaitherop/voxscope/blob/main/backend/services/influence_service.py"
click node_trends "https://github.com/zaitherop/voxscope/blob/main/backend/services/trend_service.py"
click node_narrative "https://github.com/zaitherop/voxscope/blob/main/backend/services/narrative_service.py"
click node_llm "https://github.com/zaitherop/voxscope/blob/main/backend/services/llm_client.py"
click node_api "https://github.com/zaitherop/voxscope/blob/main/backend/api/main.py"
click node_analytics "https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/analytics.py"
click node_trendroutes "https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/trends.py"
click node_networkroutes "https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/network.py"
click node_userroutes "https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/users.py"
click node_narrativeroutes "https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/narrative.py"
click node_auth "https://github.com/zaitherop/voxscope/blob/main/backend/api/auth.py"
click node_repository "https://github.com/zaitherop/voxscope/blob/main/backend/database/repository.py"
click node_postgres "https://github.com/zaitherop/voxscope/blob/main/backend/database/connection.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_scheduler,node_analyze,node_graphjob,node_trendjob,node_dashboard toneBlue
class node_preprocess,node_sentiment,node_emotion,node_topic,node_embedding,node_modelregistry toneAmber
class node_demographics,node_graphservice,node_influence,node_trends,node_narrative,node_llm toneMint
class node_repository,node_postgres toneRose
class node_api,node_analytics,node_trendroutes,node_networkroutes,node_userroutes,node_narrativeroutes,node_auth,node_collector,node_ollama toneIndigo
```

## Components

### Runtime orchestration

- [Job scheduler](https://github.com/zaitherop/voxscope/blob/main/backend/workers/scheduler.py): `backend/workers/scheduler.py`
- [Post analysis job](https://github.com/zaitherop/voxscope/blob/main/backend/workers/analyze_posts.py): `backend/workers/analyze_posts.py`
- [Graph build job](https://github.com/zaitherop/voxscope/blob/main/backend/workers/build_graph.py): `backend/workers/build_graph.py`
- [Trend job](https://github.com/zaitherop/voxscope/blob/main/backend/workers/compute_trends.py): `backend/workers/compute_trends.py`

### Post analysis

- [Text preprocessing](https://github.com/zaitherop/voxscope/blob/main/backend/services/preprocess.py): `backend/services/preprocess.py`
- [Sentiment analysis](https://github.com/zaitherop/voxscope/blob/main/backend/services/sentiment_service.py): `backend/services/sentiment_service.py`
- [Emotion analysis](https://github.com/zaitherop/voxscope/blob/main/backend/services/emotion_service.py): `backend/services/emotion_service.py`
- [Topic classification](https://github.com/zaitherop/voxscope/blob/main/backend/services/topic_service.py): `backend/services/topic_service.py`
- [Post embeddings](https://github.com/zaitherop/voxscope/blob/main/backend/services/embedding_service.py): `backend/services/embedding_service.py`
- [Model registry](https://github.com/zaitherop/voxscope/blob/main/backend/models/registry.py): `backend/models/registry.py`

### Network intelligence

- [Demographics](https://github.com/zaitherop/voxscope/blob/main/backend/services/demographics_service.py): `backend/services/demographics_service.py`
- [Interaction graph](https://github.com/zaitherop/voxscope/blob/main/backend/services/graph_service.py): `backend/services/graph_service.py`
- [Influence scoring](https://github.com/zaitherop/voxscope/blob/main/backend/services/influence_service.py): `backend/services/influence_service.py`
- [Trend detection](https://github.com/zaitherop/voxscope/blob/main/backend/services/trend_service.py): `backend/services/trend_service.py`
- [Narrative reports](https://github.com/zaitherop/voxscope/blob/main/backend/services/narrative_service.py): `backend/services/narrative_service.py`
- [Ollama client](https://github.com/zaitherop/voxscope/blob/main/backend/services/llm_client.py): `backend/services/llm_client.py`

### Persistence

- [Analytics repository](https://github.com/zaitherop/voxscope/blob/main/backend/database/repository.py): `backend/database/repository.py`
- [PostgreSQL](https://github.com/zaitherop/voxscope/blob/main/backend/database/connection.py): `backend/database/connection.py`

### API surface

- [FastAPI application](https://github.com/zaitherop/voxscope/blob/main/backend/api/main.py): `backend/api/main.py`
- [Analytics routes](https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/analytics.py): `backend/api/routers/analytics.py`
- [Trend routes](https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/trends.py): `backend/api/routers/trends.py`
- [Network routes](https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/network.py): `backend/api/routers/network.py`
- [User routes](https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/users.py): `backend/api/routers/users.py`
- [Narrative routes](https://github.com/zaitherop/voxscope/blob/main/backend/api/routers/narrative.py): `backend/api/routers/narrative.py`
- [Admin authentication](https://github.com/zaitherop/voxscope/blob/main/backend/api/auth.py): `backend/api/auth.py`

### Other components

- **Telegram collector**
- **Ollama service**
- **Dashboard client**

## Connections

- Telegram collector → PostgreSQL: stores collected posts
- Job scheduler → Post analysis job: dispatches (evidence: `backend/workers/scheduler.py`)
- Job scheduler → Graph build job: dispatches (evidence: `backend/workers/scheduler.py`)
- Job scheduler → Trend job: dispatches (evidence: `backend/workers/scheduler.py`)
- Post analysis job → Sentiment analysis: analyzes sentiment (evidence: `backend/workers/analyze_posts.py`)
- Post analysis job → Emotion analysis: analyzes emotion (evidence: `backend/workers/analyze_posts.py`)
- Post analysis job → Topic classification: classifies topics (evidence: `backend/workers/analyze_posts.py`)
- Post analysis job → Post embeddings: embeds posts (evidence: `backend/workers/analyze_posts.py`)
- Post analysis job → Analytics repository: loads and saves (evidence: `backend/workers/analyze_posts.py`)
- Text preprocessing → Model registry: detects language (evidence: `backend/services/preprocess.py`)
- Sentiment analysis → Text preprocessing: cleans text (evidence: `backend/services/sentiment_service.py`)
- Sentiment analysis → Model registry: loads classifier (evidence: `backend/services/sentiment_service.py`)
- Sentiment analysis → Analytics repository: persists results (evidence: `backend/services/sentiment_service.py`)
- Emotion analysis → Text preprocessing: cleans text (evidence: `backend/services/emotion_service.py`)
- Emotion analysis → Model registry: loads classifier (evidence: `backend/services/emotion_service.py`)
- Emotion analysis → Analytics repository: persists results (evidence: `backend/services/emotion_service.py`)
- Topic classification → Post embeddings: uses similarity (evidence: `backend/services/topic_service.py`)
- Topic classification → Model registry: loads classifier (evidence: `backend/services/topic_service.py`)
- Topic classification → Text preprocessing: cleans text (evidence: `backend/services/topic_service.py`)
- Topic classification → Analytics repository: persists results (evidence: `backend/services/topic_service.py`)
- Post embeddings → Model registry: loads encoder (evidence: `backend/services/embedding_service.py`)
- Post embeddings → Text preprocessing: uses normalized text (evidence: `backend/services/embedding_service.py`)
- Post embeddings → Analytics repository: reads and writes (evidence: `backend/services/embedding_service.py`)
- Graph build job → Demographics: builds profiles (evidence: `backend/workers/build_graph.py`)
- Graph build job → Interaction graph: builds network (evidence: `backend/workers/build_graph.py`)
- Graph build job → Influence scoring: scores authors (evidence: `backend/workers/build_graph.py`)
- Graph build job → Analytics repository: loads and saves (evidence: `backend/workers/build_graph.py`)
- Interaction graph → Analytics repository: reads posts and saves edges (evidence: `backend/services/graph_service.py`)
- Influence scoring → Interaction graph: uses graph metrics (evidence: `backend/services/influence_service.py`)
- Influence scoring → Analytics repository: reads and saves scores (evidence: `backend/services/influence_service.py`)
- Trend job → Trend detection: computes trends (evidence: `backend/workers/compute_trends.py`)
- Trend job → Narrative reports: generates reports (evidence: `backend/workers/compute_trends.py`)
- Trend job → Analytics repository: loads and saves (evidence: `backend/workers/compute_trends.py`)
- Trend detection → Analytics repository: reads and saves trends (evidence: `backend/services/trend_service.py`)
- Narrative reports → Analytics repository: loads facts and saves report (evidence: `backend/services/narrative_service.py`)
- Narrative reports → Ollama client: summarizes facts (evidence: `backend/services/narrative_service.py`)
- Ollama client → Ollama service: requests generation (evidence: `backend/services/llm_client.py`)
- FastAPI application → Analytics routes: mounts routes (evidence: `backend/api/main.py`)
- FastAPI application → Trend routes: mounts routes (evidence: `backend/api/main.py`)
- FastAPI application → Network routes: mounts routes (evidence: `backend/api/main.py`)
- FastAPI application → User routes: mounts routes (evidence: `backend/api/main.py`)
- FastAPI application → Narrative routes: mounts routes (evidence: `backend/api/main.py`)
- FastAPI application → Admin authentication: applies protection (evidence: `backend/api/main.py`)
- Analytics routes → Analytics repository: queries analyses (evidence: `backend/api/routers/analytics.py`)
- Analytics routes → Sentiment analysis: runs analysis (evidence: `backend/api/routers/analytics.py`)
- Analytics routes → Emotion analysis: runs analysis (evidence: `backend/api/routers/analytics.py`)
- Analytics routes → Topic classification: runs classification (evidence: `backend/api/routers/analytics.py`)
- Analytics routes → Text preprocessing: normalizes text (evidence: `backend/api/routers/analytics.py`)
