STEMBlock.ai Frontend - Codebase Overview

Project Overview

STEMBlock.ai is an AI-powered STEM education platform with separate dashboards for Students, Coaches (Teachers), Parents, and Admins. The frontend is built with Next.js 15, React 19, TypeScript, and Tailwind CSS.

Technology Stack

Framework: Next.js 15.5.9
UI Library: React 19.0.0
Type Safety: TypeScript 5.5.0
Styling: Tailwind CSS 3.4.0
State Management: React Query (TanStack Query 5.28.0)
Forms: React Hook Form 7.53.0 + Zod for validation
HTTP Client: Axios 1.7.0

Project Structure

Root Directory Files

stemblockai-frontend/
├── app/                          # Next.js App Router
├── components/                   # Reusable UI components
├── lib/                          # Utilities and contexts
├── types/                        # TypeScript type definitions
├── tailwind.config.ts
├── tsconfig.json
├── package.json
└── next.config.js

Key Directories

1. app/ - Next.js Pages & Routes

app/
├── layout.tsx                    # Root layout with Providers
├── page.tsx                      # Home page
├── login/page.tsx               # Login page
├── register/page.tsx            # Registration page
├── auth/callback/page.tsx       # OAuth callback
│
├── student/
│   ├── dashboard/page.tsx       # Student dashboard
│   ├── assignments/[id]/page.tsx     # Assignment details
│   ├── submissions/[id]/page.tsx     # Submission editor
│   └── evaluations/[id]/page.tsx     # Evaluation/results
│
├── coach/
│   ├── dashboard/page.tsx       # Coach dashboard
│   ├── classes/[id]/page.tsx    # Class management (assignments, students, settings)
│   ├── submissions/[id]/page.tsx     # Review student submission
│   └── reviews/page.tsx         # Review queue
│
├── parent/
│   ├── dashboard/page.tsx       # Parent dashboard with children overview
│   ├── children/[studentId]/report/page.tsx    # Detailed student report
│   └── feedback/page.tsx        # Parent feedback submission
│
├── student/
│   └── feedback/page.tsx        # Student feedback submission
│
├── coach/
│   └── feedback/page.tsx        # Coach feedback inbox
│
└── admin/
    ├── dashboard/page.tsx       # Admin system overview
    ├── classes/page.tsx         # Class management
    ├── users/page.tsx           # User management
    └── feedback/page.tsx        # Admin feedback inbox

2. components/ - Reusable Components

components/
├── Navigation.tsx               # Header navigation (role-based)
├── Footer.tsx                   # Footer component
└── ui/                          # Shadcn-like UI components
    ├── Button.tsx
    ├── Input.tsx
    ├── Card.tsx
    ├── Badge.tsx
    ├── Progress.tsx
    └── index.ts

3. lib/ - Core Utilities

lib/
├── api.ts                       # Axios instance with interceptors
│                                 # - Auth API (login, register, profile)
│                                 # - Assignments API
│                                 # - Submissions API
│                                 # - Evaluations API
│                                 # - feedbackAPI (feedback CRUD)
│                                 # - gamificationAPI (XP, streaks, achievements)
│                                 # - analyticsAPI (heat maps, class stats)
│
└── auth-context.tsx            # React Context for authentication
                                 # - User state management
                                 # - Login/Register/Logout
                                 # - Token & user persistence

4. types/index.ts - TypeScript Definitions

Core data types used throughout the app:

User, Student, Coach
Class, ClassStudent
Assignment, AssignmentType
Submission, SubmissionFile, SubmissionStatus
Evaluation, EvaluationFeedback, CategoryFeedback
Feedback, FeedbackType, FeedbackStatus
GamificationStats, StreakData, XPData, Achievement
HeatMapResponse, ClassStats
API request/response types

Key Features & Implementation

1. Authentication & Authorization

File: lib/auth-context.tsx, app/login/page.tsx, lib/api.ts

