VICTOR — Vectorized Intelligence for Conflict Tracking & Operational Reporting

Overview

VICTOR is a production-grade geopolitical intelligence platform that synthesizes real-time data from 12+ authoritative sources into a unified situational awareness dashboard. It combines multi-provider LLM reasoning, Bayesian risk forecasting, agent-based simulation, and geospatial analysis — built for intelligence analysts, humanitarian organizations, and operational planning teams.

---

Architecture

Backend

• FastAPI (async) with SQLAlchemy 2.0 + AsyncPG; 64 router modules
• PostgreSQL + PostGIS via Neon for all geospatial queries; 26 Alembic migrations tracking full schema history
• Redis for distributed rate limiting, cache control, and job locking
• APScheduler running 19 scheduled ETL jobs with task ownership for multi-worker deployments
• Multi-provider LLM registry — OpenAI, Anthropic (Claude), Google Gemini with circuit-breaker failover and semantic LLM cache
• Security middleware stack: HSTS, CSP, X-Frame-Options, CORS dynamic origin detection, structured request logging

Frontend

• React 19 + Vite SPA with React Router 7 and TanStack Query 5 for server-state management
• Mapping layer: Leaflet (clustering, heatmaps, draw tools), Mapbox GL, MapLibre GL, Cesium/Resium for 3D geospatial visualization
• Charting: Chart.js 4, Vega-Lite 6, Recharts — declarative and imperative visualization side by side
• 85+ components across dashboard, intelligence, admin, and simulation domains

---

Data Pipeline — 19 Automated ETL Jobs

All jobs log execution status to ETLRun and handle partial failures gracefully. CSV bomb protection (10 MB / 10k row hard limits) applied to all ingestion paths.

---

Intelligence Features

Natural Language CommandBar

• Keyboard shortcut (Cmd/Ctrl+K) launches a conversation-style query interface
• Up to 5-iteration reasoning loop with 8 function-calling tools:
  • Conflict events (ACLED), sentiment data (GDELT), economic indicators (World Bank live + IMF/OECD), news articles, risk forecasts, humanitarian data (HDX/UNHCR), CIA Factbook country profiles, Wikipedia entity context
• Optionally grounded via Perplexity API (web search fallback to Perplexica)
• Source attribution and "why surfaced" transparency layer on every response
• Three analysis modes: fast · balanced · thorough

Bayesian Risk Engine

• Probabilistic influence networks across economic, conflict, and humanitarian indicators
• Multi-factor risk score aggregation with temporal decay
• Scenario impact modeling and component-level lineage tracking
• Outputs: ChronoRisk panel (temporal forecasts), GeoPulse panel (regional stability scores)

Scenario Simulator

• What-if scenario modeling with configurable actors and parameters
• Agent-based simulation engine with memory graph (nodes + edges) tracking state across iterations
• State snapshots, event propagation, and outcome probability calculations
• Template marketplace with rate limiting (5 runs/user/60s)
• Save, share, and replay scenarios

Anomaly Detection

• Deviation analysis across event frequency, sentiment, and economic streams
• Baseline comparison with historical anchoring
• Surfaced automatically in CommandBar responses and alert rules

Alert System

• User-defined alert rules with flexible condition expressions
• Severity levels: LOW · MEDIUM · HIGH · CRITICAL
• Automatic dispatch with in-app notifications
• Acknowledgment tracking and integration with investigation workspaces

Intelligence Analysis Publishing

• AI-generated analysis articles with source attribution
• Keyword extraction and quality scoring per article
• Full publication history with browsable archive

Investigation Workspaces

• Multi-user collaborative workspaces
• Evidence items with structured notes
• Organization-scoped access control

---

Data Models (100+ entities)

Authentication & Access: User, UserRole (VIEWER / ANALYST / ADMIN), TOTP MFA with backup codes, JWT refresh tokens with blacklist, SecretVault (field-level encryption)

Events & Intelligence: Event (ACLED), Sentiment (GDELT), RiskForecast, EconomicIndicator, NewsArticle + deduplication hash, ThreatActor with relationship graph

Humanitarian: HumanitarianDisplacement, FoodSecurity, UNHCRAsylumApplication/Decision/Population, OperationalPresence, FactbookProfile

Simulation: SimulationCase, SimulationRun, SimulationAgent, SimulationEvent, SimulationMemoryNode/Edge, AnchoredScenario

System: AlertRule, Alert, ETLRun, LLMUsage/Run, SystemPrompt, MaterializedViewLog, CatalogItem, QualityScore

---

Security

Recent hardening addressed:

• Authentication bypass removed — dev shortcut stripped from scenario endpoints; all sensitive routes require valid JWT
• Broken authorization fixed — admin-only operations (cache clear, user role updates, manual intel) now enforce role checks at the handler level
• Information disclosure patched — manual intel endpoints fully gated
• Error message sanitization — internal exceptions no longer leak stack traces to clients

Ongoing controls:

• Password policy: 12+ chars, mixed case, numbers, symbols
• TOTP multi-factor authentication with QR provisioning and backup codes
• Distributed rate limiting with Redis circuit breaker
• CORS strict allowlist with dynamic production origin detection
• HTTPS-only session cookies in production
• SQL injection prevention via SQLAlchemy parameterized queries throughout

---

API Surface

~40 command/intelligence routes — /api/command/interpret, /api/command/stream, /api/summary/daily, /api/events, /api/analysis, /api/scenarios

~15 data source routes — /api/worldline, /api/geopulse, /api/chronorisk, /api/worldnews, /api/humanitarian, /api/factbook, /api/imf, /api/oecd, /api/owid

~20 admin routes — ETL trigger/status, materialized view refresh, cache management, user management, prompt engineering, alert rules

Health probes — /api/health/live, /api/health/ready (DB + Redis checks), /api/health/config, /api/metrics (admin-only)

---

Deployment & Infrastructure

• Railway production target with Neon PostgreSQL and Redis add-ons
• nixpacks.toml build: Python venv + pip install → frontend Vite build → Uvicorn with 2 workers
• Connection pooling tuned for NullPool compatibility (Railway/Supabase pooler)
• GitHub Actions CI/CD: build + test → staging smoke → staging soak (load test) → production release → post-deploy health checks; rollback workflow included

---

Testing

• Backend: pytest with integration tests against a real test database, security authorization tests, ETL validation, API contract tests
• Frontend: Vitest + React Testing Library for component tests; Playwright E2E suite covering auth flows, CommandBar, scenario simulation, admin operations, and mobile layout
• Performance baselines: automated regression detection on critical render and query paths
• Security audit: npm audit + pip audit gates in CI

---

Stack: Python 3.11 · FastAPI · PostgreSQL (PostGIS) · Redis · React 19 · Vite · Tailwind CSS