Realtime Poll App

Project roadmap

1. 01

   Define the protocol

   ~1.5h

   Write DESIGN.md: a session has a join code and a list of questions with their type and options; the host moves between questions and opens and closes answering; participants join with a random participant id stored in their browser. List the WebSocket messages in both directions (join, answer, current question and results) and the REST endpoints for creating sessions and exporting results. Done when: DESIGN.md defines the data and every message.

2. 02

   Build the server

   ~2.5h

   Build a Node.js server with a REST API to create a session (returning the join code and a secret host token) and a WebSocket server with the ws package. Store sessions, questions and answers in SQLite (with better-sqlite3), with a unique constraint on participant plus question so each can answer once. Validate every message and ignore invalid ones with an error reply. Broadcast updated results to the session after each answer. Done when: a script can create a session, join and answer, receiving live results.

3. 03

   Build the host screen

   ~2h

   Build a React page (with Vite) for hosts to create questions of each type, start the session, show the join code, move to the next question, open and close answering, and see results as they arrive: bar charts for choices and the average and distribution for ratings. Done when: a host can run through several questions and see live results for each.

4. 04

   Build the participant screen

   ~1.5h

   Build a mobile-friendly page where participants enter the code, see the current question when the host shows it, answer it (with the right input for each type), and then see the results. Show waiting states clearly (waiting for the next question and answering closed). Done when: several phones can follow along and answer each question.

5. 05

   Handle reconnects and duplicates

   ~1.5h

   Reconnect participants automatically with increasing waits, sending their participant id so they get the current question and their previous answer back. Reject second answers to the same question (from the database constraint), and limit how many messages a connection can send per second. Done when: refreshing or losing the connection never allows a second answer, and reconnecting restores the current state.

6. 06

   Export and test

   ~2h

   Add an export of a session's results as CSV and JSON for the host. Write tests with Vitest and the ws client: 30 simulated participants answering, duplicate answers rejected, answers after closing rejected, results matching the stored answers, and reconnection. Done when: all tests pass.

Resources

• Docsws: Node.js WebSocket library
• Docsbetter-sqlite3
• DocsMDN: writing WebSocket client applications
• DocsReact: quick start
• DocsVite: getting started