A community-driven, open-source plurality management platform.

Pluralscape helps plural systems (DID, OSDD, and beyond) manage identity tracking, fronting logs, internal communication, and privacy-controlled external sharing across web, iOS, and Android.

Status

Active development — Milestones 0-9 complete, Milestone 10 (UI/UX Design) next.

Milestones 0-7 built the full backend: data layer, API, sync, fronting, communication, privacy, and data portability. The REST API covers 304 operations across 31 route domains (OpenAPI spec), with a type-safe tRPC layer mirroring the full surface for the Expo mobile client (ADR 032).

Milestone 8 delivered the complete client foundation: Expo app shell with auth-gated routing, a 14-provider initialization tree (platform detection, auth state machine, encryption, sync), offline-first local data layer (SQLite + FTS5 search), 50+ domain data hooks via factory pattern (useOfflineFirstQuery/useOfflineFirstInfiniteQuery), web platform adapter (OPFS/IndexedDB), and CRDT sync coverage for all entity types.

Milestone 9 delivered data import: a shared import-core orchestration engine (packages/import-core) with checkpoint resume and pluggable Persister interface, Simply Plural import (packages/import-sp) covering 15 collections with file and API source modes, PluralKit import (packages/import-pk) for members/groups/fronting sessions, import API endpoints (REST + tRPC), mobile glue with 17 entity persisters, and E2E test infrastructure with deterministic seed scripts. See the CHANGELOG for details, the milestone roadmap for the full plan, the architecture overview for system design, and the mobile developer guide for client internals.

Test Suite

Unit and integration tests run via Vitest; E2E tests via Playwright (apps/api-e2e). Coverage is enforced in CI at 89% minimum (lines, functions, branches, statements).

pnpm test              # Run all tests
pnpm test:unit         # Unit tests only
pnpm test:integration  # Integration tests only
pnpm test:coverage     # Tests with coverage report
pnpm test:e2e          # E2E tests (Playwright)

E2E suite covers auth, CRUD, fronting, sync, webhooks, timers, real-time notifications, chat, boards, notes, polls, acknowledgements, privacy buckets, friends, dashboards, notifications, report export, blobs, custom fields, relationships, innerworld, API keys, check-in records, lifecycle events, notification configs, and tRPC smoke tests. Run pnpm test:coverage for up-to-date numbers.

Values

Privacy-first. Accessibility-first. Community-driven. No paywalled features. No telemetry without opt-in. No gatekeeping. No diagnosis required.

Read the full Values.

Repository Structure

This is a pnpm monorepo orchestrated by Turborepo.

apps/
  api/             Hono on Bun — tRPC (internal) + REST (public)
  api-e2e/         E2E test suite (Playwright)
  mobile/          Expo (React Native) — web, iOS, Android

packages/
  types/           Shared domain types, Zod validators, branded IDs, API constants
  crypto/          E2E encryption — libsodium (WASM + React Native adapters)
  data/            Client data layer — query factories, CRDT bridge, row/crypto transforms
  db/              Drizzle ORM schemas — PostgreSQL + SQLite dual-dialect
  sync/            CRDT sync protocol — Automerge
  api-client/      tRPC + TanStack Query client bindings
  email/           Transactional email — Resend + SMTP adapters, templates
  i18n/            Internationalization — locale formatting, nomenclature
  queue/           Background job queue — SQLite-backed with retry/DLQ
  rotation-worker/ Key rotation worker — processes bucket key rotation chunks
  storage/         Blob storage — S3 + filesystem adapters, quota management
  validation/      Shared Zod validation schemas with contract tests
  import-core/   Shared import orchestration — Persister, checkpoint, entity refs
  import-sp/     Simply Plural import — collection mappers, file + API sources
  import-pk/     PluralKit import — JSON export mapper

tooling/
  eslint-config/   Shared ESLint configuration
  prettier-config/ Shared Prettier configuration
  test-utils/      Shared test utilities and factories
  tsconfig/        Shared TypeScript configs (base.json, node.json)

ui-design/
  logo/            Brand assets (SVG icon, wordmark)
  BRANDING.md      Brand guidelines — colors, typography, components

docs/
  openapi/         OpenAPI 3.1 spec (multi-file source, Redocly CLI)
  openapi.yaml     Bundled single-file OpenAPI spec (generated)
  adr/             Architecture Decision Records (34 accepted)
  audits/          Codebase audit reports
  planning/        Specifications, milestones, feature planning
  future-features/ Unscheduled feature design documents

Tech Stack

Layer	Technology	Decision Record
Frontend	Expo (React Native) + TypeScript	ADR 002
API	Hono on Bun + tRPC (internal) + REST (public)	ADR 003
Database	PostgreSQL + Drizzle ORM / SQLite (self-hosted)	ADR 004
Offline Sync	Custom CRDT (Automerge)	ADR 005
Encryption	libsodium (E2E, zero-knowledge server)	ADR 006
Real-Time	WebSockets + SSE + Valkey	ADR 007
Runtime	Bun (Node.js fallback)	ADR 008
Media	S3-compatible (MinIO for self-hosted)	ADR 009
Job Queue	BullMQ (Valkey) / SQLite (self-hosted fallback)	ADR 010

