# krpaul/theworldincolour architecture

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

- Interactive diagram: https://gitdiagram.com/krpaul/theworldincolour
- Repository: https://github.com/krpaul/theworldincolour

## Overview

The World in Colour serves a country-level news-negativity heatmap on a globe and lets users find petitions related to a selected area. Its principal runtime path is the Flask app’s heatmap endpoint, which converts ranked country data and capital coordinates into map points for the frontend; a separate endpoint resolves a nearby country and fetches Change.org results. The repository also includes an offline news collection, manual-labeling, and sentiment-ranking workflow. The frontend and some offline wiring are represented by paths in the tree and README, but their source was not sampled, so uncertain connections are omitted.

Main entry points: [`app.py`](https://github.com/krpaul/theworldincolour/blob/main/app.py) (Flask routes), [`templates/index.html`](https://github.com/krpaul/theworldincolour/blob/main/templates/index.html) (Globe interface), [`heatmap/news.py`](https://github.com/krpaul/theworldincolour/blob/main/heatmap/news.py) (News collection), [`heatmap/sentiment.py`](https://github.com/krpaul/theworldincolour/blob/main/heatmap/sentiment.py) (Sentiment scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Web experience"]
  node_flask["Flask routes<br/>[app.py]"]
  node_rankdata["Map data<br/>[data.py]"]
  node_countrydata[("Rank and geography")]
  node_globeui["Globe interface<br/>[index.html]"]
  node_webgl["Globe renderer"]
  node_texture["Globe texture"]
end

subgraph group_scoring["News scoring"]
  node_newscollect["News collection<br/>[news.py]"]
  node_articledata[("Article dataset")]
  node_labeling["Manual labeling<br/>[classify.py]"]
  node_labeleddata[("Labeled articles")]
  node_sentiment["Sentiment scoring<br/>[sentiment.py]"]
  node_scores[("Country scores")]
end

subgraph group_actions["Regional action"]
  node_nearest["Nearest capital<br/>[app.py]"]
  node_charity["Petition search<br/>[grab.py]"]
end

node_visitor(("Visitor"))
node_newsapi["NewsAPI"]
node_googlenews["Google News"]
node_cohere["Cohere model"]
node_changeorg["Change.org"]

node_visitor -->|"uses"| node_globeui
node_globeui -->|"requests"| node_flask
node_flask -->|"loads map data"| node_rankdata
node_rankdata -->|"reads"| node_countrydata
node_flask -->|"returns heat points"| node_globeui
node_globeui -->|"renders globe"| node_webgl
node_webgl -->|"loads texture"| node_texture
node_newscollect -.->|"queries"| node_newsapi
node_newscollect -->|"queries"| node_googlenews
node_newscollect -->|"writes headlines"| node_articledata
node_articledata -->|"provides articles"| node_labeling
node_labeling -->|"writes labels"| node_labeleddata
node_sentiment -->|"reads headlines"| node_countrydata
node_sentiment -->|"classifies headlines"| node_cohere
node_sentiment -->|"writes rankings"| node_scores
node_visitor -->|"selects region"| node_globeui
node_globeui -->|"requests charities"| node_flask
node_flask -->|"resolves coordinates"| node_nearest
node_nearest -->|"reads capitals"| node_countrydata
node_flask -->|"searches country"| node_charity
node_charity -->|"scrapes results"| node_changeorg
node_flask -->|"returns petitions"| node_globeui

click node_flask "https://github.com/krpaul/theworldincolour/blob/main/app.py"
click node_rankdata "https://github.com/krpaul/theworldincolour/blob/main/data.py"
click node_countrydata "https://github.com/krpaul/theworldincolour/tree/main/heatmap"
click node_globeui "https://github.com/krpaul/theworldincolour/blob/main/templates/index.html"
click node_webgl "https://github.com/krpaul/theworldincolour/tree/main/static/js/webgl-globe"
click node_texture "https://github.com/krpaul/theworldincolour/tree/main/globe"
click node_newscollect "https://github.com/krpaul/theworldincolour/blob/main/heatmap/news.py"
click node_articledata "https://github.com/krpaul/theworldincolour/tree/main/heatmap/classification"
click node_labeling "https://github.com/krpaul/theworldincolour/blob/main/heatmap/classification/classify.py"
click node_labeleddata "https://github.com/krpaul/theworldincolour/tree/main/heatmap/classification"
click node_sentiment "https://github.com/krpaul/theworldincolour/blob/main/heatmap/sentiment.py"
click node_scores "https://github.com/krpaul/theworldincolour/tree/main/heatmap"
click node_nearest "https://github.com/krpaul/theworldincolour/blob/main/app.py"
click node_charity "https://github.com/krpaul/theworldincolour/blob/main/charity/grab.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_flask,node_rankdata,node_countrydata,node_globeui,node_webgl,node_texture toneBlue
class node_newscollect,node_articledata,node_labeling,node_labeleddata,node_sentiment,node_scores toneAmber
class node_nearest,node_charity,node_newsapi toneMint
class node_visitor,node_googlenews,node_cohere,node_changeorg toneIndigo
```

## Components

### Web experience

- [Flask routes](https://github.com/krpaul/theworldincolour/blob/main/app.py): `app.py`
- [Map data](https://github.com/krpaul/theworldincolour/blob/main/data.py): `data.py`
- [Rank and geography](https://github.com/krpaul/theworldincolour/tree/main/heatmap): `heatmap`
- [Globe interface](https://github.com/krpaul/theworldincolour/blob/main/templates/index.html): `templates/index.html`
- [Globe renderer](https://github.com/krpaul/theworldincolour/tree/main/static/js/webgl-globe): `static/js/webgl-globe`
- [Globe texture](https://github.com/krpaul/theworldincolour/tree/main/globe): `globe`

### News scoring

- [News collection](https://github.com/krpaul/theworldincolour/blob/main/heatmap/news.py): `heatmap/news.py`
- [Article dataset](https://github.com/krpaul/theworldincolour/tree/main/heatmap/classification): `heatmap/classification`
- [Manual labeling](https://github.com/krpaul/theworldincolour/blob/main/heatmap/classification/classify.py): `heatmap/classification/classify.py`
- [Labeled articles](https://github.com/krpaul/theworldincolour/tree/main/heatmap/classification): `heatmap/classification`
- [Sentiment scoring](https://github.com/krpaul/theworldincolour/blob/main/heatmap/sentiment.py): `heatmap/sentiment.py`
- [Country scores](https://github.com/krpaul/theworldincolour/tree/main/heatmap): `heatmap`

### Regional action

- [Nearest capital](https://github.com/krpaul/theworldincolour/blob/main/app.py): `app.py`
- [Petition search](https://github.com/krpaul/theworldincolour/blob/main/charity/grab.py): `charity/grab.py`

### Other components

- **Visitor**
- **NewsAPI**
- **Google News**
- **Cohere model**
- **Change.org**

## Connections

- Visitor → Globe interface: uses
- Globe interface → Flask routes: requests
- Flask routes → Map data: loads map data
- Map data → Rank and geography: reads
- Flask routes → Globe interface: returns heat points
- Globe interface → Globe renderer: renders globe
- Globe renderer → Globe texture: loads texture
- News collection → NewsAPI: queries
- News collection → Google News: queries
- News collection → Article dataset: writes headlines
- Article dataset → Manual labeling: provides articles
- Manual labeling → Labeled articles: writes labels
- Sentiment scoring → Rank and geography: reads headlines
- Sentiment scoring → Cohere model: classifies headlines
- Sentiment scoring → Country scores: writes rankings
- Visitor → Globe interface: selects region
- Globe interface → Flask routes: requests charities
- Flask routes → Nearest capital: resolves coordinates
- Nearest capital → Rank and geography: reads capitals
- Flask routes → Petition search: searches country
- Petition search → Change.org: scrapes results
- Flask routes → Globe interface: returns petitions