Yerevan Eye

Real-time geospatial intelligence console that fuses flights, earthquakes, satellites, wildfires, weather, air quality, and breaking news into a single 3D tactical display. An AI investigator agent continuously correlates events across layers and delivers prioritized briefings.

Features

• Full-screen tactical UI with Normal and NVG display modes
• Live data layers:
  • Flights (OpenSky)
  • Earthquakes (USGS)
  • Satellites (Space-Track primary, Celestrak fallback)
  • Active fire / wildfire hotspots (NASA FIRMS)
  • Weather probes (Open-Meteo)
  • Air quality (Open-Meteo primary, IQAir fallback)
  • Geolocated Armenia news (multi-source RSS + Google/Yandex geocoding)
• NDVI-lite vegetation imagery overlay (NASA GIBS)
• AI-powered intel feed with lifecycle state, deterministic scoring, and cross-layer correlation
• CSV export for any active layer snapshot
• Layer-level TTL with stale-data fallback and automatic provider failover
• Graceful degradation — the console never goes dark when keys are missing or APIs fail

Architecture

• Backend: FastAPI + normalized polling pipeline with SSE streaming and HTTP snapshot fallback (yerevan_eye/api/)
• Frontend: React + TypeScript + CesiumJS + Resium (frontend/)
• AI: OpenRouter (Gemini) for intel enrichment and correlation briefing (deterministic fallback if unavailable)
• Data model: LayerSnapshot / LayerRecord adapters with TTL + stale fallback

Getting Started

1. Install Python dependencies:

uv sync --extra dev

2. Configure API keys:

cp .env.example .env
# set OPENROUTER_API_KEY for AI (optional)
# set IQAIR_API_KEY for IQAir fallback in air-quality layer (optional)
# set GOOGLE_MAPS_API_KEY for primary news geocoding (optional)
# set YANDEX_GEOCODER_API_KEY for news geocoding fallback (optional)

3. Configure non-secret settings in config.yaml (includes provider/endpoint rate limits).

4. Run backend API:

uv run python main_api.py

5. Run frontend (new terminal):

cd frontend
npm install
npm run dev

6. Optional — Cesium terrain + buildings:

echo 'VITE_CESIUM_ION_TOKEN=your_token_here' >> frontend/.env

Frontend: http://127.0.0.1:5173 | Backend: http://127.0.0.1:8000

Tests

Backend:

uv run ruff check .
uv run pytest

Frontend:

cd frontend
npm test
npm run build
npm run test:e2e

Run hooks manually across the repository:

uv run pre-commit run --all-files

GitHub Actions runs hooks automatically through prek in .github/workflows/quality.yml.

Documentation

Technical docs are maintained in docs/.

Notes

• AI copilot is active by default for backend intel enrichment. If OPENROUTER_API_KEY is missing, the runtime stays live in degraded deterministic mode.
• Air-quality defaults to Open-Meteo (no API key required). If IQAIR_API_KEY is missing, only IQAir fallback is disabled.
• News geocoding uses Google primary (GOOGLE_MAPS_API_KEY) and Yandex fallback (YANDEX_GEOCODER_API_KEY). If both are missing/invalid, location handling falls back to lower-confidence city/country resolution.
• Backend exposes compatibility API at /api/v1/* and richer intel contract at /api/v2/*.

License

This project is licensed under the MIT License.