Web App Reference — `apps/web/`¶

Operational reference for apps/web/: tech stack versions, full route structure, deploy commands, env vars, key features, and DS doc index. For behavior rules and coding conventions, see apps/web/CLAUDE.md.

Table of Contents¶

Tech Stack Versions
Dev Commands
Project Structure (Full)
Route File Layout
Key Features
Design System Doc Index
i18n Namespaces
Environment Variables
Deployment

Tech Stack Versions¶

Item	Value
Framework	React 19.2 + Vite 8 (Rolldown)
Language	TypeScript 6.0 (strict)
Styling	Tailwind CSS 4.1 (CSS-first, `@theme` directives)
Font	Manrope (weights 400-700)
Design System	`@kwilo/ui` (Radix UI primitives, Storybook); tokens from `@kwilo/design-tokens`
State	Zustand 5 (auth + complex forms) + TanStack Query 5.96 + React Hook Form
Routing	React Router 7.14 (all routes lazy-loaded)
UI	`@kwilo/ui` + Heroicons + Lucide React
Editor	TipTap 3.22
Calendar	Schedule-X 4.3
Charts	Recharts 3.8
Formatting	Prettier 3.8 + prettier-plugin-tailwindcss
Pages	112 (all code-split via React.lazy)
Services	46 API client modules

Dev Commands¶

pnpm dev             # Dev server (port 5173, proxies /api/* to localhost:8000)
pnpm build           # Production build (~1s with Vite 8 Rolldown)
pnpm type-check      # TypeScript check
pnpm lint            # ESLint
pnpm format          # Prettier (auto-fix)
pnpm test            # Vitest

# Pre-commit CI check (runs all above):
cd ../.. && pnpm ci:web

Project Structure (Full)¶

apps/web/src/
├── components/         # 28 dirs: ui/, layouts/, guards/, ai-tutor/, ai-quota/,
│                       # content-editor/, content-renderer/, calendar/, analytics/,
│                       # proctoring/, evaluation/, physical-exam/, gamification/,
│                       # knowledge-base/, feature-flags/, subscription-plans/,
│                       # targeting/, terminology/, college/, creator/, homework/,
│                       # messaging/, courses/, attendance/, bug-report/,
│                       # notifications/, video/, admin/
├── pages/              # 112 page components — role-based folders:
│                       # platform-admin/, org-admin/, school-admin/, teacher/,
│                       # student/, parent/, creator/, shared/, auth/
├── routes/             # Route modules — split per role
│   ├── index.tsx           # <AppRoutes> composition
│   ├── lazy-pages.ts       # All lazy() page imports, grouped by section
│   ├── PublicRoutes.tsx    # Root redirect, privacy, OAuth callback
│   ├── AuthRoutes.tsx      # /login, /register, /forgot-password
│   ├── CreatorRoutes.tsx   # /creator/* (external educator flow)
│   └── ProtectedRoutes/
│       ├── index.tsx           # DashboardLayout + ProtectedRoute guard
│       ├── SharedRoutes.tsx    # Multi-role pages
│       ├── ContentRoutes.tsx   # Teacher+admin shared
│       ├── TeacherRoutes.tsx   # Teacher-only
│       ├── StudentRoutes.tsx   # Student-only
│       ├── AdminRoutes.tsx     # School/org admin
│       ├── PlatformAdminRoutes.tsx  # Platform admin only
│       └── ParentRoutes.tsx    # Parent-only
├── services/           # 46 API client services (api.ts = Axios base)
├── stores/             # Zustand (auth.ts only)
├── hooks/              # useProctoring, useTerminology, useFeatureFlag, etc.
├── types/              # TypeScript definitions
├── App.tsx             # Thin shell (ErrorBoundary + Suspense + <AppRoutes/>)
└── main.tsx

Route File Layout¶

Routes are split per role. Each file under routes/ exports a named function (not a React component). See the route module pattern in apps/web/CLAUDE.md for the mandatory call convention.

Key Features¶

Feature	Notes
Physical Exams	List, create, upload answer sheets, review/grade, marks register (5 pages)
AI Tutor	SSE streaming via `src/services/ai-tutor.ts`. Event types: `text`, `tool_call`, `tool_result`, `done`. Role-specific modes (teachers: content gen, students: Socratic)
TipTap Editor	Callout blocks, video embeds, images, math/LaTeX, code blocks, markdown tables (remark-gfm)
Schedule-X Calendar	Day/week/month views, Google Calendar-style event popups
100ms Video	HMS React SDK for online classes
Face Enrollment	MediaPipe facial recognition for student verification + attendance
Gamification	Badges, points, leaderboard

Design System Doc Index¶

Full DS rules live in packages/ui/docs/. Read the relevant doc before building or modifying any UI.

Design tokens (colors, spacing, typography, radius, elevation, motion) are authored once in @kwilo/design-tokens as DTCG JSON (packages/design-tokens/tokens/*.tokens.json). Style Dictionary generates the TypeScript constants, the Tailwind v4 @theme CSS, and the React Native output from that single source, so @kwilo/ui (web) and @kwilo/ui-native (mobile) consume the same values and never drift. To change a token, edit the JSON, run pnpm --filter @kwilo/design-tokens generate, and commit the regenerated generated/ output. CI fails if that output falls out of sync with the source.

Doc	When to read
BRAND.md	Writing ANY user-facing text, i18n copy, empty states, errors, toasts
COLOR.md	Choosing colors, status indicators, applying green/amber/red
COMPONENTS.md	Using any DS component, button variants, card patterns, dialogs, forms
TYPOGRAPHY.md	Font sizes, weights, Heading/Text usage
SPACING.md	Padding, gaps, margins — 4px grid
ELEVATION.md	Shadows
MOTION.md	Animations, hover transitions
ACCESSIBILITY.md	WCAG AA, contrast, ARIA, keyboard nav, focus rings

i18n Namespaces¶

Locale files live in src/i18n/locales/en/*.json (one file per namespace). Registered in src/i18n/index.ts.

Namespace	Coverage
`common`	Shared labels, actions
`auth`	Login, register, password
`nav`	Sidebar, breadcrumbs
`dashboard`	Home / overview
`courses`	Course management
`lessons`	Lesson creation/viewing
`assignments`	Assignment flow
`homework`	Homework flow
`submissions`	Submission review
`evaluation`	Grading, rubrics
`calendar`	Schedule-X views
`aiTutor`	AI tutor chat
`parent`	Parent portal
`messages`	Messaging
`settings`	User/org settings

Environment Variables¶

VITE_API_URL=http://localhost:8000/api/v1                               # dev
VITE_API_URL=https://vidyanet-backend-12843608316.asia-south1.run.app/api/v1  # prod

Deployment¶

Auto-deploys on push to main / staging via .github/workflows/web-cf-pages.yml.

Manual fallback:

pnpm --filter @kwilo/web build
npx wrangler@3 pages deploy apps/web/dist --project-name=kwilo-web --branch=main
# Requires CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID

TanStack Query defaults: 5-min stale, 30-min cache. Axios interceptor auto-refreshes tokens on 401.

Web App Reference — apps/web/¶