Vortex Simulator v0.1

.gitignore

@@ -28,6 +28,9 @@ storybook-static
 # local state
 .env
 
+# wrangler local artifacts
+.wrangler
+
 # landing assets (keep large videos out of git history)
 public/landing/*.mp4
 public/landing/*.webm

.prettierignore

@@ -0,0 +1,5 @@
+.wrangler
+dist
+node_modules
+.yarn
+docs/vortex-1.0-paper.md

.vscode/settings.json

@@ -1,3 +1,6 @@
 {
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "css.lint.vendorPrefix": "ignore",
+  "css.lint.propertyIgnoredDueToDisplay": "ignore",
+  "css.lint.unknownAtRules": "ignore"
 }

README.md

@@ -1,14 +1,19 @@
-# Vortex Webapp Layout
+# Vortex Experimental Mockups
 
-Experimental Vortex interface built with React + Rsbuild, Tailwind-like utility styles, and shared UI components.
+This repo ships:
+
+1. A React UI mockup of Vortex (Humanode governance hub)
+2. An off-chain “simulation backend” served from `/api/*` (Cloudflare Pages Functions)
+
+Humanode mainnet is used only as a read-only eligibility gate; all simulated governance state lives off-chain.
 
 ## Stack
 
 - React with React Router
 - Rsbuild
-- Yarn (see `.node-version` for Node version)
-- UI primitives in `src/components/primitives`
-- Tailwind-style utilities via PostCSS
+- Tailwind v4 (via PostCSS) + token-driven CSS (`src/styles/base.css`)
+- Yarn (Node version: `.node-version`)
+- Pages Functions API in `functions/` + Postgres via Drizzle
 
 ## Getting Started
 
@@ -23,11 +28,41 @@ Dev server: http://localhost:3000
 Landing: http://localhost:3000/
 App: http://localhost:3000/app
 
+## Simulation API (local)
+
+The UI reads from `/api/*` (Cloudflare Pages Functions). For local dev, run the API locally so the UI can reach it:
+
+- One command: `yarn dev:full` (API on `:8788` + UI on `:3000` + `/api/*` proxy)
+- Two terminals:
+  - Terminal 1: `yarn dev:api`
+  - Terminal 2: `yarn dev`
+
+If only `yarn dev` runs, `/api/*` is not available and auth/gating/read pages will show an “API is not available” error.
+
+### Backend docs
+
+- Start here: `docs/README.md`
+- Docs are grouped in: `docs/simulation/`, `docs/ops/`, `docs/paper/`
+- Module map (paper → docs → code): `docs/simulation/vortex-simulation-modules.md`
+- API contract: `docs/simulation/vortex-simulation-api-contract.md`
+- Proposal wizard architecture: `docs/simulation/vortex-simulation-proposal-wizard-architecture.md`
+- Local dev: `docs/simulation/vortex-simulation-local-dev.md`
+- Scope and rules: `docs/simulation/vortex-simulation-scope-v1.md`, `docs/simulation/vortex-simulation-state-machines.md`
+- Vortex 1.0 reference (working copy): `docs/paper/vortex-1.0-paper.md`
+
 ## Scripts
 
 - `yarn dev` – start the dev server
+- `yarn dev:api` – run the Pages Functions API locally (Node runner)
+- `yarn dev:full` – run UI + API together (recommended)
+- `yarn dev:api:wrangler` – run the API via `wrangler pages dev` against `./dist`
 - `yarn build` – build the app
-- `yarn exec tsc --noEmit` – type-check
+- `yarn test` – run API/unit tests
+- `yarn prettier:check` / `yarn prettier:fix`
+
+## Type checking
+
+- Repo typecheck (UI + Pages Functions + DB seed builders): `yarn exec tsc --noEmit`
 
 ## Project Structure
 
@@ -36,7 +71,11 @@ App: http://localhost:3000/app
 - `src/data` – glossary (vortexopedia), page hints/tutorial content
 - `src/pages` – feature pages (proposals, human-nodes, formations, chambers, factions, courts, feed, profile, invision, etc.)
 - `src/styles` – base/global styles
-- `prolog/vortexopedia.pl` – Prolog version of the glossary data (for future integration)
+- `functions/` – Pages Functions API (`/api/*`) + shared server helpers
+- `db/` – Drizzle schema + migrations + seed builders
+- `scripts/` – DB seed/clear + local API runner
+- `prolog/vortexopedia.pl` – Prolog glossary mirror
+- `public/landing/` – landing page assets (see `public/landing/README.md`)
 
 ## Shared Patterns
 
@@ -46,5 +85,6 @@ App: http://localhost:3000/app
 
 ## Notes
 
-- Builds output to `dist/`.
+- `dist/` is generated build output.
 - Keep glossary entries in sync between `src/data/vortexopedia.ts` and `prolog/vortexopedia.pl` if you edit definitions.
+- DB-backed dev requires `DATABASE_URL` + `yarn db:migrate && yarn db:seed` (see `docs/simulation/vortex-simulation-local-dev.md`).

db/migrations/0001_bitter_oracle.sql

@@ -0,0 +1,8 @@
+CREATE TABLE "auth_nonces" (
+	"nonce" text PRIMARY KEY NOT NULL,
+	"address" text NOT NULL,
+	"request_ip" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"expires_at" timestamp with time zone NOT NULL,
+	"used_at" timestamp with time zone
+);

db/migrations/0002_dear_betty_ross.sql

@@ -0,0 +1,10 @@
+CREATE TABLE "events" (
+	"seq" bigserial PRIMARY KEY NOT NULL,
+	"type" text NOT NULL,
+	"stage" text,
+	"actor_address" text,
+	"entity_type" text NOT NULL,
+	"entity_id" text NOT NULL,
+	"payload" jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);

db/migrations/0003_cultured_supreme_intelligence.sql

@@ -0,0 +1,16 @@
+CREATE TABLE "idempotency_keys" (
+	"key" text PRIMARY KEY NOT NULL,
+	"address" text NOT NULL,
+	"request" jsonb NOT NULL,
+	"response" jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "pool_votes" (
+	"proposal_id" text NOT NULL,
+	"voter_address" text NOT NULL,
+	"direction" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "pool_votes_proposal_id_voter_address_pk" PRIMARY KEY("proposal_id","voter_address")
+);

db/migrations/0004_smiling_iron_man.sql

@@ -0,0 +1,9 @@
+CREATE TABLE "chamber_votes" (
+	"proposal_id" text NOT NULL,
+	"voter_address" text NOT NULL,
+	"choice" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "chamber_votes_proposal_id_voter_address_pk" PRIMARY KEY("proposal_id","voter_address")
+);
+

db/migrations/0005_warm_alex_wilder.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "chamber_votes" ADD COLUMN "score" integer;
+

db/migrations/0006_heavy_hidden_dream.sql

@@ -0,0 +1,13 @@
+CREATE TABLE "cm_awards" (
+	"id" bigserial PRIMARY KEY NOT NULL,
+	"proposal_id" text NOT NULL,
+	"proposer_id" text NOT NULL,
+	"chamber_id" text NOT NULL,
+	"avg_score" integer,
+	"lcm_points" integer NOT NULL,
+	"chamber_multiplier_times10" integer NOT NULL,
+	"mcm_points" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "cm_awards_proposal_id_unique" UNIQUE("proposal_id")
+);
+

db/migrations/0007_ancient_formation.sql

@@ -0,0 +1,39 @@
+CREATE TABLE "formation_projects" (
+	"proposal_id" text PRIMARY KEY NOT NULL,
+	"team_slots_total" integer NOT NULL,
+	"base_team_filled" integer DEFAULT 0 NOT NULL,
+	"milestones_total" integer NOT NULL,
+	"base_milestones_completed" integer DEFAULT 0 NOT NULL,
+	"budget_total_hmnd" integer,
+	"base_budget_allocated_hmnd" integer,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+
+CREATE TABLE "formation_team" (
+	"proposal_id" text NOT NULL,
+	"member_address" text NOT NULL,
+	"role" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "formation_team_pk" PRIMARY KEY("proposal_id","member_address")
+);
+
+CREATE TABLE "formation_milestones" (
+	"proposal_id" text NOT NULL,
+	"milestone_index" integer NOT NULL,
+	"status" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "formation_milestones_pk" PRIMARY KEY("proposal_id","milestone_index")
+);
+
+CREATE TABLE "formation_milestone_events" (
+	"id" bigserial PRIMARY KEY NOT NULL,
+	"proposal_id" text NOT NULL,
+	"milestone_index" integer NOT NULL,
+	"type" text NOT NULL,
+	"actor_address" text,
+	"payload" jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);

db/migrations/0008_courts_v1.sql

@@ -0,0 +1,24 @@
+CREATE TABLE "court_cases" (
+	"id" text PRIMARY KEY NOT NULL,
+	"status" text NOT NULL,
+	"base_reports" integer DEFAULT 0 NOT NULL,
+	"opened" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+
+CREATE TABLE "court_reports" (
+	"case_id" text NOT NULL,
+	"reporter_address" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "court_reports_pk" PRIMARY KEY("case_id","reporter_address")
+);
+
+CREATE TABLE "court_verdicts" (
+	"case_id" text NOT NULL,
+	"voter_address" text NOT NULL,
+	"verdict" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "court_verdicts_pk" PRIMARY KEY("case_id","voter_address")
+);

db/migrations/0009_era_rollups.sql

@@ -0,0 +1,16 @@
+CREATE TABLE "era_snapshots" (
+	"era" integer PRIMARY KEY NOT NULL,
+	"active_governors" integer NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+
+CREATE TABLE "era_user_activity" (
+	"era" integer NOT NULL,
+	"address" text NOT NULL,
+	"pool_votes" integer DEFAULT 0 NOT NULL,
+	"chamber_votes" integer DEFAULT 0 NOT NULL,
+	"court_actions" integer DEFAULT 0 NOT NULL,
+	"formation_actions" integer DEFAULT 0 NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "era_user_activity_pk" PRIMARY KEY("era","address")
+);

db/migrations/0010_era_rollup_status.sql

@@ -0,0 +1,26 @@
+CREATE TABLE "era_rollups" (
+	"era" integer PRIMARY KEY NOT NULL,
+	"required_pool_votes" integer DEFAULT 0 NOT NULL,
+	"required_chamber_votes" integer DEFAULT 0 NOT NULL,
+	"required_court_actions" integer DEFAULT 0 NOT NULL,
+	"required_formation_actions" integer DEFAULT 0 NOT NULL,
+	"required_total" integer DEFAULT 0 NOT NULL,
+	"active_governors_next_era" integer DEFAULT 0 NOT NULL,
+	"rolled_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+
+CREATE TABLE "era_user_status" (
+	"era" integer NOT NULL,
+	"address" text NOT NULL,
+	"status" text NOT NULL,
+	"required_total" integer DEFAULT 0 NOT NULL,
+	"completed_total" integer DEFAULT 0 NOT NULL,
+	"is_active_next_era" boolean DEFAULT false NOT NULL,
+	"pool_votes" integer DEFAULT 0 NOT NULL,
+	"chamber_votes" integer DEFAULT 0 NOT NULL,
+	"court_actions" integer DEFAULT 0 NOT NULL,
+	"formation_actions" integer DEFAULT 0 NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "era_user_status_pk" PRIMARY KEY("era","address")
+);
+

db/migrations/0011_api_rate_limits.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "api_rate_limits" (
+	"bucket" text PRIMARY KEY NOT NULL,
+	"count" integer DEFAULT 0 NOT NULL,
+	"reset_at" timestamp with time zone NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+

db/migrations/0012_user_action_locks.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "user_action_locks" (
+	"address" text PRIMARY KEY NOT NULL,
+	"locked_until" timestamp with time zone NOT NULL,
+	"reason" text,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+

db/migrations/0013_admin_state.sql

@@ -0,0 +1,6 @@
+CREATE TABLE "admin_state" (
+	"id" integer PRIMARY KEY NOT NULL,
+	"writes_frozen" boolean DEFAULT false NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+

db/migrations/0014_proposal_drafts.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "proposal_drafts" (
+	"id" text PRIMARY KEY NOT NULL,
+	"author_address" text NOT NULL,
+	"title" text NOT NULL,
+	"chamber_id" text,
+	"summary" text NOT NULL,
+	"payload" jsonb NOT NULL,
+	"submitted_at" timestamp with time zone,
+	"submitted_proposal_id" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);

db/migrations/0015_proposals.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "proposals" (
+  "id" text PRIMARY KEY NOT NULL,
+  "stage" text NOT NULL,
+  "author_address" text NOT NULL,
+  "title" text NOT NULL,
+  "chamber_id" text,
+  "summary" text NOT NULL,
+  "payload" jsonb NOT NULL,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+

db/migrations/0016_chamber_memberships.sql

@@ -0,0 +1,9 @@
+CREATE TABLE "chamber_memberships" (
+	"chamber_id" text NOT NULL,
+	"address" text NOT NULL,
+	"granted_by_proposal_id" text,
+	"source" text DEFAULT 'accepted_proposal' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "chamber_memberships_chamber_id_address_pk" PRIMARY KEY("chamber_id","address")
+);
+

db/migrations/0017_chambers.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "chambers" (
+	"id" text PRIMARY KEY NOT NULL,
+	"title" text NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"multiplier_times10" integer DEFAULT 10 NOT NULL,
+	"created_by_proposal_id" text,
+	"dissolved_by_proposal_id" text,
+	"metadata" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"dissolved_at" timestamp with time zone
+);

db/migrations/0018_proposal_stage_denominators.sql

@@ -0,0 +1,8 @@
+CREATE TABLE "proposal_stage_denominators" (
+	"proposal_id" text NOT NULL,
+	"stage" text NOT NULL,
+	"era" integer NOT NULL,
+	"active_governors" integer NOT NULL,
+	"captured_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "proposal_stage_denominators_proposal_id_stage_pk" PRIMARY KEY("proposal_id","stage")
+);

db/migrations/0019_delegations.sql

@@ -0,0 +1,17 @@
+CREATE TABLE "delegations" (
+	"chamber_id" text NOT NULL,
+	"delegator_address" text NOT NULL,
+	"delegatee_address" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "delegations_chamber_id_delegator_address_pk" PRIMARY KEY("chamber_id","delegator_address")
+);
+--> statement-breakpoint
+CREATE TABLE "delegation_events" (
+	"seq" bigserial PRIMARY KEY NOT NULL,
+	"chamber_id" text NOT NULL,
+	"delegator_address" text NOT NULL,
+	"delegatee_address" text,
+	"type" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);

db/migrations/0020_veto.sql

@@ -0,0 +1,14 @@
+ALTER TABLE "proposals" ADD COLUMN "veto_count" integer DEFAULT 0 NOT NULL;
+ALTER TABLE "proposals" ADD COLUMN "vote_passed_at" timestamp with time zone;
+ALTER TABLE "proposals" ADD COLUMN "vote_finalizes_at" timestamp with time zone;
+ALTER TABLE "proposals" ADD COLUMN "veto_council" jsonb;
+ALTER TABLE "proposals" ADD COLUMN "veto_threshold" integer;
+
+CREATE TABLE "veto_votes" (
+  "proposal_id" text NOT NULL,
+  "voter_address" text NOT NULL,
+  "choice" text NOT NULL,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  CONSTRAINT "veto_votes_proposal_id_voter_address_pk" PRIMARY KEY("proposal_id","voter_address")
+);