JWT token-based authentication
Four user roles: STUDENT, COACH, PARENT, ADMIN
Login redirects based on user role
Google OAuth integration (backend-handled)
Token stored in localStorage with request interceptor
401 handling with automatic redirect to login

Flow:

Login → API returns JWT + User → Store in localStorage → 
Context manages state → Protected routes check role

2. Student Assignments & Submissions

Student Dashboard

File: app/student/dashboard/page.tsx

Features:

Load all assignments for student's classes
Progress tracking with completion percentage
Achievement badges (First Steps, Perfect Score, Star Student, On Fire)
Recent scores display
Gamification elements (Levels, Stars)

API Calls:

GET /assignments - All assignments
GET /submissions - Student's submissions
Filters submissions by evaluation status = 'PUBLISHED'

Assignment Detail Page

File: app/student/assignments/[id]/page.tsx

Features:

Display assignment details (title, description, due date, max score)
Show class and coach information
"Start New Submission" button
Lists existing submissions for that assignment

API Calls:

GET /assignments/\{id\} - Assignment details
POST /submissions - Create new submission → redirects to editor

Submission Page

File: app/student/submissions/[id]/page.tsx (referenced but not shown)

Expected Features:

File upload for code, photos, documentation
Draft/Submit workflow
Progress tracking
Delete submission ability

API Used:

GET /submissions/\{id\} - Get submission
POST /submissions/\{id\}/upload - Upload files
PATCH /submissions/\{id\}/submit - Mark as submitted
DELETE /submissions/\{id\} - Delete submission

Evaluation Results

File: app/student/evaluations/[id]/page.tsx (referenced but not shown)

Expected Features:

Display AI-generated feedback
Category scores (Robot Design, Code Quality, Documentation, Technical Writing)
Strengths and improvement areas
Coach feedback (if reviewed)

API Used:

GET /evaluations/\{id\} - Get evaluation
GET /evaluations/submission/\{submissionId\} - Get evaluation by submission

3. Coach Dashboard & Class Management

Coach Dashboard

File: app/coach/dashboard/page.tsx

Features:

Welcome message with coach name
System-wide stats (Classes, Students, Assignments, Review Queue)
Grid of all coach's classes
Create new class modal
Quick action to navigate to review queue

API Calls:

GET /classes - Coach's classes
POST /classes - Create class
GET /submissions - All submissions (for review queue count)

Class Detail Page (Most Complex Coach Feature)

File: app/coach/classes/[id]/page.tsx

Tabs:

Assignments Tab
- List all assignments for the class
- Edit/Delete existing assignments
- Create new assignment with modal
- Fields: Title, Description, Type, Due Date, Max Score
- Display submission count per assignment
Students Tab
- Grid of enrolled students
- Display: Name, Email, Grade Level, Enrollment Date
- Add student functionality
- Remove student functionality
- Filter out already-enrolled students
Settings Tab
- Google Classroom integration
- Link/Unlink Google Classroom
- Sync assignments from Google Classroom
- View class information (read-only)
- Delete class (danger zone)

API Calls:

GET /classes/\{id\} - Class details with students
GET /assignments?classId=\{id\} - Class assignments
POST /assignments - Create assignment
PUT /assignments/\{id\} - Update assignment
DELETE /assignments/\{id\} - Delete assignment
POST /classes/\{id\}/students/\{studentId\} - Add student
DELETE /classes/\{id\}/students/\{studentId\} - Remove student
GET /google-classroom/auth - Get auth URL
POST /google-classroom/sync/\{classId\} - Sync assignments
POST /google-classroom/disable/\{classId\} - Unlink

Review Queue

File: app/coach/reviews/page.tsx (referenced but implementation varies)

Expected Features:

Show submissions pending review (SUBMITTED or EVALUATED status)
Filter by assignment, student, status
Review submission with AI feedback
Add/edit coach feedback
Publish evaluation

4. Parent Dashboard & Child Reports

Parent Dashboard

File: app/parent/dashboard/page.tsx

Features:

