🖥️ Technical Architecture: Think & Speak Platform

1 / 15

Think & Speak

AI English Learning Platform — Technical Workshop for Educators

Next.js + React TypeScript Redux State Mgmt SCSS Modules

🏗️ Component Architecture

Modular pageComponents/ directory structure with CSS Modules preventing style leakage between Authentication, Assessment, Course Adventure, and Live Translation modules.

🎨 Visual Identity System

20 mascot variants as functional UI components communicating learning modes in real-time. Color-coded by cognitive domain: Green (Media), Blue (Analytical), Yellow (Creative), Orange (Communication).

🤖 AI-Powered Personalization

8-dimension learner profiling driving content adaptation. Assessment data flows into Vocabulary Builder, Conversation Role Play, Reading Comprehension, and Live Translation configuration.

Production URLs: app.thinkandspeak.com (Live) · uat-app.thinkandspeak.com (Testing) · Test Accounts: test_teacher@seechange-edu.com / Aa123456

🔧 CSS Modules & Component Architecture

2 / 15

Styling Foundation

The file path src/pageComponents/account/pages/login/index.module.scss reveals a CSS Module architecture that generates unique hashed class names, preventing style conflicts between the login interface and other modules.

Style Encapsulation Strategy ▼

CSS Modules generate unique hashed class names preventing conflicts between Dashboard, Course Adventure, Vocabulary Builder, and Live Translation modules
The .module.scss extension signals scoped styling isolated from global stylesheets
Component-scoped styles ensure authentication-specific styling (mascot positioning, age-selection buttons, responsive forms) remain encapsulated within the login context
Critical for educational software where interface clarity directly impacts learning outcomes

Component Colocation Pattern ▼

pageComponents/ directory structure in Next.js colocates styles with their respective components
Improves maintainability and enables distinct visual treatments for different user types (teachers vs students)
Multi-role authentication: separate credential paths (test_teacher@seechange-edu.com vs test_student1@seechange-edu.com)
Dynamic theme injection based on user type or preliminary assessment data stored in localStorage

Hybrid Styling: Tailwind + SCSS Modules ▼

@apply directives compose Tailwind utilities into semantic classes within SCSS modules
Global .mobile, .tablet selectors for breakpoint-based responsive adaptations
Design token system with $color-primary-900, $color-neutral-800 ensuring brand consistency
Shadow/elevation system: 0px 12px 24px 0px rgba(46, 42, 91, 0.1)

📁 File Structure Pattern

                                src/

                                  pageComponents/

                                    account/

                                      pages/

                                        login/

                                          index.tsx // Component

                                          index.module.scss // Scoped Styles

✅ Key Benefits

No CSS leakage between learning modules
Independent updates without whole-platform rebuilds
Optimized critical path via code-splitting
Consistent design system across multi-role interfaces

💡 Teacher Insight: This modular architecture means teachers see a professionally tailored interface while students see an engaging learning environment — same platform, different visual experiences.

🎭 Mascot Visual Identity System — 20 Functional Variants

3 / 15

The 20 mascot variants are functional UI components — not decoration. Each character communicates learning modes in real-time, reducing cognitive load through consistent visual cues. Research shows friendly visual characters increase student engagement by up to 40% in language learning contexts.

🟢 Green — Media & Active Learning

🎧

Image 1

Headphones + Microphone — Live Translation

🥽

Image 6

VR Goggles — Immersive Training

🎮

Image 10

Headphones + Coin — Gamification

🎒

Image 16

Backpack + Pencil — Student Onboarding

🔵 Blue — Analytical & Literacy

🔍

Image 2

Detective — Exam Simulation Mode

📖

Image 3

Book + A-Z — Vocabulary & Read & Speak

🤓

Image 13

Glasses — Teacher Dashboard

💪

Image 18

Crossed Arms — Confidence/Completion

🟡 Yellow — Creative & STEM

🧠

Image 5

Brain + Rocket — Higher-Order Thinking

🎨

Image 9

Paintbrush — Creative Expression

🎤

Image 15

Microphone + Star — Speaking Performance

🟠 Orange + 🟣 Purple — Global & Exploration

