🏛️ Polity - Democracy Reimagined

Empowering communities, organizations, and governments with collaborative decision-making tools for the digital age.

---

Prerequisites

• Node.js 22+ (recommended via nvm)
• npm
• Docker Desktop (for Supabase & Zero Cache)
• Supabase CLI (npm i -g supabase or use npx supabase)

---

Running the Project

1. Install dependencies

npm install

2. Start Supabase (local)

npx supabase start

This boots up a local Supabase stack (Postgres, Auth, Studio, Inbucket, etc.) via Docker.

3. Apply the database schema

Get-ChildItem supabase/schemas/*.sql | Sort-Object Name | ForEach-Object { docker exec -i supabase_db_polity psql -U postgres -d postgres -c (Get-Content $_.FullName -Raw) }

On Linux/macOS:

for f in supabase/schemas/*.sql; do docker exec -i supabase_db_polity psql -U postgres -d postgres < "$f"; done

This creates all tables, indexes, RLS policies, storage policies, and functions from supabase/schemas/.

3b. Create storage buckets

npx supabase seed buckets

This provisions the avatars and uploads storage buckets defined in supabase/config.toml. Buckets are not auto-created by supabase start — this step is required for image uploads to work.

4. Start the dev server

In a separate terminal:

npm run dev

5. Start Zero Cache

In a separate terminal:

npm run zero:dev

Or via Docker Compose (which also starts the app):

docker compose up -d

6. (Optional) Seed the database

npm run seed

---

Where to Find What

Service	URL	Description
App (Dev)	http://localhost:3000	Polity frontend (TanStack Start / Vinxi)
Supabase Studio	http://localhost:54323	Database GUI, table editor, SQL editor
Supabase API	http://localhost:54321	Supabase REST & Auth API
Supabase Inbucket	http://localhost:54324	Local email inbox (captures auth emails, OTPs)
Postgres (direct)	postgresql://postgres:postgres@127.0.0.1:54322/postgres	Direct DB connection (e.g. for psql, DBeaver)
Zero Cache	http://localhost:4848	Zero sync engine (realtime cache server)

---

All npm Scripts

Command	Description
npm run dev	Start the dev server on port 3000
npm run build	Production build
npm run start	Start production server
npm run seed	Seed the database with test data
npm run zero:dev	Start zero-cache-dev with env vars (local dev)
npm run zero:cache	Start zero-cache-dev (no env vars)
npm run supabase:start	Start local Supabase
npm run supabase:stop	Stop local Supabase
npm run test	Run unit tests (Vitest)
npm run test:e2e	Run E2E tests (Playwright)
npm run test:e2e:ui	Run E2E tests with Playwright UI
npm run test:e2e:headed	Run E2E tests in headed browser
npm run lint	Lint with ESLint
npm run lint:fix	Lint and auto-fix
npm run format	Format code with Prettier
npm run format:check	Check formatting
npm run storybook	Start Storybook on port 6006

---

Docker Compose

docker compose up -d starts:

• zero-cache — Zero sync server on port 4848, connected to Supabase Postgres
• app — The Polity dev server on port 3000

Note: Supabase must be running first (npx supabase start) since Docker Compose connects to the Supabase Docker network (supabase_network_polity).

Stopping everything

docker compose down      # Stop zero-cache & app containers
npx supabase stop        # Stop local Supabase

---

Project Structure

app/              # TanStack Start entry points (client, ssr, router)
src/
  routes/         # File-based route pages
  components/     # Reusable UI components (shadcn/ui)
  features/       # Feature modules (amendments, groups, events, etc.)
  hooks/          # Custom React hooks
  i18n/           # Internationalization (DE & EN)
  zero/           # Zero schema & sync setup
  utils/          # Utility functions
supabase/         # Supabase config & schema SQL
scripts/          # Database seeding scripts
e2e/              # Playwright E2E tests

Tech Stack

• Framework: TanStack Start (Vinxi)
• Database: Supabase (Postgres) + Zero (realtime sync)
• Styling: Tailwind CSS v4 + shadcn/ui
• Editor: Plate.js — Rich text collaborative editor
• AI: Custom AI assistants (Aria & Kai)
• Auth: Supabase Auth (email OTP)
• Testing: Vitest + Playwright
• i18n: i18next (German & English)

---

Contributing

• 💻 Code: Fix bugs, add features, improve tests
• 🎨 Design: Improve UX/UI (Figma)
• 📝 Docs: Write guides, tutorials, API docs
• 🐛 Testing: Report bugs, write test cases

Community

• Email: tobias.hassebrock@gmail.com
• GitHub: Donnerstagnacht/polity-instant

---

⚠️ Early Alpha — Database resets can happen. Use with caution!