# continuousactivelearning/poll-question-gen architecture

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

- Interactive diagram: https://gitdiagram.com/continuousactivelearning/poll-question-gen
- Repository: https://github.com/continuousactivelearning/poll-question-gen

## Overview

##### Project Type and Purpose
- This is a full-stack, interactive “Poll Automation System” designed for educational live polling.
- Frontend: React (TypeScript) SPA built with Vite, Firebase Authentication, and a shadcn/ui component library.
- Backend: Node.js + TypeScript (Inversify for DI, class-validator/transformer, OpenAPI generation) deployed as Firebase Cloud Functions. Uses MongoDB for persistence, integrates with Firebase Auth, Sentry, SMTP, and OpenAI APIs for GenAI services.

##### File Structure Analysis
- Top-level: `/frontend`, `/backend`
- Frontend:
- `src/pages` (student, teacher views)
- `src/lib/api` (REST client hooks)
- `src/context`, `src/store` (auth state)
- `components` (UI atoms, molecules)
- `routes` (React Router)
- Backend:
- `src/modules` (feature modules: auth, genai, livequizzes, users)
- `src/shared` (common middleware, database interfaces/providers for MongoDB, OpenAPI spec generator)
- `config`, `bootstrap`, `container` (framework wiring, Inversify DI)
- `firebase.json` / `.firebaserc` (Firebase Functions config)