🌏

Image 8

Globe — Global Classroom (Live Translation)

🏛️

Image 10

Podium — Public Speaking & Debate

🔭

Image 12

Binoculars — Research & Discovery (Purple)

😨

Image 14

Shy Blue — Struggling Learner State

🎨 Age-Based Color Psychology System

4 / 15

The platform implements a calculated color-psychology gradient system mirroring cognitive development stages — cooler blues for concrete operational thinking, warmer oranges for abstract reasoning maturity.

6-8

Early Childhood

Warm, inviting tones — curiosity-driven learning foundations

#FFB347

9-11

Middle Childhood

Balanced hues — growing cognitive abilities

#4ECDC4

12-14

Early Adolescence

Calming tones — systematic learning approaches

#45B7D1

15-17

Mid Adolescence

Energetic colors — DSE preparation readiness

#FFA94D

18+

Adult Learning

Professional tones — career-focused learning

#FF8C42

Implementation via SCSS Variables ▼

$age-primary-6-8, $age-primary-9-11, $age-primary-12-14, $age-secondary-15-17, $age-adult-18
Colors cascade throughout the interface using data-age-group attribute selectors
The 12-14 age group maps to "concrete operational thinking" while 15+ maps to "abstract reasoning maturity"
A 7-year-old sees warm orange interfaces while a 17-year-old sees professional orange tones — same platform, different experience

Cross-Feature Color Continuity ▼

Automatic theming extends to Live Translation feature indicators — color coding helps students instantly identify their assigned learning cohort
Visual continuity maintained from authentication through Course Adventure progression
Cohort indicators use the same palette for heatmap indicators and engagement tracking visualizations
Same color system applied to Dashboard progress bars and Vocabulary Trainer mastery indicators

💡 Teacher Insight: When you see a student's interface, you can immediately identify their age bracket by the color scheme. A Year 1 student sees warm, inviting orange tones while a Form 4 student sees the same platform in professional blues — adaptive design that respects cognitive development.

📝 Assessment Module — 8-Dimension Learner Profiling

5 / 15

Immediately post-login, users encounter the personalized assessment interface. This is NOT a test — it's a preference profile that helps the platform understand how each student learns best.

👤

Age Groups

6-8, 9-11, 12-14, 15-17, 18+ — adapts content delivery and interface complexity

🎯

Proficiency Level

1-10 scale with detailed descriptors — determines content difficulty across all modules

💡

Interests

11 topic categories — Space & Science, Animals, Sports, Music, Technology, Books...

🧠

Learning Style

8 methods — Games, Stories, Speak & Act, Videos, Solo Study...

Learning Personas (9 Types) ▼

Debate Hero · Story Explorer · Game Master · Creative Writer · Active Speaker · Visual Learner · Deep Reader · Social Learner · Independent Thinker

Each persona maps to specific content delivery templates and mascot emotional states.

Motivation Factors (8 Categories) ▼

Travel & Explore · Watch Shows/Youtube · Career Goals · Academic Success · Social Connection · Entertainment · Self-Improvement · HKDSE Preparation

Motivation factors determine content relevance scoring and recommendation algorithms.

Curious Subjects (22 Academic Topics) ▼

Mathematics · Science · Biology · Chemistry · Physics · History · Geography · Economics · Business Studies · Literature · Music · Art · PE · Computer Science · General Studies · Religious Studies · Philosophy · Psychology · Sociology · Environmental Science · Astronomy · Law Basics

HKDSE-relevant subjects ensure English learning connects to academic success.

🔄 Personalization Pipeline

① Assessment captures learner profile

↓

② Profile data flows to Redux store

↓

③ Content difficulty auto-configures

↓

④ All modules receive personalization data

✅ Proficiency Level Scale: L1-3 Beginner → L4-6 Intermediate → L7-8 Advanced → L9-10 Expert

💬 Conversational UI & Speech Bubble Architecture

6 / 15

Speech Bubble Design System

White rounded-rectangle containers with directional tails pointing toward the mascot. Implements conversational UI patterns supporting dynamic welcome messages and contextual help.

Bubble Styling Specifications ▼

