# maharajan07/live-polling-system architecture

> Architecture diagram of the GitHub repository maharajan07/live-polling-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maharajan07/live-polling-system
- Repository: https://github.com/maharajan07/live-polling-system

## Overview

#### Purpose and Entry Points
This is a full-stack, single-session live polling and chat system for teacher and student roles. The React client starts at `client/src/main.jsx`, renders the application shell in `client/src/App.jsx`, and connects to real-time services through `client/src/socket.js`. The Node/Express and Socket.IO server entry point is `server/index.js`; it also serves the production client build from `client/dist`.

#### Client Application Shell and Role Flow
`client/src/App.jsx` owns high-level client state and routes users into teacher or student experiences rather than using a separate page-based router. Role-specific UI is implemented by `client/src/components/TeacherPanel.jsx` and `client/src/components/StudentPanel.jsx`; supporting home/join state is in `client/src/components/Home.jsx`. A student identity is intended to be unique per browser tab, establishing the client-side boundary between participants.

#### Teacher Poll Authoring and Session Control
The teacher workflow is centered on `client/src/components/TeacherPanel.jsx`, with poll input captured by `client/src/components/QuestionForm.jsx` and aggregate state rendered by `client/src/components/ResultPanel.jsx`. Teachers launch timed questions, observe live answer counts, and can remove students. Poll creation is gated by the completion of the active poll, making the server-managed poll lifecycle a central control boundary.

#### Student Answering and Result Consumption
`client/src/components/StudentPanel.jsx` receives the active question, lets the student submit an answer, and transitions to results after submission or poll timeout. `client/src/components/ResultPanel.jsx` is the shared presentation boundary for live/finished poll outcomes. A removal event is represented by `client/src/components/KickedOut.jsx`, preventing a removed participant from continuing normal session interaction.

#### Real-Time Transport and Server Authority
Socket.IO is the primary control and data channel, initialized client-side in `client/src/socket.js` and handled server-side in `server/index.js`. The server is the authority for connected participants, active poll state, submitted answers, timer/completion events, chat broadcasts, and student removal. Clients emit user actions and react to broadcast state/events; no persistent database layer is present in the repository, so session data is likely process-memory scoped.

#### Chat Subsystem
Chat is a parallel real-time interaction flow available to both roles. `client/src/components/ChatPopup.jsx` provides the client chat surface, while `client/src/socket.js` transports messages to and from `server/index.js`. Role-aware message rendering distinguishes teacher and student contributions without requiring HTTP refreshes.

#### Runtime, Build, and Deployment Boundary
The frontend is a Vite-built React application (`client/package.json`, `client/vite.config.js`) whose production assets are committed under `client/dist/index.html` and `client/dist/assets`. The backend is a Node.js Express runtime with Socket.IO (`server/package.json`, `server/index.js`) and serves the built SPA in production. The documented deployment target is Render; the externally exposed server must support both static asset delivery and persistent WebSocket-compatible Socket.IO connections.

