DoCurious — Engineer Onboarding Guide

Everything you need to clone, run, and start contributing.

Quick Start (5 minutes)

Prerequisites

• Node.js 20+
• PostgreSQL 17
• npm

1. Clone & Install

git clone <repo-url>
cd docurious-FE
npm install
cd server && npm install && cd ..

2. Database Setup

# Ensure PostgreSQL is running
# The database `docurious_prod` should already exist (converted from MySQL dump)
cd server
npx prisma generate    # Generate Prisma client
npx prisma db push     # Sync schema (or npx prisma migrate dev)
cd ..

3. Run Everything

# Terminal 1: Frontend (port 5173)
npm run dev

# Terminal 2: Backend (port 3001)
cd server && npm run dev

The frontend runs with mock data by default — no backend needed for most flows. The backend is required for real API calls (auth, challenges, track records, gamification).

---

First 5 Files to Read

#	File	Why
1	src/routes/index.tsx	The entire app's route map — every URL, every guard, every page
2	src/store/useAuthStore.ts	Auth state, role system, context switching — the foundation
3	src/types/challenge.types.ts	Core domain model — challenges, track records, entries
4	src/api/mockDb.ts + src/api/seed.ts	The mock data layer — understand the data shape
5	server/src/services/auth.service.ts	Backend pattern — service → controller → route

---

Key Concepts

User Roles & Contexts

Users can have multiple contexts (personal, school, business, platform). The useAuthStore manages context switching:

General User → personal context only
Student      → school + (personal if Tier 2)
Teacher      → school + personal
School Admin → school + personal
Vendor       → business + personal
Platform Admin → platform + personal

Route guards enforce context + role access. See src/routes/guards/.

Mock vs Real APIs

Every domain has two API files:

• src/api/challenge.api.ts — Mock (in-memory, works offline)
• src/api/challenge.real.api.ts — Real (calls Express backend)

To switch: Stores import from one or the other. During development, mock APIs let you work on UI without the backend running.

The Adapter Pattern

Backend returns SQL-shaped data (snake_case, BigInt IDs). The adapter layer in src/adapters/ converts it:

• uuid → id (promotes UUID to primary identifier)
• Status mapping (ACTIVE → approved, etc.)
• Field renaming (snake_case → camelCase)

Theme System

CSS variables defined in src/theme/. Brand palette:

• Scout Green #3D5A3C
• Brass Gold #D4A15E
• Canvas Cream #F5F0E8

Tailwind CSS 4 with tailwind-merge for class deduplication. Components use cn() utility for conditional classes.

---

How to Add a New Feature (End-to-End)

Example: Adding a "Challenge Wishlist" feature

Step 1: Types

# Add types to src/types/challenge.types.ts (or new file)
# Define WishlistItem, WishlistState, etc.

Step 2: Store

# Create src/store/useWishlistStore.ts (or add to useChallengeStore)
# Follow Zustand pattern: state + actions

Step 3: Mock API

# Add to src/api/challenge.api.ts (or new file)
# Implement in-memory CRUD against mockDb

Step 4: Components

# Create src/components/challenge/WishlistButton.tsx
# Create src/pages/challenges/Wishlist.tsx

Step 5: Route

# Add route in src/routes/index.tsx:
# { path: 'wishlist', element: <LazyPage><Wishlist /></LazyPage> }

Step 6: Backend (when ready)

# server/src/services/wishlist.service.ts
# server/src/controllers/wishlist.controller.ts
# server/src/routes/wishlist.routes.ts
# Mount in server/src/index.ts

Step 7: Real API + Adapter

# src/api/wishlist.real.api.ts — calls backend
# src/adapters/wishlistAdapter.ts — if needed

---

Running Tests

# Frontend tests
npm test                    # Run all
npm test -- --watch         # Watch mode

# Backend tests
cd server && npm test       # Run all 19 test suites

# Storybook (visual testing)
npm run storybook           # Opens at localhost:6006

# E2E (Playwright, if configured)
npx playwright test

---

Documentation

Resource	How to Access	What's There
VitePress Knowledge Base	npm run docs:dev	15 feature guides, 7 role guides, dev guide
Storybook	npm run storybook	55 interactive component stories
TypeDoc API Reference	npm run docs:build then docs-site/	Auto-generated from types, stores, adapters
Screenshots	docs/app-map-screenshots.html	73 screenshots organized by flow
Spec Gap Report	docs/spec-gap-report.md	What's built, partial, placeholder, missing
Architecture Diagrams	docs/app-flow-diagrams.md	Mermaid diagrams for all major flows
Data Model	docs/data-model-reference.md	Entity relationships
Color Palette	docs/color-palette.md	Brand colors + design tokens

---

Common Tasks

Switch user role for testing

Ctrl+Shift+D opens the Debug Panel → use the role switcher tab

Add a new admin tool page

1. Create component in src/pages/admin/YourTool.tsx
2. Export from src/pages/admin/index.ts
3. Add lazy import in src/routes/index.tsx
4. Add route under admin section with ContextGuard context="platform"

Add a Storybook story

Create src/components/yourDomain/YourComponent.stories.tsx following existing patterns. Use withMockData decorator for domain components that need store data.

Add an i18n string

1. Add key to src/i18n/locales/en.json
2. Add translations to es.json and fr.json
3. Use const { t } = useTranslation() then t('your.key')

---

Team Contacts

Area	Who to Ask
Architecture decisions	[Your name]
Spec questions	[Your name] — see V2 specs in the specs folder
Design questions	[Designer]
Backend / database	[Your name]