Getting Started with Pangea v2

This guide walks you through setting up a local development environment for the Pangea v2 codebase. By the end, you will have the application running locally with fixture data and all tests passing.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js v20 or later (v25+ recommended)
Git 2.40 or later
npm 10 or later (ships with Node)

You will also need a terminal that supports Unix-style commands. On Windows, use Git Bash or WSL.

Optional: if you plan to work with the realtime collaboration features, you will also need a Cloudflare account for Durable Objects deployment.

Installation

Clone the Repository

Start by cloning the repository with optimized fetch settings:

git clone --depth=1 --filter=blob:none https://github.com/Francesco-Bonetti/Pangea-v2.git
cd Pangea-v2

Install Dependencies

Install all project dependencies:

npm install

The @wireapp/core-crypto package is optional and only required when PANGEA_MLS_ENABLED=1 is set. It is listed as a dependency but lazy-loaded at runtime — installation warnings about native modules can be safely ignored.

Project Structure

The codebase follows a modular architecture. Here are the key directories:

Directory	Purpose
`src/modules/`	19 domain modules (groups, proposals, voting, etc.)
`src/components/`	React components (UI atoms + feature components)
`src/app/`	Next.js App Router pages and layouts
`src/styles/`	Design tokens (`tokens.css`) and global styles
`src/lib/`	Shared utilities (crypto, WASM, OTP, etc.)
`messages/`	i18n message files
`content/`	MDX documentation content
`worker/`	Cloudflare Worker for realtime (Durable Objects)

Each module in src/modules/ contains:

service.ts — business logic interface and implementation
repository.ts — data access interface
fixture-repository.ts — in-memory implementation for testing
composition.ts — dependency injection wiring
types.ts — TypeScript type definitions

// Example: reading the group service
import { composeGroupService } from "@/modules/groups/composition";

const groupService = composeGroupService();
const groups = await groupService.list();

Running the Dev Server

Start the Next.js development server:

npm run dev

The application will be available at http://localhost:3000. By default, it runs with fixture repositories — no database connection needed.

Visit http://localhost:3000/showcase to see all 11 vertical slices rendered with fixture data. This is the fastest way to verify your setup.

To connect to a real Supabase instance, create a .env.local file:

PANGEA_USE_REAL_DB=1
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Never commit .env.local or any file containing the service_role_key. The .gitignore is pre-configured to exclude these files, but always verify before pushing.

Running Tests

The test suite uses Vitest with React Testing Library:

npx vitest run

All 859 tests should pass. To run tests in watch mode during development:

npx vitest

For type checking without a full build:

npx tsc --noEmit

Do not run npm run build on machines with limited memory — the full Next.js build can trigger SIGBUS on constrained environments. Use tsc --noEmit for type verification instead.

Next Steps

Now that your environment is set up, explore these areas:

Introduction to the Treatise — understand the governance principles behind Pangea
Showcase slices at /showcase — see each module in action
API Playground at /showcase/api-playground — interact with the REST API
Contributing — read CONTRIBUTING.md for the PR workflow

For questions or issues, check the repository's issue tracker or open a discussion thread.