The Governance Compass
A political self-assessment web app that measures governance preferences across 12 dimensions. Users complete a 3-phase questionnaire (forced-choice dilemmas, calibrated scales, budget allocation) and receive a multi-dimensional profile with archetype matching, tension detection, and interactive visualizations.
Supports annotations, one-on-one comparisons, and private group comparisons.
Quick Start
# Create local configuration, then start PostgreSQL (Docker must be running)
cp .env.example .env
docker compose up -d --wait postgres
# Install dependencies and seed the database
npm install
npx prisma migrate deploy
npx prisma db seed
# Start the dev server
npm run dev
# Open http://localhost:3000
Use .env rather than .env.local: the Prisma CLI loads its configuration
through dotenv/config in prisma.config.ts, which reads .env only. Next.js
reads both, so a single .env keeps the app and migrate/seed pointed at the
same database. The defaults in .env.example match compose.yaml; if you
change the credentials or port, change them in both.
Stack
Next.js 16 (App Router), TypeScript, PostgreSQL, Prisma, NextAuth v5, Tailwind CSS
Testing
npm test # Unit tests (vitest)
npm run typecheck # TypeScript
npx playwright install chromium # One-time browser installation
npm run test:e2e # E2E tests (starts the dev server automatically)
The E2E suite needs the migrated and seeded PostgreSQL database described in
Quick Start. Playwright's webServer configuration starts the application.
Google sign-in additionally requires real GOOGLE_CLIENT_ID and
GOOGLE_CLIENT_SECRET values. Credentials sign-in and non-authenticated flows
do not require Google OAuth credentials. Generate a non-placeholder
NEXTAUTH_SECRET before using the app outside local development.
Data sources
- World map geometry derived from Natural Earth (110m Cultural Vectors, public domain).
- Synthetic study personas and responses were generated by Gemini 2.5 Flash and Claude Sonnet 4.6 in April 2026 (see
/study and the methodology page for details).
License
PolyForm Noncommercial License 1.0.0. The code is source-available for personal, research, and educational use; commercial use is not permitted.
Project Structure
src/app/ — Next.js App Router pages and API routes, including the /study/* Synthetic Study sectionsrc/components/ — React components by feature (quiz, results, comparison, groups, annotations, study) plus shared NavBar, SessionProvidersrc/data/ — Axis, item, ministry, and archetype definitionssrc/lib/ — Pure logic: scoring, comparison, validation, auth, db, design tokens, study helpersdata/synthetic_study/ — Raw pipeline outputs for the Synthetic Study (personas, scored profiles, cluster labels, etc.)public/study/derived/ — Build-time preprocessed JSON for the Synthetic Study pagespublic/geo/ + public/data/ — World map TopoJSON and public Synthetic Study downloadscripts/ — Build-time preprocessing (build-synthetic-study.ts, build-geo.ts) run via npm run build:study / npm run build:geo on prebuilddocs/system_proposal/ — Design specs (scoring engine, results UI, question bank, design system, synthetic study)prisma/ — Database schema and migrations
