56 lines
2.4 KiB
Markdown
56 lines
2.4 KiB
Markdown
# 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
|