# 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)

**Waku documentation:** https://waku.gg/llms.txt

## Commands

```bash
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