Support for multiple children
Child selector if > 1 child
Quick summary cards:
- Overall progress (average score %)
- Recent activity (assignments completed)
- Active classes count
Recent Achievements section:
- Show 5 most recent published evaluations
- Display assignment title, score, AI feedback summary
- Color-coded badges by performance
Progress Over Time chart:
- Shows "Improving Steadily" or "Building Foundation"
- Last 3 assignment scores
Sidebar Sections:
- "What's Going Well" (AI-generated or fallback)
- "Areas to Focus On" (AI-generated or fallback)
- "Ways to Support at Home" (AI-generated or fallback)
- Links to Full Report, Coach Contact, PDF Download

AI Insights Feature:

Loads insights from: GET /parents/me/children/\{studentId\}/insights
Falls back to data-derived insights if API fails

API Calls:

GET /parents/me/children - Get all children with submissions
GET /parents/me/children/\{studentId\}/insights - AI-generated insights

Child Report Page

File: app/parent/children/[studentId]/report/page.tsx

Sections:

Overall Performance Card
- Large percentage score
- Performance badge (Above Average / Meeting Expectations / Needs Support)
- Contextual explanation
Skills Breakdown
- Robot Design & Engineering
- Programming Skills
- Documentation & Communication
- Technical Writing
- Each with:
  - Score percentage
  - Progress bar (color-coded)
  - Plain-language explanation
Recent Activities
- Last 5 submissions
- Color-coded by performance level
- Shows date, score, feedback summary
What's Going Well / Areas to Focus On
- Two-column layout with bullet points
- Evidence-based statements
How You Can Support at Home
- 4 numbered tips
- Parent-friendly language
Coach's Note
- Personal message from the coach
- Static/template content shown
Action Buttons
- Contact Coach
- Schedule Parent Meeting
- Download PDF Report (not implemented)

API Calls:

GET /parents/me/children/\{studentId\} - Student data with submissions

5. Admin Dashboard

Admin Dashboard

File: app/admin/dashboard/page.tsx

Features:

System-wide statistics:
- Total Users, Students, Parents, Coaches
- Total Classes, Assignments, Submissions
Quick action cards linking to:
- Manage Users
- Manage Classes
- System Settings (coming soon)

API Calls:

GET /admin/stats - System statistics

Admin Classes Management

File: app/admin/classes/page.tsx

Features:

Create new class (modal)
- Select coach from dropdown
- Name, Description
View all classes in grid
Each class card shows:
- Coach name
- Student count & Assignment count
- List of enrolled students with remove button
- "Add Student" & "View Details" buttons
Add Student to Class (modal)
- Filter students to exclude already-enrolled
- Select from dropdown

API Calls:

GET /admin/classes - All classes
GET /admin/coaches - Available coaches
GET /admin/students - All students
POST /admin/classes - Create class
POST /admin/classes/\{classId\}/students/\{studentId\} - Add student
DELETE /admin/classes/\{classId\}/students/\{studentId\} - Remove student

Admin Users Management

File: app/admin/users/page.tsx (referenced but implementation not shown)

Expected Features:

List all users
Create/Edit/Delete users
Assign roles

Authentication Flow Diagram

┌─────────────────────────────────────────────────────┐
│ Login Page (app/login/page.tsx)                     │
│ - Email/Password form (Zod validated)              │
│ - Google Sign-In button                            │
│ - Register link                                     │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────┐
│ API Call: POST /auth/login                         │
│ Response: { user, accessToken, student? }          │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────┐
│ AuthContext (lib/auth-context.tsx)                 │
│ - Store token in localStorage                      │
│ - Store user/student in localStorage               │
│ - Update React Context state                       │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────┐
│ Role-Based Redirect                                │
│ - STUDENT → /student/dashboard                    │
│ - COACH → /coach/dashboard                        │
│ - PARENT → /parent/dashboard                      │
│ - ADMIN → /admin/dashboard                        │
└─────────────────────────────────────────────────────┘

