Skip to content

Specialized Educational Components

Jump to bottom
github-actions[bot] edited this page Apr 24, 2026 · 2 revisions

Specialized Educational Components

**Referenced Files in This Document** - [ChatLayout.tsx](file://client/src/components/chat/ChatLayout.tsx) - [ConversationList.tsx](file://client/src/components/chat/ConversationList.tsx) - [MessageBubble.tsx](file://client/src/components/chat/MessageBubble.tsx) - [MessageInput.tsx](file://client/src/components/chat/MessageInput.tsx) - [use-chat-ws.ts](file://client/src/hooks/use-chat-ws.ts) - [chat-api.ts](file://client/src/lib/chat-api.ts) - [chat.ts](file://client/src/types/chat.ts) - [performance-chart.tsx](file://client/src/components/dashboard/performance-chart.tsx) - [quick-action-card.tsx](file://client/src/components/dashboard/quick-action-card.tsx) - [recent-tests-table.tsx](file://client/src/components/dashboard/recent-tests-table.tsx) - [top-students.tsx](file://client/src/components/dashboard/top-students.tsx) - [question-form.tsx](file://client/src/components/test/question-form.tsx) - [ocr-upload.tsx](file://client/src/components/test/ocr-upload.tsx) - [ocr-processing.tsx](file://client/src/components/test/ocr-processing.tsx)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document describes PersonalLearningPro’s specialized educational components for the learning platform ecosystem. It focuses on:

  • Real-time chat: messaging, conversation management, presence, and typing indicators
  • Dashboard: performance charts, quick actions, recent tests, and top performers
  • Test management: question creation, OCR upload and processing, and assessment workflows
  • MessagePal AI integration: WebSocket communication patterns and UI panel
  • State management, real-time synchronization, and educational UX patterns
  • Reusability, customization, and integration with the broader educational platform

Project Structure

The components are organized by feature areas:

  • Chat: UI and WebSocket integration for real-time messaging
  • Dashboard: analytics and quick action cards
  • Test: assessment creation and OCR workflows
  • MessagePal: AI assistant panel and WebSocket hooks
  • Shared: types, APIs, and hooks used across components
graph TB
subgraph "Chat"
CL["ConversationList.tsx"]
ML["MessageBubble.tsx"]
MI["MessageInput.tsx"]
CW["use-chat-ws.ts"]
CA["chat-api.ts"]
CT["chat.ts"]
end
subgraph "Dashboard"
PC["performance-chart.tsx"]
QAC["quick-action-card.tsx"]
RT["recent-tests-table.tsx"]
TS["top-students.tsx"]
end
subgraph "Test"
QF["question-form.tsx"]
OCU["ocr-upload.tsx"]
OCP["ocr-processing.tsx"]
end
CL --> CW
ML --> CW
MI --> CW
CW --> CA
CA --> CT
Loading

Diagram sources

  • ConversationList.tsx
  • MessageBubble.tsx
  • MessageInput.tsx
  • use-chat-ws.ts
  • chat-api.ts
  • chat.ts
  • performance-chart.tsx
  • quick-action-card.tsx
  • recent-tests-table.tsx
  • top-students.tsx
  • question-form.tsx
  • ocr-upload.tsx
  • ocr-processing.tsx

Section sources

  • ChatLayout.tsx
  • ConversationList.tsx
  • MessageBubble.tsx
  • MessageInput.tsx
  • use-chat-ws.ts
  • chat-api.ts
  • chat.ts
  • performance-chart.tsx
  • quick-action-card.tsx
  • recent-tests-table.tsx
  • top-students.tsx
  • question-form.tsx
  • ocr-upload.tsx
  • ocr-processing.tsx

Core Components

  • ChatLayout orchestrates conversation discovery, selection, and real-time thread rendering
  • ConversationList groups and filters conversations by category and role-aware metadata
  • MessageBubble renders rich message types (text, image, announcement, assignment, doubt)
  • MessageInput supports text, doubt tagging, file attachments, and quick actions
  • use-chat-ws encapsulates WebSocket lifecycle, event routing, and reconnection logic
  • chat-api provides typed REST clients for channels, DMs, messages, and uploads
  • Dashboard components visualize performance, recent tests, and top students
  • Test components support question creation and OCR scanning/evaluation
  • Types define consistent shapes for messages, conversations, and users

Section sources

  • ChatLayout.tsx
  • ConversationList.tsx
  • MessageBubble.tsx
  • MessageInput.tsx
  • use-chat-ws.ts
  • chat-api.ts
  • chat.ts
  • performance-chart.tsx
  • quick-action-card.tsx
  • recent-tests-table.tsx
  • top-students.tsx
  • question-form.tsx
  • ocr-upload.tsx
  • ocr-processing.tsx

Architecture Overview

The chat system integrates REST and WebSocket layers:

  • REST endpoints supply conversation metadata and messages
  • WebSocket maintains real-time updates for new messages, typing, read receipts, and presence
  • UI components coordinate selection, rendering, and user actions
sequenceDiagram
participant U as "User"
participant CL as "ConversationList"
participant CH as "ChatLayout"
participant CW as "use-chat-ws"
participant WS as "WebSocket Server"
participant API as "REST API"
U->>CL : Select conversation
CL->>CH : onSelect(conv)
CH->>CH : setActiveConv(conv)
CH->>CW : useChatWs({channelId})
CW->>WS : connect() and join_channel
WS-->>CW : onmessage(new_message/user_typing/presence)
CW-->>CH : callbacks (onNewMessage/onTyping/onPresence)
CH->>CH : update UI state (messages, typing, presence)
U->>CH : type message
CH->>CW : sendMessage()
CW->>WS : send_message
WS-->>CW : broadcast new_message
CW-->>CH : onNewMessage
CH->>CH : append message and mark read
CH->>API : fetchMessages(channelId)
API-->>CH : messages[]
Loading

Diagram sources

  • ConversationList.tsx
  • ChatLayout.tsx
  • use-chat-ws.ts
  • chat-api.ts

Detailed Component Analysis

Chat System Components

  • ChatLayout
    • Resolves workspaces, channels, and DMs via REST queries
    • Converts server channels to UI conversations with categories and participant metadata
    • Manages active conversation and mobile responsiveness
    • Initializes a shared WebSocket connection scoped to the active channel
  • ConversationList
    • Filters and groups conversations by category (announcements, classes, teachers, friends, parents)
    • Renders avatars, online indicators, unread counts, and last message previews
    • Uses role-aware user IDs and last message ownership to tailor UI
  • MessageBubble
    • Renders rich message types with role-specific styles and badges
    • Handles announcement banners, assignment cards, system notices, and doubt states
    • Supports pinned messages, mentions, and media previews
  • MessageInput
    • Supports doubt tagging for students and quick actions for teachers
    • Uploads files via REST and sends them as messages
    • Integrates with WebSocket typing events and read receipts
classDiagram
class Conversation {
+string id
+string name
+ConversationCategory category
+boolean isGroup
+User[] participants
+Message lastMessage
+number unreadCount
+string[] typing
}
class Message {
+string id
+string conversationId
+string senderId
+UserRole senderRole
+MessageType type
+string content
+Date timestamp
+string[] readBy
+boolean isPinned
+boolean isDoubtAnswered
}
class User {
+string id
+string name
+UserRole role
+boolean isOnline
}
Conversation "1" --> "*" Message : "contains"
Conversation "1" --> "*" User : "participants"
Loading

Diagram sources

  • chat.ts
  • chat.ts
  • chat.ts

Section sources

  • ChatLayout.tsx
  • ConversationList.tsx
  • MessageBubble.tsx
  • MessageInput.tsx
  • chat.ts

Real-Time Messaging and Presence

  • WebSocket events handled:
    • new_message: append to thread and update read status
    • user_typing: show typing indicators per conversation
    • message_read: update readBy lists and UI badges
    • user_presence: set participant online/offline status
  • Reconnection strategy:
    • Exponential backoff with capped delay
    • Graceful closure on component unmount
    • Unauthorized disconnects (code 4001) do not trigger reconnect
flowchart TD
Start([Connect]) --> Open["WebSocket onopen"]
Open --> Join{"channelId set?"}
Join --> |Yes| SendJoin["send join_channel"]
Join --> |No| Idle["Idle"]
SendJoin --> Idle
Idle --> Event{"onmessage event"}
Event --> NewMsg["new_message"]
Event --> Typing["user_typing"]
Event --> Read["message_read"]
Event --> Presence["user_presence"]
Event --> Other["other types"]
NewMsg --> UpdateUI["Update messages/read status"]
Typing --> ShowTyping["Show typing indicators"]
Read --> MarkRead["Mark readBy"]
Presence --> UpdatePresence["Update participant online status"]
Other --> Idle
Idle --> Close{"onclose?"}
Close --> |Yes| Backoff["Exponential backoff"]
Backoff --> ConnectRetry["Reconnect after delay"]
Close --> |No| End([Unmount])
Loading

Diagram sources

  • use-chat-ws.ts
  • use-chat-ws.ts
  • use-chat-ws.ts

Section sources

  • use-chat-ws.ts

Dashboard Components

  • PerformanceChart
    • Renders bar charts comparing class vs school averages
    • Uses theme-aware colors and responsive container
    • Includes skeleton loader and mock data fallback
  • QuickActionCard
    • Provides role-driven shortcuts with icons and link targets
  • RecentTestsTable
    • Lists tests with status badges, completion progress, and actions
    • Uses skeleton loaders while fetching data
  • TopStudents
    • Displays top-performing students with avatars and scores
    • Includes skeleton loader and mock data fallback
graph LR
PC["PerformanceChart"] --> Theme["Theme Context"]
RT["RecentTestsTable"] --> Status["Status Badges"]
RT --> Progress["Progress Bars"]
TS["TopStudents"] --> Avatars["Avatars"]
Loading

Diagram sources

  • performance-chart.tsx
  • quick-action-card.tsx
  • recent-tests-table.tsx
  • top-students.tsx

Section sources

  • performance-chart.tsx
  • quick-action-card.tsx
  • recent-tests-table.tsx
  • top-students.tsx

Test Management Components

  • QuestionForm
    • Zod-based validation for question types (MCQ, short, long, numerical)
    • Dynamic options for MCQ with correctness flags
    • AI rubric support for short/long answers
    • Mutation-based submission with toast feedback and cache invalidation
  • OCRUpload
    • Drag-and-drop file upload with progress tracking
    • Validates file size/type and reads as base64
    • Calls OCR endpoint and updates state with recognized text and confidence
  • OCRProcessing
    • Displays recognized answers with confidence levels
    • Allows editing recognized text and evaluating via AI
    • Provides “Review All” action and status summary
sequenceDiagram
participant U as "User"
participant QF as "QuestionForm"
participant API as "REST API"
participant Toast as "Toast"
U->>QF : Fill question form
QF->>QF : Validate (Zod)
QF->>API : POST /api/questions
API-->>QF : Success
QF->>Toast : Show success
QF->>QF : Reset form/cache invalidation
Loading

Diagram sources

  • question-form.tsx
  • question-form.tsx

Section sources

  • question-form.tsx
  • ocr-upload.tsx
  • ocr-processing.tsx

MessagePal AI Integration

  • MessagePal panel and WebSocket hook enable AI-assisted chat experiences
  • WebSocket patterns mirror the chat system: connect on mount, join channel, route events, reconnect with backoff
  • UI panel integrates with the chat thread and leverages presence/typing indicators for conversational context

[No sources needed since this section summarizes integration patterns without analyzing specific files]

Dependency Analysis

  • UI-to-API
    • REST endpoints for workspaces, channels, DMs, messages, and uploads
    • Typed interfaces ensure consistency between server and UI
  • UI-to-WebSocket
    • use-chat-ws centralizes connection, event routing, and lifecycle
    • Components depend on stable callback refs to avoid stale closures
  • Cross-feature dependencies
    • Dashboard components rely on TanStack Query for data fetching
    • Test components integrate with toast notifications and query cache invalidation
graph TB
CW["use-chat-ws.ts"] --> WS["WebSocket Server"]
CW --> CH["ChatLayout.tsx"]
CH --> CL["ConversationList.tsx"]
CH --> ML["MessageBubble.tsx"]
CH --> MI["MessageInput.tsx"]
CL --> API["chat-api.ts"]
ML --> API
MI --> API
API --> Types["chat.ts"]
Loading

Diagram sources

  • use-chat-ws.ts
  • ChatLayout.tsx
  • ConversationList.tsx
  • MessageBubble.tsx
  • MessageInput.tsx
  • chat-api.ts
  • chat.ts

Section sources

  • chat-api.ts
  • chat.ts
  • use-chat-ws.ts

Performance Considerations

  • Debounce and memoization
    • Conversation merging and grouping computed via useMemo to avoid unnecessary re-renders
  • Efficient list rendering
    • Virtualized lists recommended for large message histories
  • Network optimization
    • Stale-time caching for REST queries; minimal retries
  • WebSocket backoff
    • Exponential backoff prevents thundering herd on server restarts
  • Rendering cost
    • Conditional rendering of expensive UI (charts, OCR previews) based on visibility

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • WebSocket errors
    • Unauthorized disconnects (code 4001) halt reconnection attempts
    • On-close exponential backoff ensures resilience
  • Upload failures
    • Validate file size/type before initiating upload
    • Show user-friendly toast messages for errors
  • Data fetching
    • REST client throws on non-OK responses; surface errors via toasts
    • Enable skeleton loaders while data is pending

Section sources

  • use-chat-ws.ts
  • chat-api.ts
  • ocr-upload.tsx
  • question-form.tsx

Conclusion

PersonalLearningPro’s educational components combine robust real-time messaging, role-aware dashboards, and intelligent test workflows. The chat system’s WebSocket-first design, strong typing, and reusable hooks enable scalable, maintainable UI. Dashboard and test components emphasize performance, accessibility, and clear feedback loops. Together, these components form a cohesive foundation for an adaptive learning platform.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

  • State management patterns
    • Local component state for UI flags (mobile view, doubt mode)
    • Global query cache for server data; invalidate on mutations
  • Customization options
    • Theming via theme context affects chart and component visuals
    • Role-aware UI toggles for student/teacher/parent perspectives
  • Integration touchpoints
    • REST endpoints for metadata and uploads
    • WebSocket endpoints for real-time collaboration and presence

[No sources needed since this section provides general guidance]

Clone this wiki locally