Community Simulation

An agent-based simulation tool for strategic foresight. Model a community as an ecosystem of organizations and actors (entities), each with a detailed profile — influence, legitimacy, resources, relationships, strategic goals, and behavioral rules — then run forward simulations year by year, branch alternate scenarios, inject events, and analyze the landscape before you start.

This repository runs independently (it no longer depends on the v0.app sync workflow).

---

Tech stack

• Next.js 16 (App Router) + React 19
• Supabase (Postgres) for persistence
• Anthropic Claude for AI reasoning (landscape analysis, simulation, discovery)
• Tailwind CSS 4 + Radix UI / shadcn components

---

Prerequisites

• Node.js 20+ (Next 16 requires a modern Node runtime)
• A package manager — pnpm is recommended (a pnpm-lock.yaml is committed), but npm works too
• A free Supabase project
• An Anthropic API key

---

Setup

1. Install dependencies

pnpm install
# or: npm install

2. Configure environment variables

cp .env.example .env.local

Then open .env.local and fill in the required values (Supabase URL + anon key, Anthropic key). The optional keys can be left blank — those features will simply be unavailable until you add them.

3. Create the database schema

In your Supabase project, open SQL Editor and run the scripts in scripts/ in this exact order (later scripts depend on tables created by earlier ones):

1. scripts/001-create-entities-table.sql
2. scripts/002-create-communities-table.sql
3. scripts/create-simulation-tables.sql
4. scripts/add-simulation-branching.sql
5. scripts/add-simulation-enhancements.sql
6. scripts/add-year-summary-columns.sql

The tables use open Row Level Security policies (public access) so you can run locally without auth. Add real RLS/auth before any public deployment.

4. Run the dev server

pnpm dev
# or: npm run dev

Open http://localhost:3000

---

How it fits together

Layer	Where	What it does
Data model	lib/entity-types.ts	The flat Entity shape used throughout the UI
DB translation	app/api/entities/route.ts	Maps flat Entity ⇄ grouped JSONB DB columns
Data collection	app/api/discover-*, search-*, scrape-website, parse-*	Populate entities from real sources (990s, USASpending, SEC, Wikipedia, web)
Landscape analysis	app/api/simulations/[id]/landscape-analysis	Pre-simulation read of power, alliances, tensions, scenario readiness
Simulation engine	app/api/simulations/[id]/run-year	Advances the simulation one year; branching + event injection

Important: the DB stores grouped JSONB, not the flat Entity shape

The database stores entity attributes in grouped, snake_case JSONB columns (financials, human_resources, influence, strategic, advanced, …). The flat camelCase Entity type exists only in app code. The translation between them lives in app/api/entities/route.ts (transformDbToEntity / transformEntityToDb).

Any route that reads entities directly from Supabase must use the grouped snake_case keys (e.g. entity.strategic.risk_tolerance, entity.influence.community_influence_level) — not the flat ones. Mixing these up does not throw an error (see note below), it silently yields empty data.

Note: build errors are currently suppressed

next.config.mjs sets typescript.ignoreBuildErrors: true. This is why schema key-mismatches don't surface at build time. Consider turning this off once the codebase is stable so type errors fail loudly.

---

Deployment

Deployable to any Node host or Vercel. Set the same environment variables in your host's dashboard, and ensure the Supabase schema (step 3) has been applied to the project your production env vars point at.