# srinivas26k/poll-webapp architecture

> Architecture diagram of the GitHub repository srinivas26k/poll-webapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srinivas26k/poll-webapp
- Repository: https://github.com/srinivas26k/poll-webapp

## Overview

##### Project type and purpose
- This is a full-stack, real-time quiz application.
- Frontend: React + TypeScript single-page app (Host & Participant roles).
- Backend: Node/Express + TypeScript REST API for session and quiz management.
- Real-time layer: Pusher (pub/sub) for broadcasting transcripts and quiz events.
- AI integration: Generates polls/quizzes from transcripts every five minutes.

##### Main components
a. Frontend – Host UI
- React component tree under src/components/Host
- Uses Web Speech API (speechRecognition.ts) to capture audio and produce transcripts
- Sends transcripts to backend or directly to Pusher via pusherService.ts
- Controls session lifecycle (create/join/end) via sessionController endpoints
b. Frontend – Participant UI
- React component tree under src/components/Participant
- Subscribes to real-time channels for live transcripts and quiz events
- Renders transcripts in real time and displays polls/quizzes
c. Backend – Express Server
- Entry point: server/server.ts (or server.js)
- Routes: server/routes/index.ts
- Controllers:
– sessionController.ts (create/join sessions, session state)
– quizController.ts (trigger quiz generation, receive answers)
- AI Service (could live in backend or client as aiService.ts) that uses an external NLP/ML API to create questions
- No persistent database shown (in-memory session store implied)
d. Real-time Pub/Sub Layer
- Pusher (via pusherService.ts) as external cloud service
- Channels for “session-<id>-transcripts” and “session-<id>-quizzes”
e. External APIs
- Web Speech API (browser) for transcription
- AI provider (OpenAI or custom) for quiz generation

##### Relationships and data flows
1. Host clicks “Start Session” → Frontend calls HTTP POST /sessions → Backend creates session, returns sessionId.
2. Host’s browser activates Web Speech API → transcripts fed to speechRecognition.ts → forwarded via pusherService or HTTP POST /sessions/:id/transcript → Backend receives transcript.
3. Backend broadcasts transcript over Pusher channel → Participant UIs receive real-time updates.
4. Every 5 minutes a timer triggers quizController → fetches accumulated transcripts → calls AI Service → generates poll questions → broadcasts quiz event via Pusher.
5. Participants answer quizzes → answers sent back via HTTP POST /quizzes/:id/answers → quizController records/rates responses → may broadcast results.

##### Architectural patterns and design principles
- Pub/Sub for real-time communication (decouples sender/receivers)
- MVC-style on backend (routes → controllers → service logic)
- Single-page app on frontend with component separation (Host vs Participant)
- Periodic batch processing for quiz generation (timers + AI service)

- Components: Host UI, Participant UI, Express API (SessionController, QuizController), AI Service, Pusher
- “start session” HTTP call
- “send transcript” flow
- “broadcast transcript” flow
- “generate quiz” flow
- “answer quiz” flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        StaticPage["public/index.html"]:::frontend
        AppRoot["App\n(src/App.tsx)"]:::frontend
        IndexEntry["index.tsx\n(src/index.tsx)"]:::frontend
        HostUI["Host UI\n(src/components/Host/Host.tsx)"]:::frontend
        ParticipantUI["Participant UI\n(src/components/Participant/Participant.tsx)"]:::frontend
        speechRec["SpeechRecognition\n(src/services/speechRecognition.ts)"]:::frontend
        pusherClient["PusherService\n(src/services/pusherService.ts)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend" 
        direction TB
        ExpressEntry["Express Server\n(server/server.ts)"]:::backend
        Routes["API Routes\n(server/routes/index.ts)"]:::backend
        SessionCtrl["SessionController\n(server/controllers/sessionController.ts)"]:::backend
        QuizCtrl["QuizController\n(server/controllers/quizController.ts)"]:::backend
        aiServiceNode["AI Service\n(src/services/aiService.ts)"]:::backend
        Timer["5-min Timer"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        WebSpeechAPI["Web Speech API"]:::external
        PusherCloud["Pusher (Pub/Sub)"]:::external
        AIProvider["AI Provider API"]:::external
    end

    %% Flows
    StaticPage --> AppRoot
    AppRoot --> IndexEntry
    AppRoot --> HostUI
    AppRoot --> ParticipantUI

    HostUI -->|"use Web Speech API"| speechRec
    speechRec --> WebSpeechAPI
    WebSpeechAPI --> speechRec
    speechRec -->|"forward transcript"| pusherClient
    pusherClient -->|"publish transcript"| PusherCloud
    pusherClient -->|"publish transcript HTTP"| ExpressEntry

    HostUI -->|"POST /sessions"| ExpressEntry
    ExpressEntry --> Routes
    Routes --> SessionCtrl
    SessionCtrl --> ExpressEntry
    ExpressEntry --> HostUI

    ParticipantUI -->|"subscribe channels"| pusherClient
    PusherCloud --> ParticipantUI

    Timer -.-> QuizCtrl
    QuizCtrl --> aiServiceNode
    aiServiceNode --> AIProvider
    AIProvider --> aiServiceNode
    aiServiceNode --> QuizCtrl
    QuizCtrl -->|"broadcast quiz"| pusherClient
    pusherClient --> ParticipantUI

    ParticipantUI -->|"POST /quizzes/:id/answers"| ExpressEntry
    ExpressEntry --> Routes
    Routes --> QuizCtrl
    QuizCtrl --> ExpressEntry

    %% Click Events
    click HostUI "https://github.com/srinivas26k/poll-webapp/blob/master/src/components/Host/Host.tsx"
    click ParticipantUI "https://github.com/srinivas26k/poll-webapp/blob/master/src/components/Participant/Participant.tsx"
    click speechRec "https://github.com/srinivas26k/poll-webapp/blob/master/src/services/speechRecognition.ts"
    click pusherClient "https://github.com/srinivas26k/poll-webapp/blob/master/src/services/pusherService.ts"
    click aiServiceNode "https://github.com/srinivas26k/poll-webapp/blob/master/src/services/aiService.ts"
    click ExpressEntry "https://github.com/srinivas26k/poll-webapp/blob/master/server/server.ts"
    click Routes "https://github.com/srinivas26k/poll-webapp/blob/master/server/routes/index.ts"
    click SessionCtrl "https://github.com/srinivas26k/poll-webapp/blob/master/server/controllers/sessionController.ts"
    click QuizCtrl "https://github.com/srinivas26k/poll-webapp/blob/master/server/controllers/quizController.ts"
    click IndexEntry "https://github.com/srinivas26k/poll-webapp/blob/master/src/index.tsx"
    click AppRoot "https://github.com/srinivas26k/poll-webapp/blob/master/src/App.tsx"
    click StaticPage "https://github.com/srinivas26k/poll-webapp/blob/master/public/index.html"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend  fill:#E2F0D9,stroke:#28A745,color:#28A745
    classDef external fill:#FFF4DB,stroke:#FFC107,color:#BF8700
    class HostUI,ParticipantUI,AppRoot,IndexEntry,StaticPage,speechRec,pusherClient frontend
    class ExpressEntry,Routes,SessionCtrl,QuizCtrl,aiServiceNode,Timer backend
    class WebSpeechAPI,PusherCloud,AIProvider external
```