All dependencies verified AGPL-3.0 compatible — see license audit. Architecture decisions documented in 34 ADRs.

Key Libraries

Library	Purpose	License
Expo	Cross-platform app framework (web, iOS, Android)	MIT
React Native	Native UI rendering	MIT
Hono	Lightweight HTTP framework	MIT
tRPC	End-to-end type-safe API layer	MIT
Drizzle ORM	TypeScript-first SQL ORM (PostgreSQL + SQLite)	Apache 2.0
Automerge	CRDT library for offline-first sync	MIT
libsodium	Cryptographic primitives (XChaCha20, X25519, Argon2id)	ISC
SQLCipher	Encrypted SQLite	BSD 3-Clause
Valkey	Pub/sub for real-time horizontal scaling	BSD 3-Clause
BullMQ	Background job queue (Valkey-backed)	MIT
pkapi.js	PluralKit API v2 client (import + bridge)	BSD 2-Clause
Resend	Transactional email API (hosted deployments)	MIT
Nodemailer	SMTP email delivery (self-hosted deployments)	MIT-0
MinIO	S3-compatible object storage (self-hosted media)	AGPL-3.0
Bun	JavaScript/TypeScript runtime	MIT

Features

Pluralscape targets full feature parity with Simply Plural, plus new capabilities. Key feature areas:

• Identity management — member profiles (pronouns, avatars, colors, custom fields, tags, saturation levels), groups/folders, archival, custom fronts
• Fronting and analytics — front logging with co-fronting as parallel timelines, historical editing, timeline visualization, analytics dashboards, automated check-in timers
• Communication — proxy-based system chat, board messages, private notes, polls with consensus analytics, mandatory acknowledgement routing
• Privacy and social — intersection-based privacy buckets (fail-closed), friend network with read-only dashboards, granular per-friend visibility, push notifications
• Journaling — polymorphic authorship (member, co-authored, or system-level), privacy bucket integration
• Data portability — Simply Plural and PluralKit import, full data export, PluralKit bridge, public REST API
• Self-hosted — two-tier deployment: minimal single binary for personal use, full Docker Compose for feature parity
• Encryption — end-to-end encrypted with XChaCha20-Poly1305, X25519 key exchange, Argon2id password hashing. Server is zero-knowledge
• Offline-first — local SQLite is source of truth, Automerge CRDT sync, cryptographic confirmation before deletion of local data

See the complete feature specification.

Development

Prerequisites

• Bun (runtime)
• pnpm 10.x (package manager)
• Node.js 18+ (for tooling compatibility)
• PostgreSQL 15+ (for integration tests)

Getting Started

pnpm install           # Install all dependencies
pnpm build             # Build all packages
pnpm dev               # Start all dev servers (turbo)

Available Scripts

pnpm dev               # Start all dev servers
pnpm build             # Build all packages
pnpm typecheck         # TypeScript type-checking (all packages)
pnpm lint              # Lint all packages (zero warnings enforced)
pnpm lint:fix          # Lint and auto-fix
pnpm format            # Check formatting (Prettier)
pnpm format:fix        # Auto-format
pnpm test              # Run all tests
pnpm test:unit         # Unit tests only
pnpm test:integration  # Integration tests only
pnpm test:coverage     # Tests with coverage report
pnpm test:e2e          # E2E tests (Playwright)
pnpm clean             # Clean build artifacts
pnpm roadmap           # Generate docs/roadmap.md from beans
pnpm codeql            # Run CodeQL security analysis
pnpm openapi:lint      # Validate OpenAPI spec
pnpm openapi:bundle    # Bundle multi-file spec into docs/openapi.yaml

Code Quality

Strict TypeScript and ESLint rules are enforced with zero warnings tolerance (--max-warnings 0). Key rules:

• No any, @ts-ignore, non-null assertions (!), or var
• No floating promises, swallowed errors, or console.log in production code
• Explicit return types on exported functions
• Exhaustive switch on union types
• All interactive UI elements must have accessibility props

Methodology

This project follows Test-Driven Development (TDD). All new code is written test-first: write a failing test, make it pass, refactor. See CONTRIBUTING.md for the full TDD guidelines.

Work Tracking

This project uses beans for issue tracking — beans are markdown files stored in .beans/ and committed with code. See docs/work-tracking.md for conventions.

Issue types: milestone > epic > feature / task / bug Domain prefixes: ps-, api-, mobile-, db-, crypto-, sync-, types-, client-, infra-

Architecture Decision Records

Major technical decisions are documented as ADRs in docs/adr/. 34 accepted ADRs cover the full stack from licensing through import engine architecture. See the ADR template for the format.

License

AGPL-3.0 — ensuring this project and all derivatives remain open source.

Contributing

We welcome contributions. See CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards.

Security

To report a vulnerability, see SECURITY.md. Vulnerabilities are handled through GitHub's private advisory system with a 48-hour acknowledgement SLA.