# keerthanasathish985-beep/ghostsignal architecture

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

- Interactive diagram: https://gitdiagram.com/keerthanasathish985-beep/ghostsignal
- Repository: https://github.com/keerthanasathish985-beep/ghostsignal

## Overview

GhostSignal is an investigation and text-analysis application. Its visible API workflow accepts a topic, obtains a classifier and investigation service, and returns collected records with sentiment statistics and a timeline; it also exposes single-text and batch classification. The classifier loads separate sentiment and authenticity pipelines. The tree documents broader collection, analysis, and reporting capabilities, but most of those modules were not sampled, so their runtime connections are not asserted. The frontend entry point renders the main app; its API behavior was not inspected.

Main entry points: [`src/model/train.py`](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/train.py) (Model training), [`src/services/investigation_service.py`](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/services/investigation_service.py) (Investigation service), [`src/model/classifier.py`](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/classifier.py) (Prediction classifier), [`app.py`](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/app.py) (Flask API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface and API"]
  node_frontend["Web application<br/>[App.tsx]"]
  node_frontend_entry["App entry point<br/>[main.tsx]"]
  node_api["Flask API<br/>[app.py]"]
end

subgraph group_investigation["Investigation and collection"]
  node_service["Investigation service"]
  node_news["GDELT news collection<br/>[gdelt_collector.py]"]
  node_discussions["Discussion collection"]
  node_other_collectors["Other source collectors"]
end

subgraph group_analysis["Analysis and reporting"]
  node_preprocessing["Text preprocessing"]
  node_sentiment_analysis["Sentiment analysis<br/>[engagement.py]"]
  node_coordination["Coordination analysis<br/>[coordination.py]"]
  node_similarity["Similarity analysis<br/>[similarity.py]"]
  node_timeline["Timeline analysis<br/>[timeline.py]"]
  node_reporting["Report generation"]
end

subgraph group_models["Classification models"]
  node_classifier["Prediction classifier<br/>[classifier.py]"]
  node_training["Model training<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_training_data["Training dataset<br/>[training_data.csv]"]
  node_sentiment_model["Sentiment pipeline"]
  node_authenticity_model["Authenticity pipeline"]
end

node_user(("User"))
node_gdelt["GDELT API"]
node_hn["Hacker News"]

node_user -->|"uses"| node_frontend
node_frontend_entry -->|"renders"| node_frontend
node_api -->|"predicts with"| node_classifier
node_api -->|"invokes"| node_service
node_service -.->|"collects through"| node_news
node_service -.->|"collects through"| node_discussions
node_news -->|"requests articles"| node_gdelt
node_training -.->|"loads data"| node_training_data
node_training -->|"evaluates with"| node_evaluation
node_training -->|"writes pipeline"| node_sentiment_model
node_training -->|"writes pipeline"| node_authenticity_model
node_classifier -->|"loads pipeline"| node_sentiment_model
node_classifier -->|"loads pipeline"| node_authenticity_model

click node_frontend "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/frontend/src/App.tsx"
click node_frontend_entry "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/frontend/src/main.tsx"
click node_api "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/app.py"
click node_service "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/services/investigation_service.py"
click node_news "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/collectors/news/gdelt_collector.py"
click node_discussions "https://github.com/keerthanasathish985-beep/ghostsignal/tree/main/src/collectors/discussions"
click node_other_collectors "https://github.com/keerthanasathish985-beep/ghostsignal/tree/main/src/collectors"
click node_preprocessing "https://github.com/keerthanasathish985-beep/ghostsignal/tree/main/src/preprocessing"
click node_sentiment_analysis "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/engagement.py"
click node_coordination "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/coordination.py"
click node_similarity "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/similarity.py"
click node_timeline "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/timeline.py"
click node_reporting "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/reporting/report_generator.py"
click node_classifier "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/classifier.py"
click node_training "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/train.py"
click node_evaluation "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/evaluate.py"
click node_training_data "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/data/training/training_data.csv"
click node_sentiment_model "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/models/sentiment_pipeline.joblib"
click node_authenticity_model "https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/models/authenticity_pipeline.joblib"

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_frontend,node_frontend_entry,node_api,node_user toneBlue
class node_service,node_news,node_discussions,node_other_collectors toneAmber
class node_preprocessing,node_sentiment_analysis,node_coordination,node_similarity,node_timeline,node_reporting,node_gdelt toneMint
class node_classifier,node_training,node_evaluation,node_training_data,node_sentiment_model,node_authenticity_model toneRose
class node_hn toneIndigo
```

## Components

### User interface and API

- [Web application](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [App entry point](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Flask API](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/app.py): `app.py`

### Investigation and collection

- [Investigation service](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/services/investigation_service.py): `src/services/investigation_service.py`
- [GDELT news collection](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/collectors/news/gdelt_collector.py): `src/collectors/news/gdelt_collector.py`
- [Discussion collection](https://github.com/keerthanasathish985-beep/ghostsignal/tree/main/src/collectors/discussions): `src/collectors/discussions`
- [Other source collectors](https://github.com/keerthanasathish985-beep/ghostsignal/tree/main/src/collectors): `src/collectors`

### Analysis and reporting

- [Text preprocessing](https://github.com/keerthanasathish985-beep/ghostsignal/tree/main/src/preprocessing): `src/preprocessing`
- [Sentiment analysis](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/engagement.py): `src/analysis/engagement.py`
- [Coordination analysis](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/coordination.py): `src/analysis/coordination.py`
- [Similarity analysis](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/similarity.py): `src/analysis/similarity.py`
- [Timeline analysis](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/analysis/timeline.py): `src/analysis/timeline.py`
- [Report generation](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/reporting/report_generator.py): `src/reporting/report_generator.py`

### Classification models

- [Prediction classifier](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/classifier.py): `src/model/classifier.py`
- [Model training](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/train.py): `src/model/train.py`
- [Model evaluation](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/src/model/evaluate.py): `src/model/evaluate.py`
- [Training dataset](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/data/training/training_data.csv): `data/training/training_data.csv`
- [Sentiment pipeline](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/models/sentiment_pipeline.joblib): `models/sentiment_pipeline.joblib`
- [Authenticity pipeline](https://github.com/keerthanasathish985-beep/ghostsignal/blob/main/models/authenticity_pipeline.joblib): `models/authenticity_pipeline.joblib`

### Other components

- **User**
- **GDELT API**
- **Hacker News**

## Connections

- User → Web application: uses
- App entry point → Web application: renders (evidence: `frontend/src/main.tsx`)
- Flask API → Prediction classifier: predicts with (evidence: `app.py`)
- Flask API → Investigation service: invokes (evidence: `app.py`)
- Investigation service → GDELT news collection: collects through
- Investigation service → Discussion collection: collects through
- GDELT news collection → GDELT API: requests articles (evidence: `src/collectors/news/gdelt_collector.py`)
- Model training → Training dataset: loads data
- Model training → Model evaluation: evaluates with (evidence: `src/model/train.py`)
- Model training → Sentiment pipeline: writes pipeline (evidence: `src/model/train.py`)
- Model training → Authenticity pipeline: writes pipeline (evidence: `src/model/train.py`)
- Prediction classifier → Sentiment pipeline: loads pipeline (evidence: `src/model/classifier.py`)
- Prediction classifier → Authenticity pipeline: loads pipeline (evidence: `src/model/classifier.py`)
