STEMBlock.ai - Routing and Navigation Guide

URL Structure & File Mapping

Authentication Routes

/login                 → app/login/page.tsx
/register              → app/register/page.tsx
/auth/callback         → app/auth/callback/page.tsx

Student Routes

/student/dashboard                    → app/student/dashboard/page.tsx
/student/assignments/[id]             → app/student/assignments/[id]/page.tsx
/student/submissions/[id]             → app/student/submissions/[id]/page.tsx
/student/evaluations/[id]             → app/student/evaluations/[id]/page.tsx
/student/feedback                     → app/student/feedback/page.tsx

Coach Routes

/coach/dashboard                      → app/coach/dashboard/page.tsx
/coach/classes/[id]                   → app/coach/classes/[id]/page.tsx
/coach/submissions/[id]               → app/coach/submissions/[id]/page.tsx
/coach/reviews                        → app/coach/reviews/page.tsx
/coach/feedback                       → app/coach/feedback/page.tsx

Parent Routes

/parent/dashboard                                → app/parent/dashboard/page.tsx
/parent/children/[studentId]/report             → app/parent/children/[studentId]/report/page.tsx
/parent/feedback                                 → app/parent/feedback/page.tsx

Admin Routes

/admin/dashboard                      → app/admin/dashboard/page.tsx
/admin/classes                        → app/admin/classes/page.tsx
/admin/users                          → app/admin/users/page.tsx
/admin/feedback                       → app/admin/feedback/page.tsx

---

Navigation Flow Chart

LOGIN PAGE (/login)
├─ Email/Password → POST /auth/login
│
├─ STUDENT ROLE ──→ STUDENT DASHBOARD (/student/dashboard)
│                  ├─ Assignment Card → /student/assignments/[id]
│                  │                   └─ Start Submission → /student/submissions/[id]
│                  └─ Evaluation Card → /student/evaluations/[id]
│
├─ COACH ROLE ────→ COACH DASHBOARD (/coach/dashboard)
│                  ├─ Class Card → /coach/classes/[id]
│                  │              ├─ Assignments Tab
│                  │              │  ├─ Create Assignment (modal)
│                  │              │  └─ Edit/Delete (modal)
│                  │              ├─ Students Tab
│                  │              │  ├─ Add Student (modal)
│                  │              │  └─ Remove Student
│                  │              └─ Settings Tab
│                  │                 ├─ Google Classroom Link
│                  │                 └─ Class Info
│                  ├─ Review Queue Card → /coach/reviews
│                  └─ Create Class (modal)
│
├─ PARENT ROLE ───→ PARENT DASHBOARD (/parent/dashboard)
│                  ├─ Child Selector (if > 1 child)
│                  ├─ Recent Achievement → /parent/children/[studentId]/report
│                  ├─ View Full Report Button → /parent/children/[studentId]/report
│                  └─ Submit Feedback → /parent/feedback
│
└─ ADMIN ROLE ────→ ADMIN DASHBOARD (/admin/dashboard)
                   ├─ Manage Users → /admin/users
                   ├─ Manage Classes → /admin/classes
                   │                  ├─ Create Class (modal)
                   │                  ├─ Add Student to Class (modal)
                   │                  └─ View Class Details → /coach/classes/[id]
                   └─ System Settings (coming soon)

---

Role-Based Access Control

Authentication State

Each user has a role field: STUDENT | COACH | PARENT | ADMIN

Route Protection Pattern

// In every page component:
const { user, loading: authLoading } = useAuth()

useEffect(() => {
  if (!authLoading && user) {
    if (user.role !== 'EXPECTED_ROLE') {
      router.push('/unauthorized')
      return
    }
    loadData()
  }
}, [authLoading, user, router])

Navigation Component (Role-Aware)

components/Navigation.tsx shows different links based on user role:

• Student: Dashboard, Assignments, Progress, Feedback
• Coach: Dashboard, Classes, Reviews, Feedback
• Parent: Dashboard, Children, Feedback
• Admin: Dashboard, Classes, Users, Feedback

