How zaitherop/voxscope works
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: repository.py Analytics repository · main.py FastAPI application · analyze_posts.py Post analysis job · analytics.py Analytics routes
Components 28
Runtime orchestration
- Job scheduler
backend/workers/scheduler.py - Post analysis job
backend/workers/analyze_posts.py - Graph build job
backend/workers/build_graph.py - Trend job
backend/workers/compute_trends.py
Post analysis
- Text preprocessing
backend/services/preprocess.py - Sentiment analysis
backend/services/sentiment_service.py - Emotion analysis
backend/services/emotion_service.py - Topic classification
backend/services/topic_service.py - Post embeddings
backend/services/embedding_service.py - Model registry
backend/models/registry.py
Network intelligence
- Demographics
backend/services/demographics_service.py - Interaction graph
backend/services/graph_service.py - Influence scoring
backend/services/influence_service.py - Trend detection
backend/services/trend_service.py - Narrative reports
backend/services/narrative_service.py - Ollama client
backend/services/llm_client.py
Persistence
- Analytics repository
backend/database/repository.py - PostgreSQL
backend/database/connection.py
API surface
- FastAPI application
backend/api/main.py - Analytics routes
backend/api/routers/analytics.py - Trend routes
backend/api/routers/trends.py - Network routes
backend/api/routers/network.py - User routes
backend/api/routers/users.py - Narrative routes
backend/api/routers/narrative.py - Admin authentication
backend/api/auth.py
Other components
- Telegram collector
- Ollama service
- Dashboard client
Connections 48
- Telegram collector → PostgreSQL: stores collected posts
- Job scheduler → Post analysis job: dispatches
backend/workers/scheduler.py - Job scheduler → Graph build job: dispatches
backend/workers/scheduler.py - Job scheduler → Trend job: dispatches
backend/workers/scheduler.py - Post analysis job → Sentiment analysis: analyzes sentiment
backend/workers/analyze_posts.py - Post analysis job → Emotion analysis: analyzes emotion
backend/workers/analyze_posts.py - Post analysis job → Topic classification: classifies topics
backend/workers/analyze_posts.py - Post analysis job → Post embeddings: embeds posts
backend/workers/analyze_posts.py - Post analysis job → Analytics repository: loads and saves
backend/workers/analyze_posts.py - Text preprocessing → Model registry: detects language
backend/services/preprocess.py - Sentiment analysis → Text preprocessing: cleans text
backend/services/sentiment_service.py - Sentiment analysis → Model registry: loads classifier
backend/services/sentiment_service.py - Sentiment analysis → Analytics repository: persists results
backend/services/sentiment_service.py - Emotion analysis → Text preprocessing: cleans text
backend/services/emotion_service.py - Emotion analysis → Model registry: loads classifier
backend/services/emotion_service.py - Emotion analysis → Analytics repository: persists results
backend/services/emotion_service.py - Topic classification → Post embeddings: uses similarity
backend/services/topic_service.py - Topic classification → Model registry: loads classifier
backend/services/topic_service.py - Topic classification → Text preprocessing: cleans text
backend/services/topic_service.py - Topic classification → Analytics repository: persists results
backend/services/topic_service.py - Post embeddings → Model registry: loads encoder
backend/services/embedding_service.py - Post embeddings → Text preprocessing: uses normalized text
backend/services/embedding_service.py - Post embeddings → Analytics repository: reads and writes
backend/services/embedding_service.py - Graph build job → Demographics: builds profiles
backend/workers/build_graph.py - Graph build job → Interaction graph: builds network
backend/workers/build_graph.py - Graph build job → Influence scoring: scores authors
backend/workers/build_graph.py - Graph build job → Analytics repository: loads and saves
backend/workers/build_graph.py - Interaction graph → Analytics repository: reads posts and saves edges
backend/services/graph_service.py - Influence scoring → Interaction graph: uses graph metrics
backend/services/influence_service.py - Influence scoring → Analytics repository: reads and saves scores
backend/services/influence_service.py - Trend job → Trend detection: computes trends
backend/workers/compute_trends.py - Trend job → Narrative reports: generates reports
backend/workers/compute_trends.py - Trend job → Analytics repository: loads and saves
backend/workers/compute_trends.py - Trend detection → Analytics repository: reads and saves trends
backend/services/trend_service.py - Narrative reports → Analytics repository: loads facts and saves report
backend/services/narrative_service.py - Narrative reports → Ollama client: summarizes facts
backend/services/narrative_service.py - Ollama client → Ollama service: requests generation
backend/services/llm_client.py - FastAPI application → Analytics routes: mounts routes
backend/api/main.py - FastAPI application → Trend routes: mounts routes
backend/api/main.py - FastAPI application → Network routes: mounts routes
backend/api/main.py - FastAPI application → User routes: mounts routes
backend/api/main.py - FastAPI application → Narrative routes: mounts routes
backend/api/main.py - FastAPI application → Admin authentication: applies protection
backend/api/main.py - Analytics routes → Analytics repository: queries analyses
backend/api/routers/analytics.py - Analytics routes → Sentiment analysis: runs analysis
backend/api/routers/analytics.py - Analytics routes → Emotion analysis: runs analysis
backend/api/routers/analytics.py - Analytics routes → Topic classification: runs classification
backend/api/routers/analytics.py - Analytics routes → Text preprocessing: normalizes text
backend/api/routers/analytics.py