Tutor Mx documentation

Architecture

The React/Vite single-page app is hosted separately from the handwritten Express API. The browser obtains an RS256 access token from Auth0 and sends it only in the Authorization header. Express validates the JWKS signature, issuer, audience, expiry, not-before and subject before accessing Neon PostgreSQL through Prisma. The browser never connects directly to Neon.

Browser → Cloudflare Pages → Auth0 Universal Login
Browser → Bearer access token → Render Express API → Prisma → Neon PostgreSQL

Local setup

1. Install Node.js 22 and run npm ci in the root and frontend directories.
2. Copy the example environment files and provide local-only values.
3. Run npm run db:migrate, then npm run dev.

Never commit environment files, tokens, database URLs, client secrets or Management API credentials.

API examples

Health and readiness are public; application data requires an Auth0 access token with audience https://api.tutormx.com.

GET /health
GET /ready
GET /api/me
Authorization: Bearer <access-token>

DELETE /api/auth/delete-account
Authorization: Bearer <access-token>

Ownership always comes from the verified token subject mapped to Profile.auth0Id. Browser-supplied user identifiers are never trusted.

Testing and coverage

CI runs Prisma generation, ESLint, TypeScript checking, backend and frontend tests, production builds and repository secret checks. Coverage is uploaded to Codecov from GitHub Actions without embedding credentials in source.

Deployment

• Frontend: Cloudflare Pages, static Vite output with SPA fallback.
• API: Render free web service with exact-origin CORS.
• Database: existing Neon tutor-mx-system production branch.
• Identity: Auth0 Universal Login with Google and database login.

Public deployment links are added after the first successful release.

Limitations

• Free hosting can sleep when idle, so the first API request may be slow.
• Auth0 development Google keys are suitable for demos, not a production launch.
• Members 2 and 4 are still being integrated into the same stable URLs.
• The public-holiday integration preserves a tested fallback when its external provider is unavailable.

AI attribution

AI tools assisted with integration, tests, documentation and deployment preparation. Human team members remain responsible for review, academic disclosure, security decisions and submitted work. See AI_DECLARATION.md in the repository.