AI-powered scenario analysis: describe a real-world scenario, simulate how its stakeholder populations react over time (The Field), then have five distinct AI analyst personas debate the result into a calibrated verdict (The Council).
See docs/00_PROJECT_FOUNDATIONS.md for the full concept guide.
| Layer | Technology |
|---|---|
| Frontend | React 19 + Vite + TypeScript + Tailwind CSS 4 |
| Backend | Python 3.12 + FastAPI + SQLAlchemy (async) + Alembic |
| Database | PostgreSQL 16 |
| Cache / Pub-Sub | Redis 7 (drives SSE live updates) |
| LLM | OpenRouter (primary) + Groq (fast debate turns), via the OpenAI-compatible SDK |
| Data sources | GNews (auto-gathered seed material; more sources pluggable in backend/app/services/news.py) |
cp .env.example .env # fill in OPENROUTER_API_KEY (required), GROQ/GNEWS keys (optional)
docker compose up -d --buildOpen http://localhost:3000 — sign up, create a scenario, watch the simulation live in The Field, then start the council debate.
Database schema is managed by Alembic; migrations run automatically on backend startup.
The E2E suite runs the real stack in the browser with the backend in fake-LLM mode
(LLM_FAKE=1): deterministic canned responses, no API keys or network calls needed.
pnpm install
npx playwright install chromium
pnpm e2e:stack # docker compose with the test override (LLM_FAKE=1)
pnpm test:e2e # 7 tests: auth, full scenario→debate→verdict journey, forks, injection, discoverSwitch back to real mode afterwards with docker compose up -d.
pnpm dev # frontend on :3000 (expects backend on :8000)
cd backend && uvicorn app.main:app --reload # backend (needs postgres + redis, e.g. from docker compose)API docs: http://localhost:8000/docs