On subsequent requests:
┌─────────────────────────────────────────────────────┐
│ Axios Interceptor (lib/api.ts)                     │
│ - Add Authorization: Bearer {token} header         │
│ - On 401: clear storage & redirect to /login      │
└─────────────────────────────────────────────────────┘

API Integration Pattern

All API calls use the api instance from lib/api.ts:

// Example: Get assignments
const response = await api.get('/assignments')
const assignments = response.data  // Already typed

// With parameters
const response = await api.get(`/assignments/${id}`)

// POST with data
await api.post('/submissions', { assignmentId })

// PUT for updates
await api.put(`/assignments/${id}`, updatedData)

// DELETE
await api.delete(`/assignments/${id}`)

Base URL: process.env.NEXT_PUBLIC_API_URL (default: http://localhost:3001)

Type System

Core types in types/index.ts:

// User Types
User { id, email, firstName, lastName, role, createdAt, updatedAt }
Student { id, userId, age, gradeLevel, user, createdAt }
Coach { id, userId, user, createdAt }

// Class Types
Class { id, coachId, name, description, googleClassroomId, 
        googleClassroomName, googleClassroomSyncEnabled, 
        lastGoogleSyncAt, coach, students, assignments, _count }

// Assignment Types
Assignment { id, title, description, type, dueDate, maxScore, 
             createdAt, updatedAt, class, _count }

// Submission Types
Submission { id, assignmentId, studentId, status, submittedAt, 
             createdAt, updatedAt, assignment, student, files, evaluation }

// Evaluation Types
Evaluation { id, submissionId, overallScore, aiConfidence, 
             robotDesignScore, codeQualityScore, documentationScore, 
             technicalWritingScore, aiFeedback, status, createdAt, updatedAt }

Component Hierarchy

RootLayout (app/layout.tsx)
├── Providers (app/providers.tsx) [AuthProvider + Query Client]
├── Page content (children)
├── Navigation.tsx [Role-based header]
└── Footer.tsx

Dashboard Patterns

All dashboards follow this structure:

Page (use dynamic = 'force-dynamic')
├── Authentication check via useAuth()
├── Load data with useEffect
├── Conditional rendering based on loading/error/data
├── Grid/List display of main content
├── Modal for create/edit operations
└── Modals for confirmations

Notable Implementation Patterns

1. Dynamic Route Handler

const params = useParams()
const id = params.id as string

useEffect(() => {
  loadData(id)
}, [id])

2. Error Handling

try {
  // API call
} catch (err: any) {
  setError(err.response?.data?.message || 'Fallback error')
}

const [showModal, setShowModal] = useState(false)
// State for form data
// Handle submit with setShowModal(false)
// JSX with fixed inset-0 overlay + Card

const [activeTab, setActiveTab] = useState<TabType>('tab1')
// Buttons to switch tabs
// Conditional rendering: {activeTab === 'tab1' && <Content />}

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(1)
})

const { register, handleSubmit, formState: { errors } } = useForm({
  resolver: zodResolver(schema)
})

CSS/Styling Approach

Tailwind CSS with custom color scheme
Custom colors defined in tailwind.config.ts:
- stem-blue, stem-purple, stem-teal, stem-green, stem-orange, stem-pink, etc.
Typography: font-display (Poppins 600/700), font-sans (Inter)
Consistent component styling with borders: border-2 border-stem-*
Gradient backgrounds: bg-gradient-to-br from-* to-*

Key Features Summary

Feature	Student	Coach	Parent	Admin
View Assignments	✓	✓	-	-
Submit Work	✓	-	-	-
View Evaluations	✓	✓	✓	-
Create Classes	-	✓	-	✓
Manage Students	-	✓	-	✓
Create Assignments	-	✓	-	-
Review Submissions	-	✓	-	-
View Child Progress	-	-	✓	-
System Admin	-	-	-	✓
Google Classroom	-	✓	-	-
Submit Feedback	✓	-	✓	-
Feedback Inbox	-	✓	-	✓
Gamification (XP/Streaks)	✓	-	-	-
Class Analytics Heat Maps	-	✓	-	✓

