Improve README with usage instructions and tech overview

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Restore original README
2026-03-15 04:56:40 +01:00 · 2026-03-15 04:55:52 +01:00 · 2026-03-15 04:55:11 +01:00 · 2026-03-10 03:11:54 +01:00
6 changed files with 1793 additions and 221 deletions
--- a/README.md
+++ b/README.md
@@ -1,24 +1,40 @@
-# 🗳️ Simple P2P Poll & Chat
+# P2P Poll App
-This is a minimal prototype of a decentralized governance tool built for the **Demcode Evocracy** experiment. It allows for basic deliberation and voting without a central database or server-side logic.
+A peer-to-peer polling app where users can add options and vote on them. All data syncs directly between browsers using WebRTC — no central server stores any poll data.
-## What it does
+## How It Works
 - **P2P Connectivity:** Uses WebRTC (via PeerJS) to link browsers directly.
 - **Mesh-capable:** Allows multiple connections to sync the same poll state.
 - **Live Sync:** Changes to the poll topic, options, or votes are broadcast to all connected peers.
 - **Chat:** A simple sidebar to discuss the poll in real-time.
-## How to use it
+- **Yjs CRDTs** handle shared state — concurrent edits from different peers merge automatically without conflicts
-1. Open the page: [https://andrewlehr.github.io/evocracy-p2p-poll/]
+- **y-webrtc** establishes direct WebRTC connections between browsers (a public signaling server is used only for peer discovery)
-2. Set your **Nickname** and click "Set".
+- Each user gets a stable random ID (stored in localStorage) ensuring one vote per user per option
-3. Share your nickname with a friend.
+- Polls are identified by room name, shareable via URL
 4. One person enters the other's nickname in the **Connect** box and clicks "Add Peer".
 5. Once connected, you can set a topic, add options, and vote.
-## Technical Notes
+## Getting Started
 - **Data Persistence:** There is no database. If everyone closes their browser, the data is lost.
 - **Networking:** It uses a public signaling server to find peers, but the actual data (votes/chat) stays between the browsers.
 - **Conflict Handling:** Uses a simple "Last Write Wins" broadcast to keep peers in sync.
-## Transparency
+```bash
-This code was generated with the assistance of **Gemini (Google AI)** to quickly prototype the WebRTC networking logic. The goal was to create a clean, readable foundation that is easy for others to merge or modify during the next phase of the experiment.
+npm install
 npm run dev
 ```
 Open `http://localhost:5173` in your browser. To share a specific poll, use the `?room=` query parameter:
 ```
 http://localhost:5173/?room=my-poll
 ```
 Share this URL with others to join the same poll.
 ## Cross-Device Testing
 ```bash
 npm run dev -- --host
 ```
 Then open `http://<your-local-ip>:5173/?room=test` on another device on the same network.
 ## Tech Stack
 - [Yjs](https://yjs.dev/) — CRDT library for conflict-free shared state
 - [y-webrtc](https://github.com/yjs/y-webrtc) — WebRTC provider for P2P connectivity
 - [Vite](https://vite.dev/) — Dev server and bundler
 - Vanilla JS — No framework dependencies
--- a/index.html
+++ b/index.html
@@ -2,211 +2,32 @@
 <html lang="en">
 <head>
  <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Mesh Governance Tool</title>
+  <title>P2P Poll</title>
-    <script src="https://unpkg.com/peerjs@1.5.2/dist/peerjs.min.js"></script>
+  <link rel="stylesheet" href="/src/style.css">
    <style>
        :root { --primary: #007AFF; --bg: #f2f2f7; --success: #34c759; --secondary: #8e8e93; }
        * { box-sizing: border-box; }
        body { font-family: -apple-system, sans-serif; margin: 0; background: var(--bg); height: 100vh; display: flex; flex-direction: column; overflow: hidden; }
        /* Header & Peer List */
        .header { background: #fff; padding: 12px; border-bottom: 1px solid #d1d1d6; flex-shrink: 0; }
        .setup-row { display: flex; gap: 8px; margin-bottom: 10px; align-items: center; }
        .peer-list-container { display: flex; gap: 6px; overflow-x: auto; padding-bottom: 4px; scrollbar-width: none; }
        .peer-list-container::-webkit-scrollbar { display: none; }
        .peer-chip { background: #e9ecef; padding: 4px 10px; border-radius: 12px; font-size: 11px; white-space: nowrap; border: 1px solid #dee2e6; display: flex; align-items: center; gap: 5px; }
        .dot { width: 6px; height: 6px; background: var(--success); border-radius: 50%; }
        /* Main Layout */
        .main-container { display: flex; flex: 1; overflow: hidden; }
        @media (max-width: 768px) { .main-container { flex-direction: column; } }
        .column { flex: 1; display: flex; flex-direction: column; overflow: hidden; background: #fff; border-right: 1px solid #d1d1d6; }
        .scroll-area { flex: 1; overflow-y: auto; padding: 16px; -webkit-overflow-scrolling: touch; }
        /* Components */
        .card { background: #f9f9f9; border-radius: 10px; padding: 12px; margin-bottom: 15px; border: 1px solid #e5e5ea; }
        input { border: 1px solid #c6c6c8; padding: 10px; border-radius: 8px; font-size: 16px; width: 100%; outline: none; }
        button { background: var(--primary); color: white; border: none; padding: 10px; border-radius: 8px; font-weight: 600; cursor: pointer; }
        /* Poll UI */
        .poll-question { font-size: 20px; font-weight: 700; margin-bottom: 15px; color: var(--primary); }
        .option-item { display: flex; justify-content: space-between; align-items: center; background: white; padding: 12px; border-radius: 10px; margin-bottom: 8px; border: 1px solid #e5e5ea; }
        /* Chat UI */
        #chat-messages { display: flex; flex-direction: column; gap: 8px; }
        .msg { padding: 8px 12px; border-radius: 14px; max-width: 85%; font-size: 14px; }
        .msg.sent { background: var(--primary); color: white; align-self: flex-end; }
        .msg.received { background: #e5e5ea; color: black; align-self: flex-start; }
        .msg-sender { font-size: 10px; font-weight: bold; opacity: 0.7; display: block; }
        .chat-input-bar { padding: 12px; background: #fff; border-top: 1px solid #d1d1d6; display: flex; gap: 8px; padding-bottom: calc(12px + env(safe-area-inset-bottom)); }
    </style>
 </head>
 <body>
  <div id="app">
    <header>
      <h1>P2P Poll</h1>
      <div id="status">
        <span id="connection-status" class="connecting">Connecting...</span>
        <span id="peer-count">1 peer</span>
      </div>
    </header>
-    <div class="header">
+    <main>
-        <div class="setup-row">
+      <div id="add-option">
-            <span style="font-size: 13px;">Me: <strong id="my-id-display">...</strong></span>
+        <input type="text" id="option-input" placeholder="Add a poll option..." maxlength="100">
-            <div id="peer-list" class="peer-list-container">
+        <button id="add-btn">Add</button>
                </div>
        </div>
        <div class="setup-row">
            <input type="text" id="nickname-input" placeholder="My Name" style="flex: 0.5;">
            <button onclick="joinAs(document.getElementById('nickname-input').value)" style="background: var(--secondary); padding: 8px 12px;">Set</button>
            <input type="text" id="peer-id-input" placeholder="Friend's Name" style="flex: 1;">
            <button onclick="connectToPeer()" style="padding: 8px 12px;">Connect</button>
        </div>
      </div>
-    <div class="main-container">
+      <div id="poll-options"></div>
-        <div class="column">
+
-            <div class="scroll-area">
+      <p id="empty-state">No options yet. Add one above!</p>
-                <div class="card">
+    </main>
                    <input type="text" id="poll-title-input" placeholder="Question/Topic?">
                    <button onclick="updateTitle()" style="width:100%; margin-top:8px;">Set Topic</button>
                </div>
                <div id="active-question" class="poll-question">Waiting for Topic...</div>
                <div style="display:flex; gap:8px; margin-bottom:15px;">
                    <input type="text" id="new-option-text" placeholder="Add option...">
                    <button onclick="addOption()">Add</button>
                </div>
                <div id="poll-container"></div>
            </div>
  </div>
-        <div class="column">
+  <script type="module" src="/src/main.js"></script>
            <div class="scroll-area" id="chat-scroll">
                <div id="chat-messages"></div>
            </div>
            <div class="chat-input-bar">
                <input type="text" id="chat-input" placeholder="Discuss...">
                <button onclick="sendMessage()">Send</button>
            </div>
        </div>
    </div>
    <script>
        let pollData = { question: "Open Discussion", options: [] };
        let myName = "";
        let connections = []; 
        let peer = null;
        function joinAs(id) {
            if (peer) peer.destroy();
            peer = new Peer(id || undefined);
            peer.on('open', newId => { 
                myName = newId; 
                document.getElementById('my-id-display').innerText = newId; 
            });
            peer.on('connection', conn => setupConnection(conn));
        }
        function connectToPeer() {
            const target = document.getElementById('peer-id-input').value;
            if (target && target !== myName) {
                setupConnection(peer.connect(target));
            }
            document.getElementById('peer-id-input').value = "";
        }
        function setupConnection(conn) {
            conn.on('open', () => {
                // Prevent duplicate connections
                if (!connections.find(c => c.peer === conn.peer)) {
                    connections.push(conn);
                    updatePeerUI();
                    broadcast({ type: 'SYNC', payload: pollData });
                }
            });
            conn.on('data', data => {
                if (data.type === 'SYNC') {
                    pollData = data.payload;
                    renderPoll();
                } else if (data.type === 'CHAT') {
                    appendMessage(data.sender, data.payload, 'received');
                }
            });
            conn.on('close', () => {
                connections = connections.filter(c => c.peer !== conn.peer);
                updatePeerUI();
            });
        }
        function broadcast(data) {
            connections.forEach(c => { if (c.open) c.send(data); });
        }
        function updatePeerUI() {
            const list = document.getElementById('peer-list');
            if (connections.length === 0) {
                list.innerHTML = '<span style="font-size:11px; color:#999;">No peers connected</span>';
                return;
            }
            list.innerHTML = connections.map(c => `
                <div class="peer-chip"><div class="dot"></div>${c.peer}</div>
            `).join('');
        }
        // --- APP LOGIC ---
        function updateTitle() {
            const val = document.getElementById('poll-title-input').value;
            if (!val) return;
            pollData.question = val;
            renderPoll();
            broadcast({ type: 'SYNC', payload: pollData });
        }
        function addOption() {
            const txt = document.getElementById('new-option-text').value;
            if (!txt) return;
            pollData.options.push({ text: txt, votes: 0 });
            document.getElementById('new-option-text').value = "";
            renderPoll();
            broadcast({ type: 'SYNC', payload: pollData });
        }
        function vote(i) {
            pollData.options[i].votes++;
            renderPoll();
            broadcast({ type: 'SYNC', payload: pollData });
        }
        function renderPoll() {
            document.getElementById('active-question').innerText = pollData.question;
            const container = document.getElementById('poll-container');
            container.innerHTML = pollData.options.map((opt, i) => `
                <div class="option-item">
                    <span>${opt.text}</span>
                    <div style="display:flex; align-items:center;">
                        <span style="font-weight:bold; color:var(--primary); margin-right:12px; font-size:18px;">${opt.votes}</span>
                        <button onclick="vote(${i})" style="background:var(--success); padding:5px 12px;">Vote</button>
                    </div>
                </div>
            `).join('');
        }
        function sendMessage() {
            const input = document.getElementById('chat-input');
            if (!input.value) return;
            broadcast({ type: 'CHAT', sender: myName, payload: input.value });
            appendMessage('You', input.value, 'sent');
            input.value = "";
        }
        function appendMessage(sender, text, side) {
            const div = document.createElement('div');
            div.className = `msg ${side}`;
            div.innerHTML = `<span class="msg-sender">${sender}</span>${text}`;
            document.getElementById('chat-messages').appendChild(div);
            const scroll = document.getElementById('chat-scroll');
            scroll.scrollTop = scroll.scrollHeight;
        }
        document.getElementById('chat-input').addEventListener('keypress', (e) => { if (e.key === 'Enter') sendMessage(); });
        joinAs(null);
    </script>
 </body>
 </html>
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -0,0 +1,18 @@
 {
  "name": "p2p-poll",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "yjs": "^13.6.0",
    "y-webrtc": "^10.3.0"
  },
  "devDependencies": {
    "vite": "^6.0.0"
  }
 }
--- a/src/main.js
+++ b/src/main.js
@@ -0,0 +1,136 @@
 import * as Y from 'yjs';
 import { WebrtcProvider } from 'y-webrtc';
 // --- Peer ID (stable across reloads) ---
 function getOrCreatePeerId() {
  let id = localStorage.getItem('peer-id');
  if (!id) {
    id = crypto.randomUUID();
    localStorage.setItem('peer-id', id);
  }
  return id;
 }
 const peerId = getOrCreatePeerId();
 // --- Room name from URL ---
 function getRoomName() {
  const params = new URLSearchParams(window.location.search);
  return params.get('room') || 'default-poll';
 }
 const roomName = getRoomName();
 // --- Yjs setup ---
 const ydoc = new Y.Doc();
 const provider = new WebrtcProvider(roomName, ydoc);
 const yOptions = ydoc.getMap('poll-options');
 // --- Data operations ---
 function addOption(name) {
  const id = crypto.randomUUID();
  const optionMap = new Y.Map();
  optionMap.set('name', name);
  optionMap.set('votes', new Y.Map());
  yOptions.set(id, optionMap);
 }
 function toggleVote(optionId) {
  const optionMap = yOptions.get(optionId);
  if (!optionMap) return;
  const votes = optionMap.get('votes');
  if (votes.has(peerId)) {
    votes.delete(peerId);
  } else {
    votes.set(peerId, true);
  }
 }
 // --- UI rendering ---
 const container = document.getElementById('poll-options');
 const emptyState = document.getElementById('empty-state');
 function render() {
  container.innerHTML = '';
  const entries = [];
  yOptions.forEach((optionMap, id) => {
    entries.push({
      id,
      name: optionMap.get('name'),
      votes: optionMap.get('votes').size,
      voted: optionMap.get('votes').has(peerId),
    });
  });
  entries.sort((a, b) => b.votes - a.votes || a.name.localeCompare(b.name));
  emptyState.className = entries.length > 0 ? 'hidden' : '';
  for (const entry of entries) {
    const div = document.createElement('div');
    div.className = 'poll-option';
    const nameSpan = document.createElement('span');
    nameSpan.className = 'option-name';
    nameSpan.textContent = entry.name;
    const voteCount = document.createElement('span');
    voteCount.className = 'vote-count';
    voteCount.textContent = entry.votes;
    const voteBtn = document.createElement('button');
    voteBtn.className = entry.voted ? 'vote-btn voted' : 'vote-btn';
    voteBtn.textContent = entry.voted ? 'Unvote' : 'Vote';
    voteBtn.addEventListener('click', () => toggleVote(entry.id));
    div.append(nameSpan, voteCount, voteBtn);
    container.appendChild(div);
  }
 }
 // Re-render on any change in the shared state
 yOptions.observeDeep(() => render());
 // --- Add option handlers ---
 const input = document.getElementById('option-input');
 const addBtn = document.getElementById('add-btn');
 addBtn.addEventListener('click', () => {
  const name = input.value.trim();
  if (name) {
    addOption(name);
    input.value = '';
  }
 });
 input.addEventListener('keydown', (e) => {
  if (e.key === 'Enter') addBtn.click();
 });
 // --- Connection status & peer count ---
 const statusEl = document.getElementById('connection-status');
 const peerCountEl = document.getElementById('peer-count');
 provider.on('synced', ({ synced }) => {
  statusEl.textContent = synced ? 'Connected' : 'Connecting...';
  statusEl.className = synced ? 'connected' : 'connecting';
 });
 function updatePeerCount() {
  const count = provider.awareness.getStates().size;
  peerCountEl.textContent = `${count} peer${count !== 1 ? 's' : ''}`;
 }
 provider.awareness.on('change', updatePeerCount);
 updatePeerCount();
 // --- Initial render ---
 render();
--- a/src/style.css
+++ b/src/style.css
@@ -0,0 +1,144 @@
 * {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
 }
 body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  background: #f5f5f5;
  color: #333;
  min-height: 100vh;
 }
 #app {
  max-width: 600px;
  margin: 0 auto;
  padding: 2rem 1rem;
 }
 header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 2rem;
 }
 h1 {
  font-size: 1.5rem;
 }
 #status {
  display: flex;
  gap: 1rem;
  font-size: 0.85rem;
  color: #666;
 }
 #connection-status::before {
  content: "";
  display: inline-block;
  width: 8px;
  height: 8px;
  border-radius: 50%;
  margin-right: 4px;
  vertical-align: middle;
 }
 #connection-status.connected::before {
  background: #4caf50;
 }
 #connection-status.connecting::before {
  background: #ff9800;
 }
 #add-option {
  display: flex;
  gap: 0.5rem;
  margin-bottom: 1.5rem;
 }
 #option-input {
  flex: 1;
  padding: 0.6rem 0.8rem;
  border: 1px solid #ddd;
  border-radius: 6px;
  font-size: 1rem;
  outline: none;
 }
 #option-input:focus {
  border-color: #2196f3;
 }
 #add-btn {
  padding: 0.6rem 1.2rem;
  background: #2196f3;
  color: white;
  border: none;
  border-radius: 6px;
  font-size: 1rem;
  cursor: pointer;
 }
 #add-btn:hover {
  background: #1976d2;
 }
 .poll-option {
  display: flex;
  align-items: center;
  background: white;
  padding: 0.8rem 1rem;
  border-radius: 8px;
  margin-bottom: 0.5rem;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
 }
 .option-name {
  flex: 1;
  font-size: 1rem;
 }
 .vote-count {
  font-size: 0.9rem;
  font-weight: 600;
  color: #666;
  margin-right: 0.75rem;
  min-width: 1.5rem;
  text-align: center;
 }
 .vote-btn {
  padding: 0.4rem 1rem;
  border: 2px solid #2196f3;
  border-radius: 6px;
  font-size: 0.85rem;
  cursor: pointer;
  background: white;
  color: #2196f3;
 }
 .vote-btn:hover {
  background: #e3f2fd;
 }
 .vote-btn.voted {
  background: #2196f3;
  color: white;
 }
 .vote-btn.voted:hover {
  background: #1976d2;
 }
 #empty-state {
  text-align: center;
  color: #999;
  padding: 2rem;
 }
 #empty-state.hidden {
  display: none;
 }
Author	SHA1	Message	Date
Patrick Charrier	e30de01c86	Improve README with usage instructions and tech overview Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-15 04:56:40 +01:00
Patrick Charrier	2490a267ee	Restore original README Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-15 04:55:52 +01:00
Patrick Charrier	2af5da59c4	Implement P2P polling app with Yjs and WebRTC Uses Yjs CRDTs for conflict-free shared state and y-webrtc for peer-to-peer data exchange. Users can add poll options and vote/unvote, with all changes syncing in real-time across connected peers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-15 04:55:11 +01:00
Patrick Charrier	4a208ba05b	feat: add comment	2026-03-10 03:11:54 +01:00