CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

P2P Poll App — a peer-to-peer polling application for the Evocracy democratic coding research experiment (https://demcode.evocracy.org/).

Goal

Build a simple P2P polling app where users can add poll options and vote. Data exchange works peer-to-peer between clients (no central server for data), though a signaling/sync server for connection establishment is acceptable.

Research Context

Phase 1 (2 weeks): Submit individual code proposal
Phase 2: Groups of 3 merge solutions into a working prototype
Phase 3: Representatives iteratively merge until one final solution remains
Code must be clean, explainable, and easy to merge with others' work
Final code published open-source under MIT license
Language: JavaScript/TypeScript

Tech Stack

Runtime: Bun
Framework: Waku (minimal React framework with RSC support)
Styling: Tailwind CSS v4
P2P/Data sync: Automerge with automerge-repo (CRDT-based)
Networking: automerge-repo-network-websocket (WebSocketClientAdapter) + automerge-repo-network-broadcastchannel (cross-tab sync)
Storage: automerge-repo-storage-indexeddb (client-side persistence)

Commands

bun install          # Install dependencies
bun run dev          # Start dev server
bun run build        # Production build
bun test             # Run tests (Bun's built-in test runner)

Architecture

Waku pages router: pages live in src/pages/, layouts in _layout.tsx
Client components use 'use client' directive
Automerge Repo is initialized in a client-side provider component wrapping the app
The shared CRDT document holds the poll state (title, options, votes)
Peers sync via a lightweight WebSocket sync server (can use automerge-repo sync server or the public wss://sync.automerge.org)
BroadcastChannelNetworkAdapter enables cross-tab sync
useDocument hook from @automerge/automerge-repo-react-hooks for reactive document access
Every Waku page/layout must export getConfig specifying render mode ('static' or 'dynamic')

Key Design Principles

Keep it simple and merge-friendly for Phase 2 group work
Minimal file count, clear separation of concerns
No over-engineering — this is a research experiment, not production software

2.4 KiB Raw Blame History