ClassPulse System Architecture

Overview

ClassPulse is a real-time audience interaction platform that allows presenters to engage with their audience through interactive questions. The system follows a modular architecture with clear separation of concerns, built using the FastHTML framework.

System Components

1. Core Components

+-------------------+      +------------------+      +----------------+
|                   |      |                  |      |                |
|  Web Frontend     |<---->|  Backend Server  |<---->|  Database      |
|  (HTML/CSS/JS)    |      |  (FastHTML/Python)|     |  (SQLite)      |
|                   |      |                  |      |                |
+-------------------+      +------------------+      +----------------+
           ^                        ^
           |                        |
           v                        v
+-------------------+      +------------------+
|                   |      |                  |
|  WebSocket        |<---->|  Real-time       |
|  Communication    |      |  Events          |
|                   |      |                  |
+-------------------+      +------------------+

2. Architectural Patterns

ClassPulse employs several architectural patterns:

1. Model-View-Controller (MVC)
2. Models: Database schema and data access layer
3. Views: HTML templates and FastHTML components

4. Controllers: Route handlers that process requests

5. Service-Oriented Architecture

6. Modular utilities that provide specific services

7. Clear interfaces between components

8. Real-time Event Processing

9. WebSocket connections for live updates
10. Event-driven architecture for question responses

Data Flow

  +----------------+        +-----------------+       +------------------+
  |                |        |                 |       |                  |
  | Audience Member|------->| Join Session    |------>| View Questions   |
  |                |        |                 |       |                  |
  +----------------+        +-----------------+       +------------------+
                                                             |
                                                             v
  +----------------+        +-----------------+       +------------------+
  |                |        |                 |       |                  |
  | Presenter      |<-------| Real-time       |<------| Submit Responses |
  |                |        | Results Update  |       |                  |
  +----------------+        +-----------------+       +------------------+
        |
        v
  +----------------+
  |                |
  | Export Results |
  |                |
  +----------------+

Module Breakdown

Frontend Layer

1. Static Assets
2. CSS: Custom styling and layouts
3. JavaScript: Client-side interactivity and chart rendering

4. Images: Icons and visual elements

5. Templates

6. Presenter views: Dashboard, session management, results
7. Audience views: Join page, question answering interfaces

Backend Layer

1. Controllers
2. auth_routes.py: Authentication and user management
3. audience_routes.py: Audience-facing interfaces
4. presenter_routes.py: Presenter dashboard and management
5. question_routes.py: Question creation and result display

6. websocket_routes.py: Real-time communication

7. Utils

8. auth.py: Authentication helpers and security
9. components.py: Reusable UI components
10. qrcode.py: QR code generation for easy session joining

11. session_manager.py: Session and question management logic

12. Models

13. schema.py: Database tables, relationships, and data models

Database Schema

+----------------+       +----------------+       +----------------+
| Users          |       | Sessions       |       | Questions      |
+----------------+       +----------------+       +----------------+
| id             |<----->| id             |<----->| id             |
| username       |       | code           |       | session_id     |
| password_hash  |       | name           |       | type           |
| email          |       | created_at     |       | title          |
| display_name   |       | user_id        |       | options        |
+----------------+       | active         |       | active         |
                         +----------------+       | created_at     |
                                                  | order          |
                                                  +----------------+
                                                          |
                                                          v
                                                  +----------------+
                                                  | Responses      |
                                                  +----------------+
                                                  | id             |
                                                  | question_id    |
                                                  | session_id     |
                                                  | response_value |
                                                  | respondent_id  |
                                                  | created_at     |
                                                  +----------------+

Technology Stack

1. Backend
2. Python 3.x
3. FastHTML framework (Based on Starlette)
4. Uvicorn ASGI server

5. FastLite (SQLite ORM)

6. Frontend

7. HTML/CSS
8. Vanilla JavaScript
9. Chart.js for data visualization

10. jQCloud for word cloud rendering

11. Data Storage

12. SQLite database

13. Real-time Communication

14. WebSockets for live updates

Security Considerations

1. Authentication
2. Password hashing with salt using PBKDF2

3. Session-based authentication

4. Data Protection

5. Anonymous audience responses
6. Session ownership verification

7. Input validation and sanitization

8. Access Control

9. Route protection via middleware
10. Session-based authorization

Scalability Considerations

The current architecture can handle small to medium-sized classrooms or presentation scenarios. For larger deployments, consider:

1. Database Scaling
2. Migrate from SQLite to PostgreSQL or MySQL

3. Implement connection pooling

4. Performance Optimization

5. Implement caching for frequent queries

6. Optimize WebSocket connections for high concurrency

7. Deployment Options

8. Containerize with Docker
9. Deploy with Gunicorn workers behind Nginx