NCEAi (Frontend Core)

This is the frontend client for NCEAi, a React-based frontend built to provide an interactive dashboard for New Zealand NCEA students. The client manages student authentication, file uploading for study resources, quiz generation workflows, and real-time timed assessments with mathematical equation rendering.

The application is built using TypeScript, Vite, Tailwind CSS, and Shadcn UI components. The corresponding backend repository can be found here.

Directory Structure

├── index.html                  # Main entry HTML document
├── vite.config.ts              # Vite and plugin configuration
├── tailwind.config.ts          # Tailwind theme and custom animation rules
├── components.json             # Shadcn UI configuration
├── public/                     # Static asset files
└── src/
    ├── main.tsx                # Application mount entry point
    ├── App.tsx                 # Core routing, global layout, and provider setup
    ├── index.css               # Global CSS variables and Tailwind imports
    ├── components/             # Reusable layout and custom UI components
    │   ├── ui/                 # Base Shadcn primitive components (Radix)
    │   ├── Navigation.tsx      # Dashboard sidebar and state navigation
    │   └── MarkdowWithMath.tsx # LaTeX-enabled Markdown renderer
    ├── pages/                  # Route-level view components (Login, Study, QuizAttempt)
    ├── lib/                    # Shared core utilities (styling merges)
    └── utils/
        ├── api/                # Fetch client and endpoint declarations (auth, files, quiz)
        └── services/           # Frontend auth token store services

System Implementation

State & API Client (utils/api/)

• Custom HTTP Client: Standardized requests using a custom APIClient class built on the native browser fetch API. It dynamically injects JWT access tokens in the Authorization header and is configured with credentials: "include" to ensure stateful refresh token cookies are safely sent and received.
• Idempotency Management: Mutation forms generate UUIDs passed as an Idempotency-Token header. This matches the backend's idempotency middleware to guarantee that network retries do not trigger duplicate resource creation.
• Data Querying: Integrates TanStack Query (React Query) for caching, background revalidation, and state updates across pages like the quizzes list and study documents library.

Dashboard Layout & Navigation (components/ & pages/)

• Modular Navigation: Implements a sidebar that tracks authentication state, collapsing on smaller viewports and managing dynamic sub-pages.
• Route Guarding: Restricts views like study hubs and quiz environments behind JWT auth decorators, redirecting unauthorized users back to register/login flows.
• Real-Time Active Tracking: The quiz interface handles option selections and transmits a timed heartbeat payload to the server to record student focus duration.
• Math Rendering: Displays LaTeX equations in questions and solutions using KaTeX plugins.

Getting Started

Prerequisites

• Node.js (v18+) or Bun

Environment Setup

Create a .env file in the root directory by copying the example template:

cp .env.example .env

Adjust the variables to point to your backend API:

• VITE_API_BASE_URL: Base URL of the backend Flask API.
• VITE_APP_NAME: Display name of the application.

Installation

Install project dependencies:

npm install
# or if using bun:
bun install

Running Development Server

Start the client application locally on Vite:

npm run dev
# or if using bun:
bun run dev

Production Compilation

Compile and optimize static assets:

npm run build

Preview the compiled production bundle locally:

npm run preview