Important Files Reference

File	Purpose
`types/index.ts`	All TypeScript type definitions
`lib/api.ts`	Axios instance + all API endpoints
`lib/auth-context.tsx`	Authentication state management
`app/layout.tsx`	Root layout with providers
`app/login/page.tsx`	Login page
`app/student/dashboard/page.tsx`	Student main view
`app/student/feedback/page.tsx`	Student feedback submission
`app/coach/dashboard/page.tsx`	Coach main view
`app/coach/classes/[id]/page.tsx`	Most complex coach feature
`app/coach/feedback/page.tsx`	Coach feedback inbox
`app/parent/dashboard/page.tsx`	Parent main view
`app/parent/children/[studentId]/report/page.tsx`	Detailed report
`app/parent/feedback/page.tsx`	Parent feedback submission
`app/admin/dashboard/page.tsx`	Admin overview
`app/admin/classes/page.tsx`	Admin class management
`app/admin/feedback/page.tsx`	Admin feedback inbox

Next Steps / Future Implementation Areas

Based on code comments and placeholder text:

Complete app/admin/users/page.tsx implementation
Implement submission editor page (app/student/submissions/[id]/page.tsx)
Implement evaluation details page
Implement coach review queue (app/coach/reviews/page.tsx)
PDF generation for reports
Contact coach functionality
Schedule parent meeting functionality
System settings page (admin)
Edit class information (coach settings)
Delete class functionality
More robust Google Classroom sync

Project Overview​

Technology Stack​

Project Structure​

Root Directory Files​

Key Directories​

1. app/ - Next.js Pages & Routes​

2. components/ - Reusable Components​

3. lib/ - Core Utilities​

4. types/index.ts - TypeScript Definitions​

Key Features & Implementation​

1. Authentication & Authorization​

2. Student Assignments & Submissions​

Student Dashboard​

Assignment Detail Page​

Submission Page​

Evaluation Results​

3. Coach Dashboard & Class Management​

Coach Dashboard​

Class Detail Page (Most Complex Coach Feature)​

Review Queue​

4. Parent Dashboard & Child Reports​

Parent Dashboard​

Child Report Page​

5. Admin Dashboard​

Admin Dashboard​

Admin Classes Management​

Admin Users Management​

Authentication Flow Diagram​

API Integration Pattern​

Type System​

Component Hierarchy​

Navigation & Layout​

Dashboard Patterns​

Notable Implementation Patterns​

1. Dynamic Route Handler​

2. Error Handling​

3. Modal Management​

4. Tab Navigation​

5. Form Validation (Login)​

CSS/Styling Approach​

Key Features Summary​

Important Files Reference​

Next Steps / Future Implementation Areas​

Project Overview

Technology Stack

Project Structure

Root Directory Files

Key Directories

1. app/ - Next.js Pages & Routes

2. components/ - Reusable Components

3. lib/ - Core Utilities

4. types/index.ts - TypeScript Definitions

Key Features & Implementation

1. Authentication & Authorization

2. Student Assignments & Submissions

Student Dashboard

Assignment Detail Page

Submission Page

Evaluation Results

3. Coach Dashboard & Class Management

Coach Dashboard

Class Detail Page (Most Complex Coach Feature)

Review Queue

4. Parent Dashboard & Child Reports

Parent Dashboard

Child Report Page

5. Admin Dashboard

Admin Dashboard

Admin Classes Management

Admin Users Management

Authentication Flow Diagram

API Integration Pattern

Type System

Component Hierarchy

Navigation & Layout

Dashboard Patterns

Notable Implementation Patterns

1. Dynamic Route Handler

2. Error Handling

3. Modal Management

4. Tab Navigation

5. Form Validation (Login)

CSS/Styling Approach

Key Features Summary

Important Files Reference

Next Steps / Future Implementation Areas