Main entry points: [`client/src/App.jsx`](https://github.com/maharajan07/live-polling-system/blob/main/client/src/App.jsx) (App shell & role state), [`server/index.js`](https://github.com/maharajan07/live-polling-system/blob/main/server/index.js) (Express + Socket.IO server), [`client/src/components/TeacherPanel.jsx`](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/TeacherPanel.jsx) (Teacher controls), [`client/src/socket.js`](https://github.com/maharajan07/live-polling-system/blob/main/client/src/socket.js) (Socket client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_entry["Client entry<br/>React bootstrap<br/>[main.jsx]"]
  node_app_shell["App shell &amp; role state<br/>React application<br/>[App.jsx]"]
  node_home_join["Home &amp; join<br/>role entry UI<br/>[Home.jsx]"]
  node_teacher_panel["Teacher controls<br/>teacher UI<br/>[TeacherPanel.jsx]"]
  node_question_form["Question authoring<br/>poll form<br/>[QuestionForm.jsx]"]
  node_student_panel["Student answering<br/>student UI<br/>[StudentPanel.jsx]"]
  node_results["Live results<br/>shared results UI<br/>[ResultPanel.jsx]"]
  node_chat["Chat popup<br/>chat UI<br/>[ChatPopup.jsx]"]
  node_kicked_out["Removal state<br/>access-blocking UI<br/>[KickedOut.jsx]"]
  node_socket_client["Socket client<br/>Socket.IO transport<br/>[socket.js]"]
end

subgraph group_server["Node real-time server"]
  node_server{{"Express + Socket.IO server<br/>session authority<br/>[index.js]"}}
  node_session_state[("In-memory session state<br/>ephemeral state")]
end

subgraph group_delivery["Build &amp; hosting"]
  node_vite_build["Vite production build<br/>frontend build<br/>[vite.config.js]"]
  node_built_spa["Built SPA assets<br/>static bundle<br/>[index.html]"]
end

node_client_entry -->|"renders"| node_app_shell
node_app_shell -->|"starts at"| node_home_join
node_app_shell -->|"teacher role"| node_teacher_panel
node_app_shell -->|"student role"| node_student_panel
node_teacher_panel -->|"authors polls"| node_question_form
node_teacher_panel -->|"observes counts"| node_results
node_student_panel -->|"consumes outcome"| node_results
node_app_shell -->|"opens"| node_chat
node_app_shell -.->|"removal event"| node_kicked_out
node_teacher_panel -->|"poll and removal actions"| node_socket_client
node_student_panel -->|"answers"| node_socket_client
node_chat -->|"messages"| node_socket_client
node_socket_client -->|"Socket.IO events"| node_server
node_server -->|"manages"| node_session_state
node_server -.->|"poll updates"| node_results
node_server -.->|"removal broadcast"| node_kicked_out
node_vite_build -->|"produces"| node_built_spa
node_built_spa -->|"served in production"| node_server

click node_client_entry "https://github.com/maharajan07/live-polling-system/blob/main/client/src/main.jsx"
click node_app_shell "https://github.com/maharajan07/live-polling-system/blob/main/client/src/App.jsx"
click node_home_join "https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/Home.jsx"
click node_teacher_panel "https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/TeacherPanel.jsx"
click node_question_form "https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/QuestionForm.jsx"
click node_student_panel "https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/StudentPanel.jsx"
click node_results "https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/ResultPanel.jsx"
click node_chat "https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/ChatPopup.jsx"
click node_kicked_out "https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/KickedOut.jsx"
click node_socket_client "https://github.com/maharajan07/live-polling-system/blob/main/client/src/socket.js"
click node_server "https://github.com/maharajan07/live-polling-system/blob/main/server/index.js"
click node_vite_build "https://github.com/maharajan07/live-polling-system/blob/main/client/vite.config.js"
click node_built_spa "https://github.com/maharajan07/live-polling-system/blob/main/client/dist/index.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_entry,node_app_shell,node_home_join,node_teacher_panel,node_question_form,node_student_panel,node_results,node_chat,node_kicked_out,node_socket_client toneBlue
class node_server,node_session_state toneAmber
class node_vite_build,node_built_spa toneMint
```

## Components

### React client

- [Client entry](https://github.com/maharajan07/live-polling-system/blob/main/client/src/main.jsx): React bootstrap · `client/src/main.jsx`
- [App shell & role state](https://github.com/maharajan07/live-polling-system/blob/main/client/src/App.jsx): React application · Routes users into teacher or student flows without page routing. · `client/src/App.jsx`
- [Home & join](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/Home.jsx): role entry UI · Establishes role and tab-scoped student identity. · `client/src/components/Home.jsx`
- [Teacher controls](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/TeacherPanel.jsx): teacher UI · Controls poll lifecycle and student removal. · `client/src/components/TeacherPanel.jsx`
- [Question authoring](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/QuestionForm.jsx): poll form · `client/src/components/QuestionForm.jsx`
- [Student answering](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/StudentPanel.jsx): student UI · Submits answers and transitions on completion or timeout. · `client/src/components/StudentPanel.jsx`
- [Live results](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/ResultPanel.jsx): shared results UI · `client/src/components/ResultPanel.jsx`
- [Chat popup](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/ChatPopup.jsx): chat UI · Renders role-aware chat messages. · `client/src/components/ChatPopup.jsx`
- [Removal state](https://github.com/maharajan07/live-polling-system/blob/main/client/src/components/KickedOut.jsx): access-blocking UI · `client/src/components/KickedOut.jsx`
- [Socket client](https://github.com/maharajan07/live-polling-system/blob/main/client/src/socket.js): Socket.IO transport · `client/src/socket.js`

### Node real-time server

- [Express + Socket.IO server](https://github.com/maharajan07/live-polling-system/blob/main/server/index.js): session authority · Owns in-memory participants, polls, answers, timers, chat, and removal events. · `server/index.js`
- **In-memory session state**: ephemeral state · State is scoped to the server process; no database is present.

### Build & hosting

- [Vite production build](https://github.com/maharajan07/live-polling-system/blob/main/client/vite.config.js): frontend build · `client/vite.config.js`
- [Built SPA assets](https://github.com/maharajan07/live-polling-system/blob/main/client/dist/index.html): static bundle · Production React assets served by Express. · `client/dist/index.html`

## Connections

- Client entry → App shell & role state: renders
- App shell & role state → Home & join: starts at
- App shell & role state → Teacher controls: teacher role
- App shell & role state → Student answering: student role
- Teacher controls → Question authoring: authors polls
- Teacher controls → Live results: observes counts
- Student answering → Live results: consumes outcome
- App shell & role state → Chat popup: opens
- App shell & role state → Removal state: removal event
- Teacher controls → Socket client: poll and removal actions
- Student answering → Socket client: answers
- Chat popup → Socket client: messages
- Socket client → Express + Socket.IO server: Socket.IO events · Bidirectional real-time control and broadcast channel.
- Express + Socket.IO server → In-memory session state: manages
- Express + Socket.IO server → Live results: poll updates
- Express + Socket.IO server → Removal state: removal broadcast
- Vite production build → Built SPA assets: produces
- Built SPA assets → Express + Socket.IO server: served in production