border-radius: 24px creates soft, friendly container shape
filter: drop-shadow() for floating dialogue effect
Directional tails implemented via CSS clip-path or ::after pseudo-element triangles
JavaScript dynamically repositions tails based on mascot location within viewport
React props enable real-time content updates during authentication flow

Multilingual Container Flexibility ▼

Generous padding and min-height specifications ensure CJK character sets render without visual breakage
Line-height values inflated to 1.6+ for CJK glyph vertical complexity
Interface language toggle (English ↔ Mandarin ↔ Cantonese) without page reloads
CSS transitions morph button shapes and flag indicators during language switching

Font Engineering for Trilingual Support

CJK Font Stack

                                font-family: system-ui, -apple-system,

                                  "Segoe UI", Roboto,

                                  "Noto Sans",

                                  "Noto Sans CJK SC",  // Simplified

                                  "Noto Sans CJK TC",  // Traditional

                                  sans-serif;

Language Detection Visual Feedback ▼

zh-CN activates Image 19 (Simplified Chinese mascot) styling
zh-HK / zh-TW activates Image 20 (Traditional Chinese mascot) styling
backdrop-filter: blur() effects keep login form legible during animations
Future RTL expansion supported via [dir="rtl"] qualifications

💡 Teacher Insight: The speech bubbles adapt automatically when switching between English and Chinese modes — the platform's multilingual capabilities extend to every touchpoint, including authentication.

📱 Responsive Design & Device Optimization

7 / 15

Hong Kong students frequently access content on smartphones during MTR commutes — mobile optimization ensures vocabulary practice integrates naturally into daily routines.

🖥️

Desktop

≥1024px

Full 1920px layouts with multi-column grids
40px+ mascot characters for classroom projection
Sidebar + main content architecture
Complete analytics visualization

📱

Tablet

769–1024px

Two-column adaptive grid
Balanced density, gesture support
Expanded charts and analytics
Touch-optimized interactive elements

📲

Mobile

≤480px

Single-column scroll layout
Compact metrics cards
Swipe navigation for activities
Touch targets 44px+ minimum

Dynamic Asset Delivery ▼

useBreakpoints hook for conditional rendering (imgBubble desktop vs imgBubbleMobile mobile)
Contextual layout transformation beyond simple image resizing
Mobile-first approach using :global(.mobile) & nesting patterns
Desktop horizontal flex layout switches to stacked vertical on narrow viewports

Touch Interface Optimization ▼

Haptic feedback simulation through CSS: transform: translateY(2px) + box-shadow reduction on :active
WCAG 2.1 compliant touch targets: minimum 44px tap areas (56px for ruggedized school tablets)
onContextMenu handlers prevent accidental triggers during long-press recording cancel
Landscape orientation handling: padding adjustments prevent form field obstruction

💡 Mobile Experience: Students can start a lesson on school computers, continue on tablets at home, and review on phones during commute. Progress syncs in real-time. The mobile experience is NOT a degraded version — it's fully functional for on-the-go learning.

🔄 Progressive Onboarding & Emotional Intelligence

8 / 15

Progressive Onboarding Architecture

The combination of age badges and emotional mascot states creates a progressive onboarding system where localStorage or secure cookies remember user preferences for seamless daily access.

Returning vs New User Optimization ▼

.returning-user modifier: faster transitions (600ms → 300ms) for students who completed Assessment
.new-user classes: elaborate mascot introduction animations for first-time users
Preference observation: hover time on age badges, mascot preference clicks pre-configure content difficulty
localStorage/sessionStorage persistence enables cross-device learning continuity

Mascot State Machine Integration ▼

CSS-driven state management: .mascot-state--frustrated, .mascot-state--tired, .mascot-state--celebratory
Dynamic switching based on login attempt patterns or time-of-day detection
Worried mascot appears after failed authentication attempts (anxiety reduction)
Sleepy mascot triggers during late-hour sessions (wellness management)

Emotional Intelligence Feedback

😟

Worried

After failed auth — empathetic support

😴

Sleepy

Late-hour — break reminders

🎉

Celebratory

Achievement — positive reinforcement

😲

Surprised

