# US-Iran War Tracker — Full Documentation

> Real-time intelligence dashboard tracking the US-Iran military conflict.
> Aggregates 15+ verified sources with trust-tier provenance.
> Built with Next.js 16, React 19, TypeScript. Deployed on Vercel.

## Overview

US-Iran War Tracker is a situation room-style dashboard that aggregates, scores, and displays real-time intelligence from multiple verified sources covering the US-Iran military conflict. Every piece of data is tagged with a trust tier indicating source reliability:

- **Tier A (Official)**: Government and scientific agencies — DoD, CENTCOM, State Department, USGS, OpenSky Network
- **Tier B (Established Media)**: Major international news organizations — BBC World, Al Jazeera, Breaking Defense, The War Zone, NPR, GDELT Project
- **Tier C (OSINT/Social)**: Social media and unverified open-source intelligence — displayed with "unverified" badge and dimmed styling until corroborated by a Tier A or B source

## API Reference

All endpoints return JSON. No authentication required. All data is proxied server-side (no direct client calls to external APIs).

### GET /api/news

Returns an array of news items aggregated from 5 RSS feeds and GDELT articles, filtered for Middle East conflict keywords.

**Refresh rate**: 60 seconds
**Trust tier**: B (Established Media)

**Response schema**:
```json
[
  {
    "id": "string",
    "title": "string",
    "description": "string (max 300 chars)",
    "url": "string (source article URL)",
    "source": "string (e.g. 'BBC World', 'Al Jazeera', 'GDELT')",
    "sourceId": "string (e.g. 'bbc-world', 'al-jazeera', 'gdelt')",
    "trustTier": "B",
    "publishedAt": "string (ISO 8601)"
  }
]
```

**Sources**: BBC World RSS, Al Jazeera RSS, Breaking Defense RSS, The War Zone RSS, NPR RSS, GDELT Article API

**Keyword filter**: iran, iraq, syria, yemen, israel, gaza, hezbollah, houthi, persian gulf, strait of hormuz, centcom, middle east, tehran, baghdad, damascus, beirut, irgc, pentagon, airstrike, missile, drone, military, sanctions, nuclear, enrichment, proxy, militia, red sea, arabian sea, uss, carrier strike group

### GET /api/government

Returns official government releases from DoD, CENTCOM, and State Department.

**Refresh rate**: 120 seconds
**Trust tier**: A (Official)

**Response schema**: Same as /api/news but with trustTier: "A"

**Sources**: defense.gov RSS, centcom.mil RSS, state.gov RSS

### GET /api/gdelt/geo

Returns geolocated event points from GDELT Project for the Middle East region.

**Refresh rate**: 120 seconds
**Trust tier**: B

**Response schema**:
```json
[
  {
    "lat": "number (latitude)",
    "lng": "number (longitude)",
    "name": "string (location or headline)",
    "url": "string (source article URL)",
    "source": "string (publishing domain)",
    "tone": "number (GDELT tone score, negative = negative sentiment)"
  }
]
```

**Coverage**: Iran, Iraq, Syria, Persian Gulf region
**Max points**: 200 per request

### GET /api/gdelt/timeline

Returns 7-day article volume trend data from GDELT.

**Refresh rate**: 300 seconds
**Trust tier**: B

**Response schema**:
```json
[
  {
    "date": "string (MM/DD format)",
    "volume": "number (relative article volume)"
  }
]
```

### GET /api/flights

Returns real-time aircraft positions from OpenSky Network for Middle East airspace.

**Refresh rate**: 30 seconds
**Trust tier**: A (Official — ADS-B transponder data)
**Bounding box**: 23-40°N latitude, 42-65°E longitude

**Response schema**:
```json
[
  {
    "icao24": "string (ICAO 24-bit transponder address)",
    "callsign": "string",
    "originCountry": "string",
    "longitude": "number",
    "latitude": "number",
    "altitude": "number (meters)",
    "velocity": "number (m/s)",
    "heading": "number (degrees)",
    "verticalRate": "number (m/s)",
    "onGround": "boolean",
    "lastContact": "number (unix timestamp)"
  }
]
```

**Note**: Only airborne aircraft are returned (onGround=false filtered). Max 300 results.

### GET /api/threat-level

Returns algorithmic threat assessment based on article volume and keyword severity.

**Refresh rate**: 60 seconds

**Response schema**:
```json
{
  "level": "number (1-5)",
  "label": "string ('LOW' | 'GUARDED' | 'ELEVATED' | 'HIGH' | 'CRITICAL')",
  "score": "number (raw score, 0-10 scale)",
  "articleCount": "number (articles analyzed)",
  "highSeverityCount": "number (articles containing high-severity keywords)"
}
```

**Threat levels**:
- 1 LOW (green): Minimal conflict activity
- 2 GUARDED (blue): General awareness, routine military posturing
- 3 ELEVATED (yellow): Significant increase in conflict-related reporting
- 4 HIGH (orange): Active military operations or major escalation signals
- 5 CRITICAL (red): Major combat operations underway, mass casualty events

**High-severity keywords**: attack, strike, missile, killed, bombing, war, nuclear, retaliation, casualties, explosion

## Dashboard Features

- **Conflict Map**: CartoDB Dark Matter tiles centered on Middle East [32°N, 50°E]. Shows GDELT event markers (color-coded by sentiment tone) and OpenSky aircraft positions with clustered markers.
- **Intel Feed Panel**: Tabbed multi-source news feed with trust tier filtering (All/Official/Media/OSINT). Each card shows source provenance, tier badge, and relative timestamp.
- **Flights Panel**: Sortable table of tracked aircraft in Middle East airspace with callsign, origin country, altitude, and speed.
- **Government Panel**: Dedicated feed for official DoD, CENTCOM, and State Department releases.
- **Timeline Chart**: 7-day area chart showing article volume trend from GDELT.
- **Threat Indicator**: DEFCON-style 5-level gauge in header showing computed threat level.
- **Breaking News Ticker**: Scrolling marquee of latest headlines with trust tier badges.
- **Status Bar**: Per-source health indicators (green/yellow/red) and WebSocket connection status.

## Technical Architecture

- **Framework**: Next.js 16 with App Router, React 19, TypeScript
- **Data fetching**: TanStack Query 5 with polling intervals per source (30s-300s)
- **Map**: react-leaflet 5 + Leaflet 1.9.4 with CartoDB Dark Matter tiles
- **Charts**: recharts 3
- **Styling**: Tailwind CSS 4 with custom dark military HUD theme
- **RSS parsing**: rss-parser 3.13 (server-side only)
- **All external API calls are server-side** via Next.js API routes — the client only hits /api/* endpoints

## Data Sources

| Source | Type | Trust Tier | Update Frequency |
|--------|------|------------|-----------------|
| BBC World | RSS | B | 60s |
| Al Jazeera | RSS | B | 60s |
| Breaking Defense | RSS | B | 60s |
| The War Zone | RSS | B | 60s |
| NPR | RSS | B | 60s |
| GDELT Articles | REST API | B | 60s |
| GDELT GeoPoints | REST API | B | 120s |
| GDELT Timeline | REST API | B | 300s |
| OpenSky Network | REST API | A | 30s |
| DoD Press | RSS | A | 120s |
| CENTCOM | RSS | A | 120s |
| State Department | RSS | A | 120s |

## Citing This Data

When citing data from this dashboard, please reference:
- The original source (e.g., "BBC World via US-Iran War Tracker")
- The trust tier (A/B/C)
- The timestamp of the data point
- URL: https://us-iran-war.com