Home

BetterMind — Technical Wiki

Welcome to the engineering documentation for BetterMind, an AI-powered mental health platform built on the Next.js 14 App Router.

This wiki is the technical companion to the README. Where the README is a product overview, the wiki documents how the system is built — architecture, data flow, the API surface, the auth/security model, the design system, and the guest-mode internals.

📚 Pages

Page	What's inside
Architecture	System diagram, request lifecycle, rendering model, key design decisions
Tech-Stack	Every dependency and why it was chosen
API-Reference	Complete route-handler reference with methods, auth, and payloads
Authentication-and-Security	JWT flow, TOTP 2FA, encryption, rate limiting, RBAC
Design-System	The light design system: tokens, components, color psychology
Guest-Mode	How demo-mode browsing and the auth-gate work
Local-Development	Setup, environment variables, scripts, troubleshooting

🧭 Mental model in 60 seconds

• One Next.js app serves both the UI (React Server/Client Components) and the backend (/api/* Route Handlers).
• MongoDB is the single source of truth, accessed through the official driver via a cached client promise.
• Auth is a custom JWT layer — an httpOnly token cookie, verified server-side on every protected route, with an optional TOTP 2FA challenge gating login.
• Three roles — patient, doctor, admin — each with its own pages and server-side guards.
• External services are optional: OpenAI (AI chat), Google Calendar (appointment sync). The app degrades gracefully when their keys are absent.
• Guest Mode is a purely client-side concern: demo data is rendered locally and any write action is intercepted by a single requireRealUser() gate.

Repository

• Code: https://github.com/harshcode1/BetterMind
• Default branch: main