---

Dynamic Route Parameters

Student Route: /student/assignments/[id]

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

// Loads:
- GET /assignments/{assignmentId}
- GET /submissions?assignmentId={assignmentId}

Coach Route: /coach/classes/[id]

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

// Loads:
- GET /classes/{classId}
- GET /assignments?classId={classId}

Parent Route: /parent/children/[studentId]/report

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

// Loads:
- GET /parents/me/children/{studentId}

---

Navigation State Management

Navigation Component

Located in components/Navigation.tsx, displays:

• Logo/Branding (links to /)
• Navigation menu (role-specific)
• User profile menu
• Logout functionality

Breadcrumbs Pattern

Used in detail pages:

<Link href="/coach/dashboard">
  <Button variant="secondary">← Back to Dashboard</Button>
</Link>

---

Modal Navigation Pattern

Modals don't create new routes; they're managed with local state:

const [showCreateModal, setShowCreateModal] = useState(false)

// Modal opens:
onClick={() => setShowCreateModal(true)}

// Modal closes:
onClick={() => setShowCreateModal(false)}

// JSX at bottom of page:
{showCreateModal && (
  <div className="fixed inset-0 ...">
    {/* Modal content */}
  </div>
)}

---

Tab Navigation Pattern

Used in /coach/classes/[id]:

type TabType = 'assignments' | 'students' | 'settings'
const [activeTab, setActiveTab] = useState<TabType>('assignments')

// Tab buttons:
<Button onClick={() => setActiveTab('assignments')}>
  Assignments
</Button>

// Conditional rendering:
{activeTab === 'assignments' && <AssignmentsList />}
{activeTab === 'students' && <StudentsList />}
{activeTab === 'settings' && <Settings />}

---

Next.js Link Component Usage

All navigation uses Next.js Link component for client-side navigation:

import Link from 'next/link'

// Standard link:
<Link href="/coach/dashboard">
  <Button>Go to Dashboard</Button>
</Link>

// Link with parameters:
<Link href={`/coach/classes/${classId}`}>
  <Card>View Class</Card>
</Link>

// Programmatic navigation (when needed):
import { useRouter } from 'next/navigation'
const router = useRouter()
router.push('/student/dashboard')

---

Deep Links & Query Parameters

Current implementation doesn't heavily use query parameters. Deep linking works as:

Student clicks Assignment → /student/assignments/abc123
  → Page loads assignment details
  → Click Start Submission → /student/submissions/xyz789
    → Page loads submission editor

---

Logout Flow

From any page, user can click logout in Navigation:

const { logout } = useAuth()

// Logout function in auth-context.tsx:
logout() → {
  - Clear localStorage
  - Clear React state
  - Redirect to /login
}

---

404 & Error Pages

Not explicitly implemented in shown code, but patterns used:

• Show error Card if data fails to load
• Show empty states with helpful messages
• Back buttons to return to previous context

---

Mobile Navigation Considerations

Navigation uses responsive Tailwind classes:

• Desktop: Horizontal navigation bar
• Mobile: Likely hamburger menu (implementation not shown)

All pages use responsive grid layouts:

className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3"

---

Important Navigation Notes

1. No client-side routing library needed - Next.js App Router handles all routing
2. Token auto-refresh - Not shown, may be backend-handled
3. Protected routes - Each page manually checks user.role
4. Back buttons - Explicitly placed; no browser back button navigation
5. Modals - Don't create routes; stay on same page
6. Form submissions - Don't change URL; modals close on success

---

Future Navigation Improvements

Based on comments in code:

1. Implement proper page-level route guards/middleware
2. Add 404 error page
3. Implement breadcrumb navigation component
4. Add keyboard shortcuts for power users
5. Implement search across assignments/classes
6. Add filter/sort parameters to URLs (query params)
7. History/previous visits tracking