Merge pull request #311 from guillermoscript/chore/project-setup

chore(docs): project setup — env vars, README, test accounts, npm scripts

Author: HectorZR

.env.example

@@ -1,77 +1,80 @@
-# ============================================================
-# LMS Platform — Environment Variables
-# Copy this file to .env.local and fill in your values.
-# NEVER commit .env.local to version control.
-# ============================================================
+# ─── MINIMUM VIABLE LOCAL SETUP ──────────────────────────────────────────────
+# Copy this file to .env.local and fill in the values below.
+# Do NOT commit .env.local — it is listed in .gitignore.
+# At minimum, you need these 4 vars to run the app locally:
+#   NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY,
+#   SUPABASE_SERVICE_ROLE_KEY, NEXT_PUBLIC_PLATFORM_DOMAIN
 
-# ─── Supabase ────────────────────────────────────────────────
-# Found at: https://supabase.com/dashboard → Project Settings → API
-NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
-NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY=eyJ...          # anon / publishable key
-SUPABASE_SERVICE_ROLE_KEY=eyJ...                              # service_role key — keep secret!
+# ─── SUPABASE ─────────────────────────────────────────────────────────────────
+# Get these from: Supabase Dashboard → your project → Settings → API
+NEXT_PUBLIC_SUPABASE_URL=                          # Required — Supabase project URL
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY=      # Required — anon/publishable key
+SUPABASE_SERVICE_ROLE_KEY=                         # Required — service role key (bypasses RLS, server-only)
 
-# ─── Platform Domain ─────────────────────────────────────────
-# The root domain for subdomain routing. Each school gets school.yourdomain.com
-# For local dev: lvh.me:3000 (all subdomains resolve to localhost)
-NEXT_PUBLIC_PLATFORM_DOMAIN=yourdomain.com
-NEXT_PUBLIC_APP_URL=https://yourdomain.com
+# ─── STRIPE — STUDENT PAYMENTS (Connect) ──────────────────────────────────────
+# Students pay schools via Stripe Connect (PaymentIntents)
+# Get keys from: https://dashboard.stripe.com/apikeys
+STRIPE_SECRET_KEY=                                 # Required for payment features
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=                # Required for payment features
+STRIPE_WEBHOOK_SECRET=                             # Required — student payment webhook (/api/stripe/webhook)
 
-# ─── Stripe — Student Payments (Connect) ─────────────────────
-# Schools receive payments via Stripe Connect.
-# Found at: https://dashboard.stripe.com/apikeys
-STRIPE_SECRET_KEY=sk_live_...
-NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
-# Webhook secret for /api/stripe/webhook (student payments)
-# Created at: https://dashboard.stripe.com/webhooks → add endpoint
-STRIPE_WEBHOOK_SECRET=whsec_...
+# ─── STRIPE — SCHOOL BILLING (Platform) ───────────────────────────────────────
+# Schools pay the platform via Stripe Billing (Checkout + Subscriptions)
+STRIPE_PLATFORM_WEBHOOK_SECRET=                    # Required for school billing webhook (/api/stripe/platform-webhook)
 
-# ─── Stripe — Platform Billing (School Subscriptions) ────────
-# Platform charges schools for their plan (Starter, Pro, Business).
-# Webhook secret for /api/stripe/platform-webhook
-STRIPE_PLATFORM_WEBHOOK_SECRET=whsec_...
+# ─── PLATFORM ─────────────────────────────────────────────────────────────────
+NEXT_PUBLIC_PLATFORM_DOMAIN=lvh.me                 # Has-Default — subdomain base (lvh.me for local, yourdomain.com in prod)
+NEXT_PUBLIC_APP_URL=http://localhost:3000           # Has-Default — base URL of the app
+NEXT_PUBLIC_APP_NAME=LMS Platform                  # Has-Default — displayed in UI and emails
 
-# ─── AI — OpenAI (Exam Grading, Exercises, AI Tutor) ─────────
-# Found at: https://platform.openai.com/api-keys
-OPENAI_API_KEY=sk-...
+# ─── AI ───────────────────────────────────────────────────────────────────────
+OPENAI_API_KEY=                                    # Optional — server-side AI features (Aristotle tutor, grading)
+# ⚠ SECURITY: This key is exposed to the browser bundle. Do not use a production key here.
+# It is consumed by the speech-input component. Server-side proxying is the intended fix (tracked separately).
+NEXT_PUBLIC_OPENAI_API_KEY=                        # Optional — client-side speech input feature
+ASSEMBLYAI_API_KEY=                                # Optional — audio transcription for speech exercises
 