##### README Insights
- Real-time polls, feedback sessions, quick assessments.
- Key use cases: teacher creates poll rooms; students join via code; real-time question distribution; live response aggregation; GenAI content generation for adaptive questions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client (Browser)"
        direction TB
        SPA["React SPA"]:::frontend
        StudentPages["Student Views"]:::frontend
        TeacherPages["Teacher Views"]:::frontend
        RESTHooks["REST Client Hooks"]:::frontend
        AuthContext["Auth Context"]:::frontend
        AuthStore["Auth Store"]:::frontend
        Routing["Routing (React Router)"]:::frontend
        SPA --> StudentPages
        SPA --> TeacherPages
        SPA --> RESTHooks
        SPA --> AuthContext
        SPA --> AuthStore
        SPA --> Routing
    end

    %% API Layer Entry
    API["API Layer\n(Index.ts)"]:::backend

    %% Middleware Chain
    subgraph "Middleware Chain" 
        direction TB
        CORS["CORS"]:::middleware
        AuthChecker["Auth Checker"]:::middleware
        ErrorHandler["Error Handler"]:::middleware
        RateLimiter["Rate Limiter"]:::middleware
        Logger["Logging"]:::middleware
    end

    %% Dependency Injection
    DI["DI Container"]:::backend
    LoadModules["Module Loader"]:::backend

    %% Backend Modules
    subgraph "Cloud Functions"   
        direction TB
        API --> CORS
        CORS --> AuthChecker
        AuthChecker --> ErrorHandler
        ErrorHandler --> RateLimiter
        RateLimiter --> Logger
        Logger --> AuthModule
        Logger --> PollModule
        Logger --> GenAIModule
        Logger --> UserModule

        subgraph "Auth Module" 
            direction TB
            AuthController["AuthController"]:::backend
            FirebaseAuthService["FirebaseAuthService"]:::backend
            AuthValidator["Auth Validators"]:::backend
            AuthController --> FirebaseAuthService
            FirebaseAuthService --> AuthValidator
            FirebaseAuthService --> FirebaseAuth[("Firebase Auth")]:::external
        end

        subgraph "LiveQuizzes Module" 
            direction TB
            PollRoomController["PollRoomController"]:::backend
            PollService["PollService"]:::backend
            RoomService["RoomService"]:::backend
            PollSocket["PollSocket (WebSocket)"]:::backend
            PollValidators["Poll Validators"]:::backend
            PollRoomController --> PollService
            PollRoomController --> RoomService
            PollService --> PollSocket
            PollService --> PollValidators
            PollService --> MongoDB
        end

        subgraph "GenAI Module" 
            direction TB
            GenAIVideoController["GenAIVideoController"]:::backend
            AIContentService["AIContentService"]:::backend
            AudioService["AudioService"]:::backend
            VideoService["VideoService"]:::backend
            TranscriptionService["TranscriptionService"]:::backend
            CleanupService["CleanupService"]:::backend
            GenAISchemas["GenAI Schemas"]:::backend
            GenAIVideoController --> AIContentService
            AIContentService --> OpenAI[("OpenAI API")]:::external
            AIContentService --> AudioService
            AIContentService --> VideoService
            AIContentService --> TranscriptionService
            AIContentService --> CleanupService
            AIContentService --> GenAISchemas
        end

        subgraph "User Module" 
            direction TB
            UserController["UserController"]:::backend
            UserService["UserService"]:::backend
            UserValidators["User Validators"]:::backend
            UserController --> UserService
            UserService --> UserValidators
            UserService --> MongoDB
        end

        DI --> AuthModule
        DI --> PollModule
        DI --> GenAIModule
        DI --> UserModule
        LoadModules --> DI
    end

    %% Persistence & Shared
    MongoDB[("MongoDB Atlas")]:::database
    subgraph "Database Provider"
        direction TB
        MongoProvider["MongoDatabase Provider"]:::backend
        UserRepo["UserRepository"]:::backend
        MongoInterfaces["DB Interfaces"]:::backend
        MongoProvider --> UserRepo
        MongoProvider --> MongoInterfaces
        UserRepo --> MongoDB
    end

    %% Shared Utilities
    OpenAPI["OpenAPI Spec Generator"]:::backend
    OpenAPI --> LoadModules

    Sentry[("Sentry")]:::external
    SMTP[("SMTP Service")]:::external

    %% Connections
    RESTHooks --> API
    Routing --> API
    AuthContext --> API
    AuthStore --> API
    API --> MongoProvider
    API --> OpenAPI
    API --> Sentry
    API --> SMTP

    %% Legend
    classDef frontend fill:#D6E5FF,stroke:#333,stroke-width:1px
    classDef backend fill:#E2FFE2,stroke:#333,stroke-width:1px
    classDef external fill:#FFF5BA,stroke:#333,stroke-width:1px
    classDef database fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef middleware fill:#F0F0F0,stroke:#333,stroke-width:1px

    %% Click Events
    click SPA "https://github.com/continuousactivelearning/poll-question-gen/tree/main/frontend/"
    click StudentPages "https://github.com/continuousactivelearning/poll-question-gen/tree/main/frontend/src/pages/student/"
    click TeacherPages "https://github.com/continuousactivelearning/poll-question-gen/tree/main/frontend/src/pages/teacher/"
    click RESTHooks "https://github.com/continuousactivelearning/poll-question-gen/tree/main/frontend/src/lib/api/"
    click AuthContext "https://github.com/continuousactivelearning/poll-question-gen/blob/main/frontend/src/context/auth.tsx"
    click AuthStore "https://github.com/continuousactivelearning/poll-question-gen/blob/main/frontend/src/lib/store/auth-store.ts"
    click Routing "https://github.com/continuousactivelearning/poll-question-gen/tree/main/frontend/src/routes/"
    click API "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/index.ts"
    click DI "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/container.ts"
    click LoadModules "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/bootstrap/loadModules.ts"
    click AuthController "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/auth/controllers/AuthController.ts"
    click FirebaseAuthService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/auth/services/FirebaseAuthService.ts"
    click AuthValidator "https://github.com/continuousactivelearning/poll-question-gen/tree/main/backend/src/modules/auth/classes/"
    click PollRoomController "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/livequizzes/controllers/PollRoomController.ts"
    click PollService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/livequizzes/services/PollService.ts"
    click RoomService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/livequizzes/services/RoomService.ts"
    click PollSocket "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/livequizzes/utils/PollSocket.ts"
    click PollValidators "https://github.com/continuousactivelearning/poll-question-gen/tree/main/backend/src/modules/livequizzes/validators/"
    click GenAIVideoController "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/genai/GenAIVideoController.ts"
    click AIContentService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/genai/services/AIContentService.ts"
    click AudioService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/genai/services/AudioService.ts"
    click VideoService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/genai/services/VideoService.ts"
    click TranscriptionService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/genai/services/TranscriptionService.ts"
    click CleanupService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/genai/services/CleanupService.ts"
    click GenAISchemas "https://github.com/continuousactivelearning/poll-question-gen/tree/main/backend/src/modules/genai/schemas/"
    click UserController "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/users/controllers/UserController.ts"
    click UserService "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/modules/users/services/UserService.ts"
    click UserValidators "https://github.com/continuousactivelearning/poll-question-gen/tree/main/backend/src/modules/users/classes/"
    click MongoProvider "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/shared/database/providers/mongo/MongoDatabase.ts"
    click UserRepo "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/shared/database/providers/mongo/repositories/UserRepository.ts"
    click MongoInterfaces "https://github.com/continuousactivelearning/poll-question-gen/tree/main/backend/src/shared/database/interfaces/"
    click OpenAPI "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/shared/functions/generateOpenApiSpec.ts"
    click Sentry "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/config/sentry.ts"
    click SMTP "https://github.com/continuousactivelearning/poll-question-gen/blob/main/backend/src/config/smtp.ts"
```