Error states — alerting feedback

🧠 Krashen's Affective Filter Theory: Anxiety blocks language acquisition. The mascot system addresses this — students who make mistakes see a SAD but ENCOURAGING mascot, not a harsh error message. Non-judgmental retry prompts maintained across all tiers.

🔄 Onboarding Flow Sequence

Auth

→

Age Select

→

Assess

→

Dashboard

⚡ Performance Optimization & Security Architecture

9 / 15

Performance Optimization

Content Visibility API

content-visibility: auto defers mascot animations for rapid load on limited bandwidth

CSS Containment

contain: layout style paint isolates form from CJK font loading reflows

Asset Pipeline

image-set() with WebP/AVIF + PNG fallbacks for mascot delivery

GPU Acceleration

will-change: transform for 60fps mascot animations on school devices

Bandwidth Adaptation Strategies ▼

Image lazy-loading and animation deferral until critical content renders
Contour isolation ensures CJK font loading doesn't cause input lag
School-issued devices with limited GPU: will-change compositor hints
Rural area bandwidth: progressive asset loading prioritizes text over images

Security & Compliance

🔒 Data Security Architecture

Iframe sandboxing isolates assessment data from main application
Base64 token encoding (btoa()) for iframe authentication
postMessage validation prevents malicious injection
FERPA-compliant data boundaries

👤 Role-Based Access Control

Teacher accounts: Live Learning Feedback & Heatmap
Student accounts: personalized learning content only
Credential separation prevents inappropriate feature access
JWT token-based authentication for API security

🌐 Environment Separation

Production (app.thinkandspeak.com) — real student data
UAT (uat-app.thinkandspeak.com) — teacher training sandbox
Desaturated color scheme in UAT prevents accidental data modification

♿ Accessibility & Inclusive Design Compliance

10 / 15

Visual & Motor Accessibility

High Contrast & Focus Support ▼

Focus-visible styling for speech bubbles and form elements — WCAG 2.1 AA compliance
.focusVisible polyfill ensures tab navigation through age-selection badges (6-8, 9-11, etc.)
outline properties provide clear focus indicators for motor control considerations
48px+ touch targets for primary school users accessing Vocabulary Trainer modules
56px minimum for ruggedized school tablets

Reduced Motion Support ▼

@media (prefers-reduced-motion) queries respect user preferences
Mascot communicates through static pose variations (worried, excited, neutral) replacing animations
No motion-dependent content — all information accessible without animation

Cognitive & Wellness Accessibility

Cognitive Load Management ▼

.interactionZone wrappers with :focus-within logging hesitation data for learning analysis
Clear visual feedback through color transitions (not relying solely on color)
Sleepy mascot triggers during late-hour sessions — proactive wellness management
Client-side time API detection suggests break reminders before Dashboard access

✅ Accessibility Features Summary

Feature	Status
WCAG 2.1 AA Compliance	✅ Active
Keyboard Navigation	✅ All Controls
Screen Reader (ARIA)	✅ aria-labels
High Contrast Mode	✅ Toggle Support
Reduced Motion	✅ Media Query
Touch Targets 44px+	✅ Verified

💡 Teacher Insight: These accessibility features directly support the platform's promise to serve every learner regardless of ability level, ensuring all students can benefit from personalized English language instruction. Some students may have special educational needs — the platform accommodates these without requiring separate systems.

🧪 Assessment Module: Technical Data Capture & Integration

11 / 15

Immediately post-authentication, users encounter the personalized assessment interface. This is not a separate system — it is seamlessly integrated into the login flow, making profiling feel like part of the welcome experience.

1

Age Selection

6-8 through 18+ badges with visual color feedback

2

Proficiency

Brief adaptive assessment from beginner to advanced

3

Interests

Topics for personalized content curation

4

Style Detection

System observes interaction patterns

5

Dashboard Gen

All data feeds personalized configuration

Data Privacy ▼

Assessment data used solely for content personalization
Secure authentication protects student profiles
K12 compliance for Hong Kong educational context
GDPR-aligned design with optional PII fields

Adaptive Difficulty ▼