-# ─── Email — Mailgun ─────────────────────────────────────────
-# Used for enrollment confirmations, certificate delivery, welcome emails.
-# Found at: https://app.mailgun.com/mg/dashboard
-MAILGUN_API_KEY=key-...
-MAILGUN_DOMAIN=mg.yourdomain.com
-MAILGUN_API_URL=https://api.mailgun.net                       # use https://api.eu.mailgun.net for EU
-EMAIL_FROM=noreply@yourdomain.com
+# ─── OBSERVABILITY / LANGFUSE ─────────────────────────────────────────────────
+LANGFUSE_PUBLIC_KEY=                               # Optional — LLM observability (Langfuse)
+LANGFUSE_SECRET_KEY=                               # Optional
+LANGFUSE_BASEURL=                                  # Optional — defaults to Langfuse cloud if omitted
 
-# ─── Certificates ────────────────────────────────────────────
-# Used to sign and verify issued certificates.
-CERTIFICATE_ENCRYPTION_KEY=a-random-32-char-secret-string
-CERTIFICATE_ISSUER_NAME=Your Platform Name
+# ─── EMAIL / MAILGUN ──────────────────────────────────────────────────────────
+MAILGUN_API_KEY=                                   # Optional — transactional email
+MAILGUN_API_URL=                                   # Optional — e.g. https://api.eu.mailgun.net (EU region)
+MAILGUN_DOMAIN=                                    # Optional — your Mailgun sending domain
+EMAIL_FROM=                                        # Optional — e.g. noreply@yourdomain.com
 
-# ─── Company Info (used in invoices / emails) ────────────────
-COMPANY_NAME=Your Company Name
-COMPANY_EMAIL=hello@yourdomain.com
-COMPANY_ADDRESS=123 Main St, City, Country
-COMPANY_PHONE=+1 555 000 0000
+# ─── CERTIFICATES ─────────────────────────────────────────────────────────────
+CERTIFICATE_ENCRYPTION_KEY=                        # Optional — course completion certificate signing
+CERTIFICATE_ISSUER_NAME=                           # Optional — displayed on certificates
 
-# ─── Cron Jobs ───────────────────────────────────────────────
-# Secret to authenticate /api/cron/* endpoints (called by Vercel Cron).
-# Generate with: openssl rand -hex 32
-CRON_SECRET=your-random-cron-secret
+# ─── INFRASTRUCTURE (deployment only) ─────────────────────────────────────────
+CLOUDFLARE_ZONE_ID=                                # Optional — Cloudflare DNS zone for custom domains
+CF_DNS_API_TOKEN=                                  # Optional — Cloudflare API token
+SERVER_IP=                                         # Optional — deployment target IP
 
-# ─── PayPal (Optional — alternative payment provider) ────────
-# Only required if PAYMENT_PROVIDER=paypal
-PAYPAL_CLIENT_ID=
-PAYPAL_CLIENT_SECRET=
-PAYMENT_PROVIDER=stripe                                       # stripe | paypal | manual
+# ─── PAYMENTS — PAYPAL ────────────────────────────────────────────────────────
+PAYPAL_CLIENT_ID=                                  # Optional — PayPal payment provider
+PAYPAL_CLIENT_SECRET=                              # Optional
+PAYMENT_PROVIDER=stripe                            # Has-Default — stripe | manual | paypal
 
-# ─── MCP Server (Optional — AI development tooling) ──────────
-MCP_SERVER_URL=
-MCP_PROXY_SECRET=
+# ─── MCP SERVER ───────────────────────────────────────────────────────────────
+# The mcp-server/ sub-project exposes LMS data to AI agents via MCP protocol.
+# See mcp-server/.env.example for the MCP server own env vars.
+MCP_PROXY_SECRET=                                  # Optional — shared secret for MCP proxy auth
+MCP_SERVER_URL=http://localhost:3001               # Has-Default — URL of the MCP server
 
