Edorax is a project-based learning platform. Mentors write MDX chapters with graded checkpoints such as quizzes, tests, must-reads, open questions, and runnable code. Learners work through those chapters. Progress and reports are computed on the server.
The platform source is in this repository. Course packages, Agent IP, and editorial work live in the private devweekends/Edorax-core repository. Export archives are excluded from both repositories. Existing canvas and lab implementations stay in packages/learning-ui so the web and desktop apps can keep rendering them. See content separation.
The full product and technical spec lives in docs/. Start there. Security, gating, and grading rules are spelled out in the topic docs linked from that map.
The LMS uses Postgres. It does not use Mongo. Mongo is what some course lessons teach, not what the platform runs on.
- Write and publish courses as MDX, with an in-app editor and versioned releases.
- Teach with interactive blocks: quizzes, code exercises, open questions, predict questions, diagrams, videos, AI interviews, and capstone checks.
- Enroll learners, lock later modules until earlier ones are complete, and review submitted work.
- Let learners rate courses, ask a mentor for help, and (when configured) ask a short question about a chapter.
- Browse a public catalog, listen to narrated courses as audiobooks, and run visual labs on a board.
- Use XP, streaks, levels, credits, and opt-in leaderboards (each can be turned off with a server flag). See gamification.
- Request paid course access, apply discount codes, and manage organization enrollments and credits. Checkout does not collect card payments in the app; an administrator grants access after payment is arranged.
- Run an instructor workspace with reports, campaigns, coupons, and a wallet for payouts.
- Use a platform admin area for users, organizations, discounts, and course access.
- Connect organizations through the public
/integrations/v1API. - Use the desktop app for the catalog, a native reader, and a course IDE with local or Docker workspaces.
Some learner areas are still being built. Bite-sized practice, puzzles, on-call voice tutors, guided labs, and shell labs have overview pages but are not open yet. See learning areas.
Two independent apps, each with its own package.json and lockfile, can be deployed from its own folder (Vercel root directory frontend; Heroku, Render, or Fly from server). The split from the original Next.js monolith is recorded in docs/phases/backend-split.mdx.
| Folder | What | Stack |
|---|---|---|
frontend/ |
Web app. UI only. Every read and write goes through the API. | Next.js 16 (App Router), TypeScript, Tailwind, shadcn/ui, Playwright, Vitest |
server/ |
API. Owns Postgres, sessions, email, background jobs, content scripts, and the contract code in src/shared. |
Express 5, TypeScript, Prisma 7, Zod, Vitest and supertest |
packages/learning-ui/ |
Shared canvases and visual labs used by the web and desktop apps. | React library, linked as a local file: dependency |
desktop/ |
Electron desktop app. Optional for local web development. | Electron Forge, React, TypeScript, Tailwind |
The code both web apps run (block schemas and graders, API wire types, enums, MDX block extraction, and pure helpers) lives in server/src/shared. The web app carries a committed copy in frontend/src/shared. pnpm sync-shared refreshes it, and CI fails when it is stale. There is no workspace link between the two app folders, which is what lets each deploy on its own.
Browser code calls same-origin /api/v1/*. Next.js proxies it to the API (API_URL). Organizations and other tenants call /integrations/v1/* on the API host directly.
- Node.js 20.19 or later. CI and the Docker images use Node 20. The API package requires
>=20.19. The rootpackage.jsonlistsengines.nodeas24.x(used by some host deploys). - pnpm 12.11.2 (the version pinned in each app's
packageManagerfield) - Docker, for local Postgres, or point
DATABASE_URLat any Postgres instance instead
pnpm install && pnpm install:all # root: the `concurrently` helper; then server/ and frontend/
cp server/.env.example server/.env # DATABASE_URL, APP_URL, email keys
cp frontend/.env.example frontend/.env # API_URL (the web app never talks to Postgres)
docker compose up -d # starts local Postgres on :5432
pnpm db:ready # migrate deploy + prisma generate (use after git pull)
pnpm db:seed # 1 admin, 1 mentor, 3 mentees, 1 course placeholder, 4 preview enrollments
pnpm dev # API on :4000, web on :3000Run one side on its own with pnpm --dir server dev or pnpm --dir frontend dev. You can also cd into the folder and treat it as a normal project. Nothing outside that folder is required for that app to start, except a reachable API for the web app.
Sessions, sign-up, verification emails, and magic links are all handled by the API. Set AUTH_RESEND_KEY and EMAIL_FROM in server/.env (from Resend) to send real email. Without a key, the API logs the links instead and activates new accounts immediately, so the whole flow stays testable offline.
After seeding, the login page shows a one-click picker for the seeded accounts. It is hidden when NODE_ENV=production. The accounts are:
admin@buildment.devmentor@buildment.devmentee1@buildment.devmentee2@buildment.devmentee3@buildment.dev
Clicking one signs in through the normal login API. You can also call GET /api/v1/auth/dev-login?email=... on the API, which mints a real database session for that seeded user. That route returns 404 when NODE_ENV=production.
A clean clone seeds a small catalog placeholder. Full course lessons are published from the private Edorax-core repository.
Mentors can ask OpenRouter to draft feedback for a pending open-question response. Configure the credential on the server only. Never use a NEXT_PUBLIC_ prefix.
OPENROUTER_API_KEY=your-rotated-key
OPENROUTER_REVIEW_MODEL=google/gemini-2.5-flash # optionalThe request is made only after the mentor clicks Draft with AI. The mentor sees and edits the draft, then chooses the final verdict. See docs/05-review-queue.mdx for the data-sharing boundary.
Run from the repo root unless noted.
| Command | What it does |
|---|---|
pnpm dev |
Start the API and the web app together |
pnpm build |
Build server, then frontend |
pnpm test |
Vitest in both apps (the server suite needs Postgres) |
pnpm typecheck / pnpm lint |
Type-check / lint both apps |
pnpm sync-shared |
Refresh frontend/src/shared from server/src/shared after editing contract code |
pnpm db:migrate |
prisma migrate dev (server) |
pnpm db:seed |
Re-run the seed script (idempotent; it upserts) |
pnpm db:studio |
Prisma Studio, a GUI for the local database |
pnpm content:import |
Legacy local import when BUILDMENT_CONTENT_ROOT points to a private content checkout |
pnpm content:validate |
Compile-check every stored chapter the way publish does (needs a database) |
pnpm --dir server content:validate:source |
Compile-check a private course checkout (no database) |
pnpm --dir server content:audit |
Structural audit (gates, learning logs, STYLE heuristics) |
pnpm --dir server db:seed:showcase |
Add realistic, repeatable demo history after the course import |
pnpm --dir frontend exec playwright test |
Browser end-to-end suite (starts API and web itself; see frontend/playwright.config.ts) |
pnpm --dir desktop start |
Start the Electron app (install it first with pnpm --dir desktop install; the API should already be running) |
Content and seed scripts live in server/scripts, next to the database they write. The content-root environment variable is still named BUILDMENT_CONTENT_ROOT.
Copy the example files and fill in values as needed. Names only, from those files:
Server (server/.env.example): NODE_ENV, PORT, LOG_LEVEL, DATABASE_URL, APP_URL, CORS_ORIGINS, AUTH_RESEND_KEY, EMAIL_FROM, ADMIN_NOTIFY_EMAIL, CRON_SECRET, DISABLE_RATE_LIMITS, OPENROUTER_API_KEY, OPENROUTER_REVIEW_MODEL, AI_KEY_ENCRYPTION_KEY, OPENROUTER_INTERVIEW_MODEL, ANTHROPIC_API_KEY, LEARNER_QA_ENABLED, LEARNER_QA_MODEL, LEARNER_QA_DAILY_LIMIT, LEARNER_QA_GLOBAL_DAILY_LIMIT, R2_ENDPOINT, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, INTEGRITY_MEDIA_SECRET, JOBS_ENABLED, WEEKLY_GOAL_REMINDER_HOUR_UTC, INTEGRITY_RETENTION_HOUR_UTC, NOTIFICATION_WORKER_ENABLED, NOTIFICATION_WORKER_INTERVAL_MS, REMINDER_DAILY_LIMIT, REALTIME_TOKEN_SECRET, GAMIFICATION_XP, GAMIFICATION_STREAK_FREEZES, GAMIFICATION_LEVELS, GAMIFICATION_CAREER_LEVELS, GAMIFICATION_LEADERBOARDS, GAMIFICATION_CREDITS.
Frontend (frontend/.env.example): API_URL, NEXT_PUBLIC_REALTIME_URL, SENTRY_DSN, NEXT_PUBLIC_SENTRY_DSN, SENTRY_ORG, SENTRY_PROJECT, NEXT_PUBLIC_POSTHOG_KEY, NEXT_PUBLIC_POSTHOG_HOST, APP_URL, NARRATION_BASE_URL.
For local development you only need DATABASE_URL and APP_URL on the server, and API_URL on the frontend. The rest are optional. Email, AI, object storage, Sentry, and PostHog stay off unless you set their keys.
The desktop app uses BUILDMENT_API_URL and BUILDMENT_WEB_URL when it should talk to a deployment other than http://localhost:4000 and http://localhost:3000. See desktop/README.md.
pnpm test # Vitest for the API and the web app
pnpm --dir frontend exec playwright test # browser end-to-end testsThe API test suite needs Postgres (DATABASE_URL, or TEST_DATABASE_URL). CI starts Postgres 16, runs pnpm db:ready and pnpm db:seed, then runs the server tests. Frontend unit tests do not need a database.
Each folder deploys on its own. Nothing outside it is needed for that deploy.
- Web on Vercel: import the repository, set Root Directory to
frontend, and keep the Next.js preset. Environment:API_URL(the API's public URL) andAPP_URL(the Vercel URL). Browser traffic to/api/v1/*and/integrations/v1/*is proxied to the API on the server, so there is no CORS and the session cookie just works. Live notifications use Server-Sent Events through the same proxy. Optionally setNEXT_PUBLIC_REALTIME_URLto the API's public URL (at build time) to open the stream straight to the API instead. - API on Heroku: deploy this repository. The root
Procfilesupports a root deployment.server/Procfilesupports a monorepo buildpack withAPP_BASE=server. The release phase runsprisma migrate deploy. Publish course updates separately from the privateEdorax-coreworkflow against the same database. Thebuildscript generates the Prisma client and compiles. Config vars:DATABASE_URL,APP_URL(the web URL, used in email links),CORS_ORIGINS, the email and OpenRouter keys fromserver/.env.example, andCRON_SECRET. Scheduled jobs (hourly study reminders, daily cleanup, and the daily weekly-goal and integrity jobs) run inside the process. SetJOBS_ENABLED=falseon every dyno but one, or hand the schedule to an external scheduler callingPOST /api/v1/jobs/*(study reminders hourly). The notification email worker also runs in the process and is safe on every dyno. With more than one dyno, set the sameREALTIME_TOKEN_SECRETeverywhere. Seedocs/12-notifications.mdxfor what live push needs across replicas. - Containers anywhere:
docker build -f server/Dockerfile -t edorax-api .anddocker build -t edorax-web frontend/(Next.js standalone output).docker compose --profile app up --buildruns Postgres, migrations, and both apps locally. - CI (
.github/workflows/ci.yml): one job per app (typecheck, lint, tests against Postgres, production build), a check thatfrontend/src/sharedmatchesserver/src/shared, and, onmain, both image builds.
The live site is www.edorax.com.
frontend/ Web app (Next.js)
server/ API (Express, Prisma, jobs, content scripts)
packages/learning-ui/ Shared canvases and visual labs
desktop/ Electron desktop app
docs/ Product and technical docs
docker-compose.yml Local Postgres, and an optional full-stack profile
See docs/07-architecture.mdx for the route and folder layout, and docs/11-decisions-and-open-questions.mdx for a running log of decisions, including places where the stack drifted from the original spec (for example Next.js 16 instead of 15, and Prisma 7's driver-adapter requirement).
The desktop app and the API have their own READMEs.
Start at docs/README.mdx. Useful entry points:
- Product overview
- Architecture
- Learning areas
- Content separation
- Capstone checks and certificates
- Organization API
- Notifications
- Gamification
There is no CONTRIBUTING file in this repository yet. Open a pull request against main. After you edit contract code in server/src/shared, run pnpm sync-shared and commit the updated copy in frontend/src/shared.