Vocabulary Builder difficulty curves auto-adjust based on assessment
Conversation Role Play scenario complexity adapts to proficiency
Reading Comprehension mode (Guided vs Exam) determined by level
Live Translation language support configured by profile data

Progress Reassessment ▼

System prompts reassessment after significant usage periods
Updates personalization parameters based on demonstrated growth
Continuous adaptation ensures content stays appropriately challenging
Students never outgrow or undergrow the platform

📚 Reading Comprehension Architecture & HKDSE Preparation

12 / 15

9 Question Type Taxonomy

TrueOrFalse

TextInput

MCQ

WordBuilder

DragTheWords

FillInBlanks

DragAndDrop

TableCompletion

ReferentMatch

🎯 AI Evaluation: TextInput questions use callPromptToAi for semantic analysis beyond exact matching — evaluating conceptual correctness, not just keyword presence.

Dual-Mode Practice System

Feature	Exam Mode	Guide Mode
Timer	90-min countdown	Hidden
Hints	Disabled	AI Coach enabled
Scoring	Immediate on submit	Real-time feedback
Color Theme	Orange accent	Green accent
Use Case	HKDSE simulation	Learning & practice

Adaptive Difficulty & Gamification ▼

Clearance levels system: Level 1 (0 pts) through Level 10 (10,000+ pts)
AnswerStatus enum: NotStarted → InProgress → Completed
Session resume based on activePaperSessionId persistence
HKDSE multi-article format: Part A (compulsory) + Part B (B1/B2 choice)

🌍 Live Translation Engine & Multilingual Architecture

13 / 15

Trilingual Support

🇬🇧

English

en-US primary source

🇭🇰

Cantonese

yue-HK traditional

🇨🇳

Mandarin

zh-CN simplified

Real-Time Processing Pipeline ▼

WebSocket/RTC Multi-Channel Architecture: Chat Channel (translations) separate from Room Channel (presence updates)
Message Thread: translationText: Record<string, string> supporting simultaneous multi-language rendering
Translation Caching: pre-computed translations reduce client-side latency
History Persistence: StorageKey.historyMessages enables session transcript storage

Classroom Management

👥 Attendance Monitoring

attendingStudentIds and invitedStudentIds for real-time presence
Three states: Attending (WebSocket connected), Invited (authorized), Available (eligible)
Avatar stack with "+N members" overflow indicator

📊 Engagement Feedback

"Question" or "Understand" signal detection for comprehension monitoring
Real-time heatmap: Green (active) → Yellow (intermittent) → Red (confused)
Room Status: NOT_STARTED → STARTED → IN_PROGRESS → COMPLETED

Listen

→

Capture

→

Review

→

Master

Every class becomes a structured, reusable learning asset.

📊 Teacher Dashboard, Vocabulary System & Course Adventure

14 / 15

📊 Teacher Dashboard

Live Learning Feedback & Heatmap — real-time engagement visualization
Student Status Indicators — AI Coach detecting hesitation
Progress Tracking — historical graphs over time
Broadcast Tools — simultaneous content delivery to class
Group Discussion Configuration — Live Translation session setup
Session Recording & Review — playback for parent conferences

📝 Vocabulary System

Spaced repetition based on Ebbinghaus forgetting curve
Words Mastered = retention across 4+ review cycles
3x better retention vs mass exposure (research-validated)
5-Skill Radar: Vocab Guide, Spelling L1/L2, Usage, Dictation
Auto flashcard generation from capture during lessons
10 progression levels: First Words → Extreme Words

🗺️ Course Adventure

5-task lesson structure: Video → Quiz → Glossary → Download → Speaking
Milestone-based progression with achievement moments
Skills tracked: Listening, Speaking, Reading, Vocabulary
Mascot-guided learning journey maintaining engagement
Adaptive content based on assessment profile
Progressive difficulty aligned with DSE preparation

Dashboard Technical Architecture ▼

useCallGetUserDashboard — custom API hook for real-time data fetching
Redux Store synchronization for state consistency across components
useModuleGuardian — access control for proper module sequencing
Responsive sidebar/main content adapting to device types

Multi-Tab Reporting System ▼