-# ─── CORS (Optional — restrict API origins) ──────────────────
-ALLOWED_ORIGIN=https://yourdomain.com
+# ─── CRON ─────────────────────────────────────────────────────────────────────
+CRON_SECRET=                                       # Optional — protects cron endpoints (/api/cron/*)
 
-# ─── Local Development Only ──────────────────────────────────
-# NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
-# NEXT_PUBLIC_PLATFORM_DOMAIN=lvh.me:3000
-# NEXT_PUBLIC_APP_URL=http://lvh.me:3000
+# ─── INVOICING ────────────────────────────────────────────────────────────────
+COMPANY_NAME=                                      # Optional — appears on generated invoices
+COMPANY_ADDRESS=                                   # Optional
+COMPANY_EMAIL=                                     # Optional
+COMPANY_PHONE=                                     # Optional
+
+# ─── TESTING ──────────────────────────────────────────────────────────────────
+BASE_URL=http://localhost:3000                     # Has-Default — base URL for Playwright tests
+E2E_BASE_URL=http://localhost:3000                 # Has-Default — explicit E2E base URL
+E2E_TENANT_BASE_URL=http://testschool.lvh.me:3000  # Has-Default — tenant subdomain for E2E multi-tenant tests

CLAUDE.md

@@ -191,17 +191,48 @@ Feature gating uses `get_plan_features(_tenant_id)` RPC as single source of trut
 
 ## Environment Variables
 
+See `.env.example` for the full list with Required/Optional tags (33 vars across 14 categories). The minimum required vars to run locally:
+
 ```
 NEXT_PUBLIC_SUPABASE_URL=
 NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY=
 SUPABASE_SERVICE_ROLE_KEY=         # Bypasses RLS — admin ops only
-STRIPE_SECRET_KEY=
-NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
-STRIPE_WEBHOOK_SECRET=             # For Connect webhook (student payments)
-STRIPE_PLATFORM_WEBHOOK_SECRET=    # For Billing webhook (school plan payments)
-NEXT_PUBLIC_PLATFORM_DOMAIN=       # e.g. lmsplatform.com (for subdomain routing)
+NEXT_PUBLIC_PLATFORM_DOMAIN=       # e.g. lvh.me for local dev, lmsplatform.com in prod
+```
+
+Categories at a glance:
+- **Supabase** (3 vars): URL, anon key, service role key
+- **Stripe — Student Payments** (3 vars): secret key, publishable key, webhook secret
+- **Stripe — School Billing** (1 var): platform webhook secret
+- **Platform** (3 vars): domain, app URL, app name
+- **AI** (3 vars): OPENAI_API_KEY, NEXT_PUBLIC_OPENAI_API_KEY _(client-side — see Security Notes)_, ASSEMBLYAI_API_KEY
+- **Observability / Langfuse** (3 vars): public key, secret key, base URL
+- **Email / Mailgun** (4 vars): API key, API URL, domain, from address
+- **Certificates** (2 vars): encryption key, issuer name
+- **Infrastructure** (3 vars): Cloudflare zone ID, DNS API token, server IP
+- **Payments — PayPal** (3 vars): client ID, client secret, PAYMENT_PROVIDER
+- **MCP Server** (2 vars): MCP_PROXY_SECRET, MCP_SERVER_URL
+- **Cron** (1 var): CRON_SECRET
+- **Invoicing** (4 vars): company name, address, email, phone
+- **Testing** (3 vars): BASE_URL, E2E_BASE_URL, E2E_TENANT_BASE_URL
+
+## MCP Server
+
+An MCP (Model Context Protocol) sub-server lives in `mcp-server/`. It exposes LMS data to AI agents via the MCP protocol.
+
+**Setup:**
+```bash
+cd mcp-server
+cp .env.example .env   # fill in SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, MCP_PROXY_SECRET
+npm install
+npm run build
+npm start
 ```
 
