Quick Start

Get the DoCurious frontend running locally in under five minutes.

Prerequisites

Tool	Minimum Version	Check
Node.js	20+	node -v
npm	10+	npm -v
Git	2.x	git --version

Clone and Install

git clone <repository-url> docurious-FE
cd docurious-FE
npm install

Environment Setup

Create a .env file in the project root (or copy from .env.example if available):

# Mock API mode (default: true)
# Set to 'false' to switch to the real backend API
VITE_USE_MOCK_API=true

# Backend API URL (only used when VITE_USE_MOCK_API=false)
VITE_API_URL=http://localhost:8000/api/portal

# OAuth / Third-party services (optional for local dev)
VITE_GOOGLE_CLIENT_ID=
VITE_STRIPE_PUBLIC_KEY=
VITE_RECAPTCHA_SITE_KEY=
VITE_GOOGLE_MAPS_API_KEY=
VITE_APPLE_CLIENT_ID=
VITE_APPLE_REDIRECT_URI=

By default, the app runs entirely with mock APIs -- no backend required. The mock database seeds itself on first load with demo users, challenges, communities, and all other data.

NPM Scripts

Script	Command	Description
dev	npm run dev	Start Vite dev server with HMR
build	npm run build	TypeScript check + production build
preview	npm run preview	Preview production build locally
lint	npm run lint	Run ESLint across the project
format	npm run format	Auto-format with Prettier
format:check	npm run format:check	Check formatting without writing
test	npm test	Run Vitest in watch mode
test:run	npm run test:run	Single Vitest run (CI mode)
test:coverage	npm run test:coverage	Run tests with V8 coverage report
test:e2e	npm run test:e2e	Run Playwright E2E tests (headless Chromium)
test:e2e:ui	npm run test:e2e:ui	Run Playwright with interactive UI
test:e2e:headed	npm run test:e2e:headed	Run Playwright in headed browser
test:all	npm run test:all	Run Vitest + Playwright back-to-back
storybook	npm run storybook	Launch Storybook on port 6006
build-storybook	npm run build-storybook	Build static Storybook
docs:dev	npm run docs:dev	Dev server for this documentation site
docs:build	npm run docs:build	Build documentation (TypeDoc + VitePress)
docs:preview	npm run docs:preview	Preview built documentation

Start the Dev Server

npm run dev

The app opens at http://localhost:5173. The mock database auto-seeds on first load.

Full-Stack Mode

The backend Express server lives in server/ — 129 Prisma models, 23 route files, 18 domain services, 164 passing tests.

# Terminal 1 — Install and start the backend
cd server && npm install
cp .env.example .env        # edit DATABASE_URL, JWT_SECRET, JWT_REFRESH_SECRET
npx prisma generate && npx prisma db push
npm run dev                  # http://localhost:8000

# Terminal 2 — Start the frontend with real API
VITE_USE_MOCK_API=false npm run dev

# Run backend tests
cd server && npm test        # 19 test files, 164 tests (Vitest + Supertest)

Required environment variables: DATABASE_URL, JWT_SECRET, JWT_REFRESH_SECRET. See server/.env.example for the full list including Cloudinary and Stripe keys.

See server/README.md for full API route tables, auth documentation, and database details.

Project Structure Overview

docurious-FE/
  src/              Frontend source code
    adapters/       SQL-to-FE data adapters (UUID mapping, status enums)
    api/            Mock + real API layer (26 modules)
    components/     Reusable UI components (26 directories, ~148 components)
    hooks/          Custom React hooks (useFeatureFlag, useLocation, useAddressSearch)
    lib/            Utility functions (cn class merge, contextHelpers)
    i18n/           Internationalization (en/es/fr)
    pages/          Route page components (189 pages)
    routes/         Router config + 7 guards (Auth, Role, Tier, Age, Consent, Context, Parent)
    store/          Zustand stores (30 stores)
    theme/          Theme system (7 presets, CSS variable injection)
    types/          TypeScript type definitions (32 files)
    App.tsx         Root component
    main.tsx        Entry point
  server/           Backend Express server
    prisma/         Prisma schema (~129 models) + seed
    src/
      routes/       23 route files (21 domain + prodData + index)
      controllers/  19 controllers
      services/     18 domain services
      middleware/   Auth, role guard, validation, error handler
      config/       Environment + CORS config
      utils/        JWT, password, pagination, response helpers
      __tests__/    19 test files, 164 tests (Vitest + Supertest)

Demo User Accounts

The mock database includes pre-seeded accounts for every role. Use the UserSwitcher dropdown in the application header to instantly switch between personas without logging out.

Persona	Email	Password	Home Route	Role Guide
Student	student@lincoln-elementary.edu	Student1234	/	Student
Teacher	teacher@lincoln-elementary.edu	Teacher1234	/school	Teacher
Parent	parent@example.com	Parent1234	/parent	Parent
School Admin	admin@lincoln-elementary.edu	Admin1234	/school	School Admin
Vendor	vendor@craftbox.com	Vendor1234	/vendor	Vendor
Platform Admin	platform@docurious.com	Platform1234	/admin/analytics	Platform Admin

There is also a dedicated demo landing page at /demo that presents these personas with descriptions and one-click login.

Debug Panel

Press Ctrl+Shift+D to open the Debug Panel -- a 6-tab development overlay for inspecting stores, network requests, feature flags, and other app internals. This panel is only available in development mode.

Next Steps

• Architecture -- understand the frontend system layers
• Backend Quick Start -- set up the Express server
• Stores -- Zustand state management patterns
• API -- mock/real API switching
• Routing -- route guards and lazy loading
• Theme -- theme system and presets