https://github.com/saagpatel/sovereign
Browser-based geopolitical simulator — apply policy levers to 18 countries and watch cascading effects over 60 months
https://github.com/saagpatel/sovereign
d3 data-visualization geopolitics monte-carlo nextjs simulation typescript web-worker
Last synced: about 23 hours ago
JSON representation
Browser-based geopolitical simulator — apply policy levers to 18 countries and watch cascading effects over 60 months
- Host: GitHub
- URL: https://github.com/saagpatel/sovereign
- Owner: saagpatel
- License: mit
- Created: 2026-03-24T11:41:32.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-19T12:58:38.000Z (10 days ago)
- Last Synced: 2026-06-19T14:29:36.740Z (10 days ago)
- Topics: d3, data-visualization, geopolitics, monte-carlo, nextjs, simulation, typescript, web-worker
- Language: TypeScript
- Size: 604 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Sovereign
[](#) [](#)
> What happens to the global economy if one country raises tariffs by 20%?
Sovereign is a browser-based geopolitical simulation tool. Apply a policy lever — trade tariff, military spending shift, immigration change, or currency devaluation — to any of 18 countries and blocs, then watch cascading effects ripple across the world over a 60-month horizon. Up to 50 Monte Carlo passes with configurable noise produce p10/p50/p90 confidence bands for 10 macroeconomic variables per country.
## Features
- **18 countries and blocs** — US, EU, China, Russia, UK, India, Japan, Brazil, and more, each with calibrated baseline economic parameters
- **6 policy domains** — trade, energy, military, immigration, monetary, and technology
- **Monte Carlo engine** — up to 50 simulation passes in a Web Worker via Comlink; no UI blocking
- **Confidence bands** — p10/p50/p90 bands across GDP growth, inflation, trade openness, debt-to-GDP, foreign reserves, and 5 other variables
- **Interactive world map** — D3-geo + TopoJSON globe with country selection and hover tooltips
- **Timeline scrubber** — step through any of the 60 months to see the state at that moment
- **Causal chain view** — top-10 ranked causal links explaining how your policy propagated
## Quick Start
### Prerequisites
- Node.js 18+
### Installation
```bash
pnpm install
```
### Usage
```bash
# Development server
pnpm dev
# Run tests
pnpm test
# Type-check
pnpm typecheck
```
## Tech Stack
| Layer | Technology |
|-------|------------|
| Framework | Next.js 15 (App Router) |
| Language | TypeScript 5.7 |
| Simulation | Web Worker via Comlink |
| State | Zustand |
| Geo visualization | D3-geo + TopoJSON |
| Charts | Recharts |
| Styling | Tailwind CSS 3 |
| Testing | Vitest + Testing Library |
## Architecture
The simulation engine runs entirely in a Web Worker, keeping the UI responsive during heavy Monte Carlo passes. Comlink provides a transparent async proxy so the React layer calls `await worker.simulate(params)` like a regular function. Results — p10/p50/p90 bands for all 10 variables across all 18 entities — are streamed back to Zustand stores that drive the D3 map and Recharts panels simultaneously.
## License
MIT