+The MCP server runs separately from the Next.js app on port 3001 by default (`MCP_SERVER_PORT`). The `mcp:build` npm script builds it from the project root: `npm run mcp:build`.
+
+**Env vars** (see `mcp-server/.env.example`): `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `MCP_PROXY_SECRET`, `MCP_SERVER_PORT`, `MCP_SERVER_HOST`.
+
 ## Testing
 
 E2E tests in `tests/playwright/`. Four files by priority:
@@ -210,7 +241,11 @@ E2E tests in `tests/playwright/`. Four files by priority:
 - `payment-security.spec.ts` — P0, 7 tests
 - `comprehensive-security-audit.spec.ts` — P1/P2, 26 tests
 
-Test accounts: `student@test.com` / `teacher@test.com` / `admin@test.com` — all `password123`
+Test accounts (from `supabase/seed.sql` — seeded by `supabase db reset`):
+- `student@e2etest.com` / `password123` — student (Default School)
+- `owner@e2etest.com` / `password123` — admin (Default School)
+- `creator@codeacademy.com` / `password123` — teacher (Code Academy, subdomain: `code-academy.lvh.me:3000`)
+- `alice@student.com` / `password123` — student (Code Academy)
 
 Pre-commit checklist: `npm run build` · tenant filter on every query · tested with all relevant roles · loading + error states handled
 
@@ -235,6 +270,12 @@ Pre-commit checklist: `npm run build` · tenant filter on every query · tested
 - **`enroll_user()` RPC** loops through ALL courses per product (FOR loop) — a product can have multiple courses via `product_courses`.
 - **Transactions unique constraint** is a partial index on `(user_id, product_id, plan_id) WHERE status IN ('pending', 'successful')` — allows retries after failed payments.
 
+## Security Notes
+
+- **`NEXT_PUBLIC_OPENAI_API_KEY`** is exposed to the browser bundle (used for speech input). Do not use a production key. Server-side proxying is the intended fix (tracked separately).
+- **Sentry DSN** is currently hardcoded in `sentry.server.config.ts`. This is intentional (public DSN) but consider moving to an env var for consistency.
+- **Test account passwords** (`password123`) are for local development only — seeded by `supabase db reset`. Never use these credentials in a deployed environment.
+
 ## Key Documentation
 
 - `docs/DATABASE_SCHEMA.md` — complete schema with relationships

README.md

@@ -1,36 +1,61 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
-
-## Getting Started
-
-First, run the development server:
-
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
-
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
-
-## Learn More
-
-To learn more about Next.js, take a look at the following resources:
-
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
-
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
-
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+# LMS Platform
+
+A multi-tenant SaaS Learning Management System. Schools run on subdomains (`school.platform.com`). Educators create and sell courses; students enroll and learn.
+
+**Stack:** Next.js 16 · React 19 · TypeScript · Supabase · Shadcn UI · Tailwind CSS v4 · Stripe Connect · next-intl (en/es)
+
+## Prerequisites
+
+- Node.js 20+
+- Docker (required for local Supabase)
+- [Supabase CLI](https://supabase.com/docs/guides/cli)
+- Stripe CLI _(optional — only for testing webhooks locally)_
+
+## Quick Start
+
+1. **Clone and install**
+   ```bash
+   git clone <repo-url>
+   cd lms-front
+   npm install
+   ```
+
+2. **Configure environment**
+   ```bash
+   cp .env.example .env.local
+   # Fill in at minimum: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_OR_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY
+   ```
+
+3. **Start local Supabase** _(requires Docker)_
+   ```bash
+   supabase start
+   supabase db reset   # applies all migrations + seeds test data
+   ```
+
+4. **Run the dev server**
+   ```bash
+   npm run dev
+   ```
+
+5. **Open the app**
+   Visit `http://localhost:3000` — or use a tenant subdomain like `http://testschool.lvh.me:3000`
+
+## npm Scripts
+
+| Script | Command |
+|--------|---------|
+| `npm run dev` | Start dev server |
+| `npm run build` | Production build (TypeScript + lint) |
+| `npm run lint` | Run ESLint |
+| `npm test` | Run Playwright E2E tests |
+| `npm run db:reset` | Reset local DB (migrations + seed) |
+| `npm run db:push` | Push migrations to cloud Supabase |
+| `npm run mcp:build` | Build the MCP server sub-project |
+
+## Documentation
+
+- [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) — full local setup guide
+- [`CLAUDE.md`](CLAUDE.md) — architecture reference for AI agents and developers
+- [`docs/DATABASE_SCHEMA.md`](docs/DATABASE_SCHEMA.md) — complete DB schema
+- [`docs/AUTH.md`](docs/AUTH.md) — authentication flows
+- [`docs/MONETIZATION.md`](docs/MONETIZATION.md) — billing and payments