chore: cleanup project root and refactor documentation structure

Author: Tanner Osterkamp

README.md

@@ -12,19 +12,23 @@ A modern, full-stack mentorship platform built specifically for healthcare profe
 Built with Next.js 15, Supabase PostgreSQL, Clerk authentication, AI-enhanced matching (OpenAI/Gemini), and comprehensive healthcare compliance features.
 
 ## 🚀 Live Demo
+
 [Production: sandboxmentoloop.online](https://sandboxmentoloop.online)
 
 Deployed via GitHub → Netlify. Preview environment available. Documentation lives in `docs/` within this repo.
 
 ## 📸 Screenshots
 
 ### Student Dashboard
+
 ![Student Dashboard](https://sandboxmentoloop.online/window.svg)
 
 ### AI-Powered Matching
+
 ![AI Matching](https://sandboxmentoloop.online/globe.svg)
 
 ### Preceptor Management
+
 ![Preceptor Dashboard](https://sandboxmentoloop.online/file.svg)
 
 ## Core Healthcare Features
@@ -57,6 +61,7 @@ Deployed via GitHub → Netlify. Preview environment available. Documentation li
 ## Tech Stack
 
 ### Frontend
+
 - **Next.js 15** - React framework with App Router
 - **TailwindCSS v4** - Utility-first CSS framework
 - **shadcn/ui** - Modern component library
@@ -68,6 +73,7 @@ Deployed via GitHub → Netlify. Preview environment available. Documentation li
 - **React Bits** - Custom animation components
 
 ### Backend & Services
+
 - **Supabase** - PostgreSQL database with RLS policies and real-time subscriptions
 - **Clerk** - Authentication and user management
 - **OpenAI** - AI-enhanced matching with GPT-4
@@ -78,50 +84,54 @@ Deployed via GitHub → Netlify. Preview environment available. Documentation li
 - **Svix** - Webhook validation
 
 ### Development & Testing
+
 - **TypeScript** - Type safety throughout
 - **Vitest** - Unit testing framework
 - **Playwright** - End-to-end testing
 - **Testing Library** - Component testing
 - **Turbopack** - Fast build tool
 
 ### Deployment & Infrastructure
+
 - **Netlify** - Primary deployment (connected to GitHub)
 - **GitHub Actions** - CI pipeline
 - **Environment Management** - Secrets in Netlify dashboard
 
 ## Operations Quick Reference
 
 ### Environment Variables
+
 Secrets managed in Netlify dashboard. Required for production:
 
-| Key | Description |
-| --- | --- |
-| `SUPABASE_URL` | Supabase project URL (server-side) |
-| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL (client-side) |
-| `SUPABASE_ANON_KEY` | Supabase anon key (server utilities/tests) |
-| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anon key (client-side) |
-| `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key (server-side) |
-| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk publishable key |
-| `CLERK_SECRET_KEY` | Clerk secret key |
-| `NEXT_PUBLIC_CLERK_FRONTEND_API_URL` | Clerk JWT template issuer URL |
-| `STRIPE_SECRET_KEY` | Stripe secret key |
-| `STRIPE_WEBHOOK_SECRET` | Stripe webhook secret |
-| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe publishable key |
-| `SENTRY_DSN` | Sentry DSN (auto-injected to client) |
-| `SENDGRID_API_KEY` | SendGrid API key |
-| `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` | Twilio credentials |
+| Key                                                              | Description                                |
+| ---------------------------------------------------------------- | ------------------------------------------ |
+| `SUPABASE_URL`                                                   | Supabase project URL (server-side)         |
+| `NEXT_PUBLIC_SUPABASE_URL`                                       | Supabase project URL (client-side)         |
+| `SUPABASE_ANON_KEY`                                              | Supabase anon key (server utilities/tests) |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY`                                  | Supabase anon key (client-side)            |
+| `SUPABASE_SERVICE_ROLE_KEY`                                      | Supabase service role key (server-side)    |
+| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`                              | Clerk publishable key                      |
+| `CLERK_SECRET_KEY`                                               | Clerk secret key                           |
+| `NEXT_PUBLIC_CLERK_FRONTEND_API_URL`                             | Clerk JWT template issuer URL              |
+| `STRIPE_SECRET_KEY`                                              | Stripe secret key                          |
+| `STRIPE_WEBHOOK_SECRET`                                          | Stripe webhook secret                      |
+| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`                             | Stripe publishable key                     |
+| `SENTRY_DSN`                                                     | Sentry DSN (auto-injected to client)       |
+| `SENDGRID_API_KEY`                                               | SendGrid API key                           |
+| `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER` | Twilio credentials                         |
 
 ### Deployment
+
 1. Push to `main` → Netlify auto-builds
 2. Build runs: `npm run lint`, `npm run type-check`, `npm run build`
 3. Deploy succeeds if build passes
 4. Verify at https://sandboxmentoloop.online
 
 ### Health Checks
+
 - `GET /api/health` - JSON response with service status
 - Expected: HTTP 200 with `"status": "ok"`
 
-
 ## Getting Started
 
 ### Prerequisites
@@ -142,6 +152,7 @@ cp .env.example .env.local
 ```
 
 Configure `.env.local`:
+
 ```bash
 NEXT_PUBLIC_SUPABASE_URL=your-project-url
 NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
@@ -170,15 +181,19 @@ npx playwright test     # E2E tests
 ## Architecture
 
 ### Database Layer
+
 Supabase PostgreSQL with Row Level Security policies. Service resolver pattern at `lib/supabase/serviceResolver.ts` routes API calls to service implementations in `lib/supabase/services/`.
 
 ### Authentication
+
 Clerk handles auth. Users synced to Supabase via webhook. Protected routes use middleware checking Clerk session.
 
 ### Payments
+
 Stripe checkout integration. 70/30 revenue split for preceptor compensation. Webhook validates payment events.
 
 ### Key Routes
+
 - `/` - Landing page
 - `/dashboard` - Protected dashboard
 - `/student-intake` - Student onboarding flow
@@ -195,18 +210,30 @@ Stripe checkout integration. 70/30 revenue split for preceptor compensation. Web
 ├── components/
 │   ├── ui/                 # shadcn/ui components
 │   └── react-bits/         # Custom animations
+├── docs/                   # Project documentation
+│   └── reports/            # Generated reports and plans
 ├── lib/
 │   ├── supabase/           # Database layer
 │   │   ├── services/       # Service implementations
 │   │   └── serviceResolver.ts  # API router
 │   ├── supabase-hooks.ts   # React hooks
 │   └── supabase-api.ts     # API definitions
+├── scripts/                # Utility scripts
 └── middleware.ts           # Route protection
 ```
 
+## Documentation
+
+Detailed documentation, reports, and implementation plans can be found in the `docs/` directory.
+
+- **Reports & Plans**: `docs/reports/` contains generated reports, migration plans, and status updates.
+- **Architecture**: `docs/architecture/` contains architectural decisions and diagrams.
+- **Security**: `docs/security/` contains security audits and implementation guides.
+
 ## Key Components
 
 ### Landing Page
+
 - **Hero Section** - Animated hero with CTAs
 - **Features Section** - Interactive feature showcase
 - **Pricing Table** - Custom Clerk billing integration
@@ -215,12 +242,14 @@ Stripe checkout integration. 70/30 revenue split for preceptor compensation. Web
 - **Footer** - Links and information
 
 ### Dashboard
+
 - **Sidebar Navigation** - Collapsible sidebar with user menu
 - **Interactive Charts** - Data visualization with Recharts
 - **Data Tables** - Sortable and filterable tables
 - **Payment Gating** - Subscription-based access control
 
 ### Animations & Effects
+
 - **Splash Cursor** - Interactive cursor effects
 - **Animated Lists** - Smooth list animations
 - **Progressive Blur** - Modern blur effects
@@ -239,6 +268,7 @@ The starter kit includes a fully customizable theme system. You can customize co
 ### Local Development
 
 See `.env.example` for complete list. Required:
+
 - Supabase URL, anon key, service role key
 - Clerk publishable key, secret key, frontend API URL
 - Stripe publishable key, secret key, webhook secret