Improve README with usage instructions and tech overview

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

README.md

@@ -1,39 +1,40 @@
 # P2P Poll App
 
-There are various issues of Trust:
-The possiblity to generate lots of users that do a lot of things (at a rather low cost)
-The possibility to put out wrong data, maby not even contradicting but additional to existing data.
-The possibility to do all kinds of shenenigans like spam other users with some requests
+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.
 
-Due to low programming knowledge, the starting point of this proposal was to mirror how normal groups of people solve issues of trust to then automate and possibly improve the process. There are already some systems out there like Trust flow or random walk. As far as i understand it, the Flexible Trust Web also already does something like this, also maby RWOT and GNUweb but i didn't read into them too much since i discovered them rather late and want to look for feedback anyway. After all, a system with a clearer consensus might be preferable to some.
+## How It Works
 
-If random new people should be able to use the system as equals to previous users, but the system never has real identities as an input, then there is no way to fully prevent the creation of new users to manipulate or sabotage the poll. But it can be assumed, that your friends are rather trustworthy and most likely also their friends and so on. And if someone makes huge ammounts or just one second account, they will probably only have the creator or maby some other people as friends, and even they might already be less socially connected than a normal user.
-So the social distance to another user should be evaluated to see, whether you should count their vote.
-This is evaluated for and by every user individually, based on the information they were sent. The ammount of contacts you won't count are displayed to you, such that you get a hint at how many people you are missing but also how many people are not counting you. This encourages people to try to prove others/vise versa and make social connections to officially tie the network closer together such that the voting system works and confirms itself. It would be great, if there was some chat attached to the poll. If people want to prove their (or others) trusworhiness within this system, they are then also encouraged to have productive discussions, probably about the matter of the poll.
-Everyone in a poll with you is a "contact" of yours.
-"users" can have "friends".
-You can also manually mark users as suspicious or trustworthy or normal again.
-The system for evaluating the trustworthyness of users is somehow a mix between the concepts "weighted path score" and "trust flow" with 5 steps.
-That means for 5 steps starting with you, all friends and trusted people of people looked at in this step get some trust from the people we look at: 0.8 * The trust of the looked at person (if trusted) + 0.8 * The trust of the looked at person / friends the looked at person has (if friend). Then the trust of the person that received trust may maximally be 100. The Trust you have to yourself is 100.
-You can also mark someone as trustworthy or untrustworthy. That is then also sent around to everyone if you want(should be the standard, but maby a user wants to just see how the trustworthyness will look like after the change).
-If you receive such an information, you can make the following calculations immidiately and after every assesment of everyones trustworthyness:
-If the accused is less trustworthy then the accusing person, decrease the accused trustworthyness to 0 and the accused friends and trustees trustworthyness by the trustworthyness of the accusing person.
-If the trustworhyness of the accusing person is less than the trustworthyness of the accused, then reduce the trustworthyness of the accusing person to 0 and the accusing persons friends and trustees by the trustworthyness of the accused * 0,2.
-If you mark someone as trustworthy:
-The Trust flowing to the trusted person from you will also be 0.8 of your trust.
-Maby this should also be the effect of beeing "friends" since "trust" might be something you could more intuitively casually deal out after a short chat. If that change were to occur, then the effect would have to be switched around.
-All contacts can maximally have the Trust 100.
+- **Yjs CRDTs** handle shared state — concurrent edits from different peers merge automatically without conflicts
+- **y-webrtc** establishes direct WebRTC connections between browsers (a public signaling server is used only for peer discovery)
+- Each user gets a stable random ID (stored in localStorage) ensuring one vote per user per option
+- Polls are identified by room name, shareable via URL
 
+## Getting Started
 
-Future matters:
-If there can be any discrepancy of sent information, depending on what sender you trust most, you will mark one of the senders as untrustworthy and neglect all future information from this user. Since everything can be signed and such, that shouldnˋt be an issue tho, but if it was, the ammount of "useless" messages to already informed people might have to increase to validate received data.
-A system to showcase the social connections in a 2D - format would be neat.
-(most likely something like this exists already)
-Obviously the user would also have to see other context like the total of all votes (trusted or not)
+```bash
+npm install
+npm run dev
+```
 
-Anonymous polls:
-A system of individually assigned trust poses a challenge for a system where you can decide not to trust some voters.
-If there is no other option some compromises might be makable, such as:
--Your Friends can know what you voted for
--The Person initiating a poll just decides on the validity of participants according to an own judgement of trust at the moment of poll-creation
--A System with clear Consensus of who to trust
+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

index.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>P2P Poll</title>
+  <link rel="stylesheet" href="/src/style.css">
+</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>
+
+    <main>
+      <div id="add-option">
+        <input type="text" id="option-input" placeholder="Add a poll option..." maxlength="100">
+        <button id="add-btn">Add</button>
+      </div>
+
+      <div id="poll-options"></div>
+
+      <p id="empty-state">No options yet. Add one above!</p>
+    </main>
+  </div>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>

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"
+  }
+}

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();

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;
+}