Courses Report: enrollment, completion, skill development
Scripts Report: speaking practice monitoring, role-play performance
VocabBank Report: vocabulary with 5-skill radar charts
Time range filtering: 7d, 30d, 90d, all-time presets
4-Dimension Assessment: Fluency, Accuracy, Completeness, Intonation

💡 Teacher Insight: Students see real-time progress — immediate feedback loop. Teachers see aggregate class data for identifying students who need support. The gamification elements (points, streaks, mastered words) create dopamine feedback loops that encourage continued practice.

🏆 The Closed-Loop Learning Ecosystem

15 / 15

Everything Connects

Assessment → Personalization → Activity → Analytics → Improvement — This closed loop creates continuous, self-reinforcing learning growth.

🔵 For Teachers

Reduced preparation time via automated vocabulary extraction
Real-time engagement monitoring with heatmap visualization
Multilingual classroom support (EN ↔ CN ↔ HK)
Structured lesson reuse from every class session
Aggregate analytics for identifying struggling students

🏫 For Schools

Scalable solution supporting multiple schools and classes
Comprehensive reporting on learning outcomes
GDPR/COPPA compliance for educational data
JWT-based security with role-based access control

🟢 For Students

Personalized learning paths adapting to proficiency
Reduced anxiety through mascot-driven emotional support
Interactive practice with immediate AI feedback
Clear progress tracking across all modules
Mobile-first design for learning anywhere

⚙️ Core Technologies

React + Next.js TypeScript Redux SCSS Modules WebRTC Azure Speech WebSocket

"Teach with Confidence. Learn without Limits."

Think & Speak — See Change AI English

📧 Contact us: support@seechange-edu.com · 🌐 app.thinkandspeak.com

🖥️ Technical Architecture: Think & Speak Platform

Think & Speak

🏗️ Component Architecture

🎨 Visual Identity System

🤖 AI-Powered Personalization

🔧 CSS Modules & Component Architecture

Styling Foundation

📁 File Structure Pattern

✅ Key Benefits

🎭 Mascot Visual Identity System — 20 Functional Variants

🟢 Green — Media & Active Learning

🔵 Blue — Analytical & Literacy

🟡 Yellow — Creative & STEM

🟠 Orange + 🟣 Purple — Global & Exploration

🎨 Age-Based Color Psychology System

📝 Assessment Module — 8-Dimension Learner Profiling

Age Groups

Proficiency Level

Interests

Learning Style

🔄 Personalization Pipeline

💬 Conversational UI & Speech Bubble Architecture

Speech Bubble Design System

Font Engineering for Trilingual Support

CJK Font Stack

📱 Responsive Design & Device Optimization

Desktop

Tablet

Mobile

🔄 Progressive Onboarding & Emotional Intelligence

Progressive Onboarding Architecture

Emotional Intelligence Feedback

Worried

Sleepy

Celebratory

Surprised

🔄 Onboarding Flow Sequence

⚡ Performance Optimization & Security Architecture

Performance Optimization

Content Visibility API

CSS Containment

Asset Pipeline

GPU Acceleration

Security & Compliance

🔒 Data Security Architecture

👤 Role-Based Access Control

🌐 Environment Separation

♿ Accessibility & Inclusive Design Compliance

Visual & Motor Accessibility

Cognitive & Wellness Accessibility

✅ Accessibility Features Summary

🧪 Assessment Module: Technical Data Capture & Integration

📚 Reading Comprehension Architecture & HKDSE Preparation

9 Question Type Taxonomy

Dual-Mode Practice System

🌍 Live Translation Engine & Multilingual Architecture

Trilingual Support

English

Cantonese

Mandarin

Classroom Management

👥 Attendance Monitoring

📊 Engagement Feedback

📊 Teacher Dashboard, Vocabulary System & Course Adventure

📊 Teacher Dashboard

📝 Vocabulary System

🗺️ Course Adventure

🏆 The Closed-Loop Learning Ecosystem

Everything Connects

🔵 For Teachers

🏫 For Schools

🟢 For Students

⚙️ Core Technologies

"Teach with Confidence. Learn without Limits."

🎤 Speaker Notes — Slide 1