Introduction to the Pangea Treatise

This document introduces the foundational ideas behind Pangea — a framework for digital governance that bridges deliberative democracy with modern distributed systems. The full treatise is maintained separately; this page provides an architectural and philosophical orientation.

What is Pangea?

Pangea is a governance layer for communities that need structured decision-making without centralized authority. It combines:

• Proposal lifecycles with commit-reveal voting
• Role elections and transitive delegation chains
• Guardian oversight with sunset windows and emergency pauses
• Real-time collaboration via CRDTs on Cloudflare Durable Objects

Pangea does not prescribe a single governance model. It provides composable primitives that communities assemble into constitutions.

The name reflects the ambition: a connected landmass of self-governing groups, federated but sovereign.

Core Principles

Three axioms guide every design decision in the Pangea ecosystem.

Subsidiarity

Decisions should be made at the lowest competent level. A group that can resolve a dispute internally should never need to escalate to a federation-level tribunal. The guardian module enforces this by evaluating trigger conditions before activating cross-group mechanisms.

In code, the trigger evaluation looks like this:

const report = await guardian.evaluateTriggers(groupId);
if (report.allConditionsMet) {
  await guardian.openSunsetWindow(groupId, domain);
}

Transparency

Every state transition is auditable. Proposals move through a 7-state lifecycle (draft → staged → vote_ready → tallying → final → archived) with each transition recorded. The archive module provides immutable snapshots.

Use the proposalService.transition() method to advance state:

await proposalService.transition(proposalId, "vote_ready");

Progressive Decentralization

Communities start with training wheels. Early groups operate in sim mode with structural defaults. As participation grows and critical-mass thresholds are met, the guardian module enables self-governance features incrementally.

Architecture Overview

The Pangea codebase is organized into 19 modules across 4 tiers, from foundational infrastructure to user-facing slices.

Tier Model

Each module follows the composition root pattern: a composition.ts file wires the service interface to its repository implementation¹.

// src/modules/groups/composition.ts
export function composeGroupService(): GroupService {
  const repo = process.env.PANGEA_USE_REAL_DB
    ? new SupabaseGroupRepository()
    : new FixtureGroupRepository();
  return new GroupServiceImpl(repo);
}

Getting Involved

The treatise is a living document. Contributions follow the standard PR workflow:

1. Fork the repository
2. Create a feat/ or fix/ branch
3. Submit a pull request with conventional commit messages
4. Wait for review — the guardian module enforces a comment period

For questions, open a discussion in the repository or reach out through the community channels listed in the project README.