LearnOS AI

The Open Learning Operating System.

LearnOS AI turns a learning or career goal into a structured, buildable workspace containing roadmaps, projects, architecture, tasks, Codex prompts, study packs, and interview preparation.

What is included

• AI workspace generation from a goal such as Become a Backend Engineer at Stripe
• Specialized Career Planner, Project Generator, Architect, Codex Planner, Lecture Assistant, and Interview Coach agents
• VS Code-inspired workspace explorer with Markdown preview, editing, copy, and ZIP export
• Lecture Assistant for PDF, DOCX, PPTX, TXT, and Markdown source material
• Generated summaries, notes, flashcards, quizzes, and viva questions
• Interview preparation grounded in workspace artifacts
• Better Auth email/password authentication with optional Google and GitHub providers
• Workspace ownership checks, RBAC, audit logs, secure headers, and server-side AI usage
• OpenAI provider abstraction with structured output and token/cost budgets

Requirements

• Node.js 22 or newer
• pnpm 11 or newer
• Docker Desktop (for local PostgreSQL)
• An OpenAI API key for live generation

Quick start

From the repository root:

pnpm install
Copy-Item .env.example .env

Set at least these values in .env:

DATABASE_URL=postgresql://learnos:learnos_dev_password@localhost:5432/learnos?schema=public
BETTER_AUTH_SECRET=<at-least-32-random-characters>
BETTER_AUTH_URL=http://localhost:3000
OPENAI_API_KEY=<server-side-key>
OPENAI_MODEL=gpt-5

Start PostgreSQL and initialize Prisma:

docker compose up -d postgres
pnpm db:generate
pnpm db:migrate

Start the application:

pnpm dev

Open http://localhost:3000. The public demo is available at /demo.

Useful commands

pnpm dev             # Start the Next.js development server
pnpm build           # Create a production build
pnpm start           # Serve the production build
pnpm typecheck      # Run strict TypeScript checks
pnpm lint           # Run ESLint across workspaces
pnpm test            # Run package tests
pnpm format          # Format the repository
pnpm env:check       # Validate environment configuration
pnpm db:generate     # Generate Prisma Client
pnpm db:migrate      # Apply local Prisma migrations
pnpm db:studio       # Open Prisma Studio

Application structure

apps/web/                 Next.js App Router application
packages/agents/          Provider contracts, OpenAI provider, and AI agents
packages/auth/            Better Auth configuration, email, permissions, and guards
packages/domain/          Shared domain types and entities
packages/application/     Use-case and application contracts
packages/infrastructure/  Prisma client and repositories
prisma/                   PostgreSQL schema, migrations, and seed support
docs/                     Product and architecture source documentation

The web application is organized into route groups:

• (marketing) — landing page and demo workspace
• (auth) — sign in, registration, password reset, and verification
• (platform) — authenticated dashboard, goals, workspaces, lecture assistant, interview prep, settings, and admin
• api/v1 — versioned protected API routes

Security model

Business resources are ownership-scoped to the authenticated user and workspace. Protected pages use server-side Better Auth session resolution; protected APIs validate the session again. Roles are SUPER_ADMIN, ADMIN, MENTOR, and STUDENT.

API keys remain server-side and encrypted when stored. Never expose OPENAI_API_KEY, email credentials, encryption keys, or database credentials to the browser. Configure a real BETTER_AUTH_SECRET and transactional email provider before deploying authentication flows.

AI execution enforces input/output token budgets, estimated request cost limits, daily request limits, and daily/monthly token limits. Usage is persisted per user, workspace, agent run, and provider request.

Production checklist

Before deployment:

1. Use a managed PostgreSQL database and apply migrations.
2. Set a unique high-entropy BETTER_AUTH_SECRET and production BETTER_AUTH_URL.
3. Configure OPENAI_API_KEY only as a server-side secret.
4. Configure one email provider: Resend, Postmark, or SMTP.
5. Configure API_KEY_ENCRYPTION_KEY through a secret manager or KMS-backed deployment.
6. Configure object storage before enabling production uploads.
7. Run pnpm typecheck, pnpm lint, pnpm test, and pnpm build in CI.
8. Verify workspace ownership, authentication, email delivery, AI limits, and ZIP export in a staging environment.

Documentation

The docs/ directory is the source of truth for product requirements, system architecture, API design, security, token optimization, UI/UX, and the demo flow.