# iandreafc/gdeltnews architecture

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

## Overview

gdeltnews turns GDELT Web News NGrams into filtered article datasets: users can download minute files, reconstruct article text from overlapping fragments, then Boolean-filter and deduplicate CSV output. The Tkinter GUI exposes download, reconstruction, filtering, and recap workflows over the same package capabilities. Arrows reflect documented or excerpted calls; unsampled internals are represented only where the README documents a capability.

Main entry points: [`GUI/main.py`](https://github.com/iandreafc/gdeltnews/blob/main/GUI/main.py) (Desktop GUI), [`src/gdeltnews/download.py`](https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/download.py) (Minute downloader), [`src/gdeltnews/reconstruct.py`](https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/reconstruct.py) (Batch orchestrator), [`src/gdeltnews/filtermerge.py`](https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/filtermerge.py) (Query and deduplicate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_gui["Desktop GUI<br/>[main.py]"]
end

subgraph group_acquisition["Data acquisition"]
  node_download["Minute downloader<br/>[download.py]"]
  node_gdelt["GDELT files"]
  node_rawfiles["Compressed inputs"]
end

subgraph group_reconstruction["Article reconstruction"]
  node_reconstruct["Batch orchestrator<br/>[reconstruct.py]"]
  node_wordmatch["Fragment matcher<br/>[wordmatch.py]"]
  node_articles["Article CSVs"]
end

subgraph group_selection["Filtering and export"]
  node_filtermerge["Query and deduplicate<br/>[filtermerge.py]"]
  node_finalcsv["Filtered CSV"]
end

node_user(("Research user"))

node_user -->|"operates"| node_gui
node_user -->|"requests range"| node_download
node_download -->|"fetches files"| node_gdelt
node_download -->|"writes files"| node_rawfiles
node_user -->|"runs reconstruction"| node_reconstruct
node_rawfiles -->|"reads inputs"| node_reconstruct
node_reconstruct -->|"dispatches files"| node_wordmatch
node_wordmatch -->|"writes articles"| node_articles
node_user -->|"sets query"| node_filtermerge
node_articles -->|"reads CSVs"| node_filtermerge
node_filtermerge -->|"filters and deduplicates"| node_finalcsv
node_gui -->|"invokes"| node_download
node_gui -->|"invokes"| node_reconstruct
node_gui -->|"invokes"| node_filtermerge

click node_gui "https://github.com/iandreafc/gdeltnews/blob/main/GUI/main.py"
click node_download "https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/download.py"
click node_reconstruct "https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/reconstruct.py"
click node_wordmatch "https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/wordmatch.py"
click node_filtermerge "https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/filtermerge.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_gui,node_user toneBlue
class node_download,node_gdelt,node_rawfiles toneAmber
class node_reconstruct,node_wordmatch,node_articles toneMint
class node_filtermerge,node_finalcsv toneRose
```

## Components

### User interface

- [Desktop GUI](https://github.com/iandreafc/gdeltnews/blob/main/GUI/main.py): `GUI/main.py`

### Data acquisition

- [Minute downloader](https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/download.py): `src/gdeltnews/download.py`
- **GDELT files**
- **Compressed inputs**

### Article reconstruction

- [Batch orchestrator](https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/reconstruct.py): `src/gdeltnews/reconstruct.py`
- [Fragment matcher](https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/wordmatch.py): `src/gdeltnews/wordmatch.py`
- **Article CSVs**

### Filtering and export

- [Query and deduplicate](https://github.com/iandreafc/gdeltnews/blob/main/src/gdeltnews/filtermerge.py): `src/gdeltnews/filtermerge.py`
- **Filtered CSV**

### Other components

- **Research user**

## Connections

- Research user → Desktop GUI: operates (evidence: `GUI/main.py`)
- Research user → Minute downloader: requests range (evidence: `README.md`)
- Minute downloader → GDELT files: fetches files (evidence: `README.md`)
- Minute downloader → Compressed inputs: writes files (evidence: `src/gdeltnews/download.py`)
- Research user → Batch orchestrator: runs reconstruction (evidence: `README.md`)
- Compressed inputs → Batch orchestrator: reads inputs (evidence: `src/gdeltnews/reconstruct.py`)
- Batch orchestrator → Fragment matcher: dispatches files (evidence: `src/gdeltnews/reconstruct.py`)
- Fragment matcher → Article CSVs: writes articles (evidence: `src/gdeltnews/wordmatch.py`)
- Research user → Query and deduplicate: sets query (evidence: `README.md`)
- Article CSVs → Query and deduplicate: reads CSVs (evidence: `README.md`)
- Query and deduplicate → Filtered CSV: filters and deduplicates (evidence: `src/gdeltnews/filtermerge.py`)
- Desktop GUI → Minute downloader: invokes (evidence: `GUI/main.py`)
- Desktop GUI → Batch orchestrator: invokes (evidence: `GUI/main.py`)
- Desktop GUI → Query and deduplicate: invokes (evidence: `GUI/main.py`)
