# unicodeveloper/globalthreatmap architecture

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

## Overview

Global Threat & Event Intelligence Map is an OSINT dashboard for exploring live security events, country conflict intelligence, military and hazard layers, and research dossiers. The principal workflow loads event data into the dashboard, classifies it for map/feed presentation, and lets analysts inspect locations or research entities. Country conflicts and deep research are separate on-demand workflows; prediction markets and authentication add supporting capabilities. Edges reflect shown imports/calls or README-documented behavior; some route internals and unsampled integrations remain uncertain.

Main entry points: [`components/map/threat-map.tsx`](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/map/threat-map.tsx) (Threat Map), [`app/page.tsx`](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/page.tsx) (Dashboard), [`components/search/entity-search.tsx`](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/search/entity-search.tsx) (Entity Research), [`app/api/events/route.ts`](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/events/route.ts) (Event API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Situational Dashboard"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_event_hook["Event Loader<br/>[use-events.ts]"]
  node_map["Threat Map<br/>[threat-map.tsx]"]
  node_feed["Event Feed<br/>[event-feed.tsx]"]
  node_sidebar["Research Sidebar<br/>[sidebar.tsx]"]
end

subgraph group_intelligence["Research Intelligence"]
  node_conflicts["Country Conflicts"]
  node_entity_search["Entity Research<br/>[entity-search.tsx]"]
  node_markets["Threat Markets"]
  node_alerts["Alert Rules"]
end

subgraph group_services["Data Services"]
  node_event_api["Event API<br/>[route.ts]"]
  node_event_processing["Event Classification<br/>[ai-classifier.ts]"]
  node_valyu["Valyu Client<br/>[valyu.ts]"]
  node_conflict_api["Conflict API<br/>[route.ts]"]
  node_entities_api["Entity API<br/>[route.ts]"]
  node_geocoding["Location Extraction<br/>[geocoding.ts]"]
  node_research_api["Deep Research API<br/>[route.ts]"]
  node_research_tasks["Research Task Status<br/>[route.ts]"]
  node_market_client["Market Client<br/>[polymarket.ts]"]
  node_bases_api["Military Base Data<br/>[route.ts]"]
  node_hazard_apis["Hazard Layers"]
end

subgraph group_state["Client State"]
  node_map_state["Map State<br/>[map-store.ts]"]
  node_event_state["Event State<br/>[events-store.ts]"]
  node_auth_state["Auth State<br/>[auth-store.ts]"]
end

node_analyst(("Analyst"))
node_valyu_service["Valyu Search Service"]
node_mapbox["Mapbox"]

node_analyst -->|"opens"| node_dashboard
node_dashboard -->|"loads events"| node_event_hook
node_dashboard -->|"renders"| node_map
node_dashboard -->|"renders"| node_sidebar
node_event_hook -->|"updates"| node_event_state
node_event_hook -.->|"fetches events"| node_event_api
node_event_api -->|"searches"| node_valyu
node_event_api -->|"classifies"| node_event_processing
node_event_api -.->|"queries"| node_valyu_service
node_map -->|"reads and updates"| node_map_state
node_map -->|"reads events"| node_event_state
node_map -->|"opens details"| node_conflicts
node_map -.->|"renders map"| node_mapbox
node_sidebar -->|"renders"| node_feed
node_sidebar -->|"renders"| node_entity_search
node_feed -->|"selects location"| node_map_state
node_conflicts -.->|"requests conflicts"| node_conflict_api
node_conflict_api -.->|"synthesizes conflict data"| node_valyu
node_entity_search -.->|"researches entities"| node_entities_api
node_entities_api -->|"researches profiles"| node_valyu
node_entities_api -->|"extracts locations"| node_geocoding
node_entity_search -->|"sets locations"| node_map_state
node_entity_search -.->|"starts dossier"| node_research_api
node_research_api -.->|"starts research"| node_valyu
node_research_tasks -.->|"polls research"| node_valyu
node_entity_search -.->|"polls task"| node_research_tasks
node_dashboard -->|"renders panel"| node_markets
node_markets -->|"loads markets"| node_market_client
node_map -.->|"loads bases"| node_bases_api
node_map -.->|"loads layers"| node_hazard_apis
node_analyst -.->|"configures alerts"| node_alerts
node_auth_state -.->|"provides access token"| node_event_api

click node_dashboard "https://github.com/unicodeveloper/globalthreatmap/blob/main/app/page.tsx"
click node_event_hook "https://github.com/unicodeveloper/globalthreatmap/blob/main/hooks/use-events.ts"
click node_map "https://github.com/unicodeveloper/globalthreatmap/blob/main/components/map/threat-map.tsx"
click node_feed "https://github.com/unicodeveloper/globalthreatmap/blob/main/components/feed/event-feed.tsx"
click node_sidebar "https://github.com/unicodeveloper/globalthreatmap/blob/main/components/sidebar.tsx"
click node_map_state "https://github.com/unicodeveloper/globalthreatmap/blob/main/stores/map-store.ts"
click node_event_state "https://github.com/unicodeveloper/globalthreatmap/blob/main/stores/events-store.ts"
click node_auth_state "https://github.com/unicodeveloper/globalthreatmap/blob/main/stores/auth-store.ts"
click node_event_api "https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/events/route.ts"
click node_event_processing "https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/ai-classifier.ts"
click node_valyu "https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/valyu.ts"
click node_conflicts "https://github.com/unicodeveloper/globalthreatmap/blob/main/components/map/country-conflicts-modal.tsx"
click node_conflict_api "https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/countries/conflicts/route.ts"
click node_entity_search "https://github.com/unicodeveloper/globalthreatmap/blob/main/components/search/entity-search.tsx"
click node_entities_api "https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/entities/route.ts"
click node_geocoding "https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/geocoding.ts"
click node_research_api "https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/deepresearch/route.ts"
click node_research_tasks "https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/deepresearch/%5BtaskId%5D/route.ts"
click node_markets "https://github.com/unicodeveloper/globalthreatmap/blob/main/components/threat-markets-panel.tsx"
click node_market_client "https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/polymarket.ts"
click node_bases_api "https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/military-bases/route.ts"
click node_hazard_apis "https://github.com/unicodeveloper/globalthreatmap/tree/main/app/api"

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_dashboard,node_event_hook,node_map,node_feed,node_sidebar toneBlue
class node_conflicts,node_entity_search,node_markets,node_alerts toneAmber
class node_event_api,node_event_processing,node_valyu,node_conflict_api,node_entities_api,node_geocoding,node_research_api,node_research_tasks,node_market_client,node_bases_api,node_hazard_apis toneMint
class node_map_state,node_event_state,node_auth_state toneRose
class node_analyst,node_valyu_service,node_mapbox toneIndigo
```

## Components

### Situational Dashboard

- [Dashboard](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/page.tsx): `app/page.tsx`
- [Event Loader](https://github.com/unicodeveloper/globalthreatmap/blob/main/hooks/use-events.ts): `hooks/use-events.ts`
- [Threat Map](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/map/threat-map.tsx): `components/map/threat-map.tsx`
- [Event Feed](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/feed/event-feed.tsx): `components/feed/event-feed.tsx`
- [Research Sidebar](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/sidebar.tsx): `components/sidebar.tsx`

### Research Intelligence

- [Country Conflicts](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/map/country-conflicts-modal.tsx): `components/map/country-conflicts-modal.tsx`
- [Entity Research](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/search/entity-search.tsx): `components/search/entity-search.tsx`
- [Threat Markets](https://github.com/unicodeveloper/globalthreatmap/blob/main/components/threat-markets-panel.tsx): `components/threat-markets-panel.tsx`
- **Alert Rules**

### Data Services

- [Event API](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/events/route.ts): `app/api/events/route.ts`
- [Event Classification](https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/ai-classifier.ts): `lib/ai-classifier.ts`
- [Valyu Client](https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/valyu.ts): `lib/valyu.ts`
- [Conflict API](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/countries/conflicts/route.ts): `app/api/countries/conflicts/route.ts`
- [Entity API](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/entities/route.ts): `app/api/entities/route.ts`
- [Location Extraction](https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/geocoding.ts): `lib/geocoding.ts`
- [Deep Research API](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/deepresearch/route.ts): `app/api/deepresearch/route.ts`
- [Research Task Status](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/deepresearch/%5BtaskId%5D/route.ts): `app/api/deepresearch/[taskId]/route.ts`
- [Market Client](https://github.com/unicodeveloper/globalthreatmap/blob/main/lib/polymarket.ts): `lib/polymarket.ts`
- [Military Base Data](https://github.com/unicodeveloper/globalthreatmap/blob/main/app/api/military-bases/route.ts): `app/api/military-bases/route.ts`
- [Hazard Layers](https://github.com/unicodeveloper/globalthreatmap/tree/main/app/api): `app/api`

### Client State

- [Map State](https://github.com/unicodeveloper/globalthreatmap/blob/main/stores/map-store.ts): `stores/map-store.ts`
- [Event State](https://github.com/unicodeveloper/globalthreatmap/blob/main/stores/events-store.ts): `stores/events-store.ts`
- [Auth State](https://github.com/unicodeveloper/globalthreatmap/blob/main/stores/auth-store.ts): `stores/auth-store.ts`

### Other components

- **Analyst**
- **Valyu Search Service**
- **Mapbox**

## Connections

- Analyst → Dashboard: opens (evidence: `app/page.tsx`)
- Dashboard → Event Loader: loads events (evidence: `app/page.tsx`)
- Dashboard → Threat Map: renders (evidence: `app/page.tsx`)
- Dashboard → Research Sidebar: renders (evidence: `app/page.tsx`)
- Event Loader → Event State: updates (evidence: `hooks/use-events.ts`)
- Event Loader → Event API: fetches events (evidence: `README.md`)
- Event API → Valyu Client: searches (evidence: `app/api/events/route.ts`)
- Event API → Event Classification: classifies (evidence: `app/api/events/route.ts`)
- Event API → Valyu Search Service: queries (evidence: `README.md`)
- Threat Map → Map State: reads and updates (evidence: `components/map/threat-map.tsx`)
- Threat Map → Event State: reads events (evidence: `components/map/threat-map.tsx`)
- Threat Map → Country Conflicts: opens details (evidence: `components/map/threat-map.tsx`)
- Threat Map → Mapbox: renders map (evidence: `README.md`)
- Research Sidebar → Event Feed: renders (evidence: `components/sidebar.tsx`)
- Research Sidebar → Entity Research: renders (evidence: `components/sidebar.tsx`)
- Event Feed → Map State: selects location
- Country Conflicts → Conflict API: requests conflicts (evidence: `README.md`)
- Conflict API → Valyu Client: synthesizes conflict data (evidence: `README.md`)
- Entity Research → Entity API: researches entities (evidence: `README.md`)
- Entity API → Valyu Client: researches profiles (evidence: `app/api/entities/route.ts`)
- Entity API → Location Extraction: extracts locations (evidence: `app/api/entities/route.ts`)
- Entity Research → Map State: sets locations (evidence: `components/search/entity-search.tsx`)
- Entity Research → Deep Research API: starts dossier (evidence: `README.md`)
- Deep Research API → Valyu Client: starts research (evidence: `README.md`)
- Research Task Status → Valyu Client: polls research (evidence: `README.md`)
- Entity Research → Research Task Status: polls task (evidence: `README.md`)
- Dashboard → Threat Markets: renders panel (evidence: `app/page.tsx`)
- Threat Markets → Market Client: loads markets (evidence: `components/threat-markets-panel.tsx`)
- Threat Map → Military Base Data: loads bases (evidence: `README.md`)
- Threat Map → Hazard Layers: loads layers (evidence: `README.md`)
- Analyst → Alert Rules: configures alerts (evidence: `README.md`)
- Auth State → Event API: provides access token (evidence: `README.md`)
