Project Setup & Development Guide¶

Last updated: June 2026 (revised — clean-deploy step, Firebase fully removed)

Environment Setup¶

Built with Vite 6, React 19, and TypeScript (strict mode).

Key Dependencies¶

Package	Purpose
`react-router-dom` v7	Client-side routing
`motion`	UI animations
`lucide-react`	Icon system
`chart.js` + `react-chartjs-2`	Radar charts
`recharts`	Bar / line charts
`tailwindcss` v4	Styling
`@tailwindcss/typography`	Prose formatting
`html2canvas-pro` + `jspdf`	PDF export
`@google/genai`	Gemini AI integration
`date-fns`	Date formatting

Firebase SDK completely removed. All auth is handled by VPS JWTs (/api/auth/* endpoints). All data is stored in MongoDB via the VPS API.

Dev Dependencies¶

Package	Purpose
`typescript` ~5.8	Type checking
`tsx`	TypeScript script runner

Local Development¶

# Install dependencies
npm install

# Start development server (port 3000, all interfaces)
npm run dev

# Type-check without emitting files
npm run lint

# Production build
npm run build

# Preview production build
npm run preview

Environment Variables¶

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

# Gemini AI
VITE_GEMINI_API_KEY=...

# Stripe (publishable key — frontend only)
VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...

# VPS backend API
VITE_API_URL=https://mind-meditate.com
# For local dev: VITE_API_URL=http://localhost:5002

Deploying to Production¶

Frontend¶

Always clear the remote /assets/ folder before uploading — Vite hashes change each build and old files accumulate indefinitely.

# Option A — manual (from client folder)
push-location "c:\My Apps\Personality-Test\client"; npm run build; pop-location
ssh root@76.13.211.100 "rm -rf /opt/personality-app/public/assets"
scp -r "c:\My Apps\Personality-Test\client\dist\*" root@76.13.211.100:/opt/personality-app/public/

# Option B — automated script (recommended)
& "c:\My Apps\hostinger\deploy-personality.ps1"

Backend¶

SCP changed route files to the VPS and restart PM2:

scp "c:\My Apps\Personality-Test\server\src\routes\<file>.js" root@76.13.211.100:/opt/personality-app/src/routes/
ssh root@76.13.211.100 "pm2 restart personality-app --update-env && pm2 save"

Repository Structure¶

``text Personality-Test/ client/ Frontend (React 19 + Vite 6 + TypeScript) src/ pages/ Full-page route components lifeDesign/ Future Studio step components growthLoop/ Growth Loop tab components admin/ AdminDashboard components/ Shared UI (Layout, ProtectedRoute, JourneyProgressStrip) contexts/ UserProfileContext (shared auth + profile state) services/ Pure logic (ikigai, insights, career, compatibility, AI, payment) api/ auth.ts (VPS auth calls), config.ts (localStorage shim), client.ts (VPS HTTP client + JWT helpers), db.ts (MongoDB API calls) utils/ Scoring engine + journey gate rules + gamification data/ Static JSON (framework, questions, scoring, etc.) types/ TypeScript interfaces vps-routes/ Legacy scaffolding (not deployed — superseded by server/src/routes/) public/ PWA manifest, service worker server/ Backend (Express + MongoDB, Node 20) src/ server.js Express entry point; mounts all routes middleware/ auth.js JWT verification (jwt.verify`) + adminMiddleware + orgAdminMiddleware rateLimiter.js Per-user rate limiter (120 req/min, keyed on uid) routes/ users.js User profiles responses.js Assessment responses coaches.js Coach profiles coachRequests.js Coach–user requests notifications.js In-app notifications organisations.js Organisations + plan activation cohorts.js Coach cohorts teams.js Teams (join by code) shareLinks.js Report share tokens promoCodes.js Promo code management coachApplications.js Coach onboarding applications conversations.js Coach–user messaging workshops.js Workshop listings reportFeedback.js Report feedback / reactions stripe.js Stripe checkout, webhook, verify-session ai.js Gemini AI endpoints admin.js Admin plan management (change-plan endpoint) auth.js Register, login, forgot/reset password utils/ agentCommissions.js Commission tier logic — shared by stripe.js

Branching Strategy¶

main — production-ready code
develop — integration branch for new features
feature/* — individual feature branches