NEXUS

AI-Powered Learning Platform with Gamification, Sandbox Labs & Knowledge Synthesis

Features • Screenshots • Getting Started • Architecture • AI Agents • API Reference • Deployment

NEXUS is a full-stack learning platform that combines 5 specialized AI agents (powered by Claude), real container-based labs, spaced-repetition review, gamification mechanics, and a personal knowledge encyclopedia into a cohesive self-directed learning experience.

Built with Next.js 16, React 19, SQLite (Drizzle ORM), Tailwind v4, Framer Motion, and the Anthropic SDK. Works fully offline with mock fallbacks when no API key is configured.

Features

Learning & AI Tutoring

Personalized Curriculum -- ATLAS agent designs adaptive learning paths across CS, Infrastructure, Security, and AI/ML domains
Interactive AI Tutor -- SOCRATES agent teaches via Socratic method with streaming SSE responses
Assessment Engine -- MINERVA agent generates quizzes, evaluates answers, and creates spaced-repetition review cards
Research & Diagrams -- LEONARDO agent visualizes concepts and synthesizes research

Hands-On Labs

8 lab templates across 4 domains (C programming, Git, Docker, Nginx, SSH, file permissions, Python data, Jupyter)
Real container execution via OrbStack/Docker integration with provisioning, command exec, file browsing, and validation
60-min sessions with 3x 30-min extensions, heartbeat keepalive, auto-cleanup
WebSocket terminal -- xterm.js with interactive shell (orb exec) and garden-themed colors

Knowledge System

Grokpedia -- Personal encyclopedia with HERMES agent for deep multi-source research and article synthesis
Knowledge Graph -- Force-directed visualization of article interconnections
Full-Text Search -- SQLite FTS5 with highlight snippets
Wikilink System -- [[Topic]] syntax with automatic backlink detection and resolution
Citation Tracking -- Sources from Reddit, Stack Overflow, Hacker News, DEV.to, GitHub

Notes & Vault

Obsidian-style editor -- Split-pane layout with rich markdown toolbar (bold, italic, code, headings, lists, blockquotes, links, tasks)
Live preview with syntax-highlighted code blocks
[[Wikilink]] support with backlinks panel
Obsidian vault sync -- Export notes as .md files with YAML frontmatter
Deep search -- Multi-source research dialog powered by HERMES

Gamification

XP & Levels -- 50-level progression with exponential scaling
Streak System -- Daily streak tracking with purchasable streak freezes (500 XP)
Daily Quests -- 4 deterministic quests per day with bonus XP on completion
25 Achievements -- 7 categories (milestones, streaks, volume, mastery, levels, reviews, special)
Challenge Mode -- 3 modes (Sprint 60s, Marathon 3min, Blitz 30s) with combo multipliers and leaderboard
Growth Garden -- Visual plant growth mapped to learning progress
Shareable Stats Card -- Screenshot-ready progress card with level, XP, streaks

Spaced Repetition

SM-2 algorithm implementation for optimal review scheduling
Auto-generated flashcards on lesson completion
Quality rating (0-5) with adaptive interval scheduling
Review dashboard with due/completed counts and session summaries

UI/UX

14 pages + custom 404 with loading skeletons and error boundaries
Command Palette (Cmd+K) -- Search across notes, lessons, paths, achievements, grokpedia + quick actions
Keyboard shortcuts -- ? opens shortcuts modal, 1-9 navigates to pages
Mobile navigation -- Bottom tab bar with slide-out drawer
Light/Dark themes -- Garden dark (default) + warm botanical light theme
Notification center -- Bell icon with 7 notification types and 30s polling
Data export -- Export notes (.md) and progress (.json)

Screenshots

Dashboard	Learn
Progress	Achievements
Notes	Skill Map
Grokpedia	Article Reader
Command Palette

Getting Started

Prerequisites

Node.js 22+ (LTS recommended)
npm 10+
OrbStack or Docker (optional, for sandbox labs)
Anthropic API Key (optional, app works fully with mock fallbacks)

Installation

# Clone the repository
git clone https://github.com/Ag-surfer/nexus.git
cd nexus

# Install dependencies
npm install

# Set up environment variables (optional)
cp .env.example .env
# Edit .env to add your ANTHROPIC_API_KEY if you have one

# Push database schema & seed with demo data
npm run db:push
npm run db:seed

# Start development server
npm run dev

Open http://localhost:3000 in your browser.

Development Scripts

Command	Description
`npm run dev`	Start Next.js dev server (Turbopack)
`npm run dev:pty`	Start WebSocket PTY server (port 3001) for lab terminals
`npm run dev:full`	Start both Next.js and PTY server
`npm run build`	Production build (standalone)
`npm run start`	Start production server
`npm run db:push`	Push schema changes to SQLite
`npm run db:seed`	Seed database with demo data (3 paths, 24 lessons, 5 grokpedia articles, etc.)
`npm run db:studio`	Open Drizzle Studio (database GUI)
`npm run test:e2e`	Run Playwright E2E tests
`npm run lint`	Run ESLint

Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	No	Claude API key. Omit to use mock fallbacks.
`GITHUB_TOKEN`	No	GitHub token for LEONARDO knowledge crawler
`OBSIDIAN_VAULT_PATH`	No	Local Obsidian vault path for note sync (e.g., `~/Obsidian/garden`)
`FIRECRAWL_API_KEY`	No	Firecrawl API key for JS-heavy doc site crawling

Architecture

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, Turbopack)
UI	React 19, Tailwind v4, shadcn/ui, Framer Motion
Database	SQLite via better-sqlite3 + Drizzle ORM
AI	Anthropic Claude SDK (claude-sonnet-4-20250514)
Terminal	xterm.js + WebSocket (ws)
Containers	OrbStack / Docker (runtime detected)
Testing	Playwright (E2E)
Deployment	Docker (multi-stage) / Fly.io

Project Structure

nexus/
├── src/
│   ├── agents/                 # 5 AI agents + router + runner
│   │   ├── atlas/              # Curriculum design
│   │   ├── socrates/           # Interactive tutoring (streaming)
│   │   ├── minerva/            # Assessment & review generation
│   │   ├── leonardo/           # Diagrams & research
│   │   ├── hermes/             # Deep search & article synthesis
│   │   ├── router.ts           # Action -> agent routing
│   │   ├── runner.ts           # Claude API execution + mock fallback
│   │   ├── context.ts          # Student context builder
│   │   └── types.ts            # Shared agent types
│   ├── app/                    # Next.js App Router pages
│   │   ├── page.tsx            # Dashboard
│   │   ├── learn/              # Learning paths + lesson view
│   │   ├── labs/               # Lab catalog + lab session
│   │   ├── progress/           # Journey tracking
│   │   ├── review/             # Spaced repetition
│   │   ├── challenge/          # Challenge modes
│   │   ├── achievements/       # Achievement grid
│   │   ├── notes/              # Knowledge vault
│   │   ├── grokpedia/          # Personal encyclopedia
│   │   ├── digest/             # Weekly digest
│   │   ├── skills/             # Interactive skill map
│   │   ├── settings/           # App settings
│   │   └── api/                # 43 API routes
│   ├── components/             # React components
│   │   ├── dashboard/          # Hero, quests, garden, activity
│   │   ├── learning/           # Tutor chat, quiz, lesson content
│   │   ├── lab/                # Terminal, file browser, session timer
│   │   ├── grokpedia/          # Article reader, knowledge graph, search
│   │   ├── notes/              # Editor, deep search, backlinks
│   │   ├── review/             # Flashcard session, stats
│   │   ├── challenge/          # Challenge session, mode selector
│   │   ├── progress/           # Level card, streak calendar, sparklines
│   │   ├── achievements/       # Achievement grid, progress bars
│   │   ├── skills/             # Metro-style skill map
│   │   ├── layout/             # Sidebar, topbar, mobile nav
│   │   ├── onboarding/         # First-run onboarding flow
│   │   ├── ui/                 # shadcn/ui primitives (badge, card, dialog, etc.)
│   │   └── command-palette.tsx  # Cmd+K global search + quick actions
│   ├── services/               # Deterministic business logic (zero AI calls)
│   │   ├── db/                 # Schema (16 tables), seed, query modules
│   │   ├── gamification/       # XP, levels, streaks, achievements, quests, SM-2
│   │   ├── garden/             # Growth rules, species, calculator
│   │   ├── grokpedia/          # Article queries, FTS, backlinks
│   │   ├── knowledge/          # GitHub/web crawler, deep search
│   │   ├── sandbox/            # OrbStack orchestration, session manager
│   │   ├── notifications/      # Notification creation
│   │   └── vault/              # Obsidian sync
│   ├── lab-templates/          # 8 lab templates (JSON + shell scripts)
│   │   ├── cs/                 # Hello World C, Git Basics
│   │   ├── infrastructure/     # Docker Basics, Nginx Basics
│   │   ├── security/           # File Permissions, SSH Hardening
│   │   └── ai-ml/              # Python Data, Jupyter Notebook
│   └── lib/                    # Shared utilities
│       ├── animations.tsx      # Framer Motion presets
│       ├── markdown.tsx        # Markdown parser & renderer
│       ├── syntax-highlight.tsx # Code block syntax highlighting
│       └── events.ts           # Custom event system
├── server/
│   └── ws-pty.ts               # WebSocket PTY server for lab terminals
├── e2e/                        # Playwright E2E tests (7 spec files)
├── scripts/                    # Utility scripts
├── data/                       # SQLite database (gitignored)
├── drizzle.config.ts           # Drizzle ORM configuration
├── Dockerfile                  # Multi-stage production build
├── docker-compose.yml          # Docker Compose setup
├── fly.toml                    # Fly.io deployment config
└── playwright.config.ts        # E2E test configuration

Database Schema

16 tables covering the full learning lifecycle:

Table	Purpose
`learning_paths`	Curriculum paths with skill trees
`lessons`	Individual lessons with content, objectives, XP rewards
`lab_sessions`	Container sessions with heartbeat, expiry, validation
`progress`	Singleton user progress (XP, level, streak, goals)
`daily_activity`	Per-day metrics (XP, lessons, labs, reviews, minutes)
`achievements`	25 unlockable achievements across 7 categories
`tutor_messages`	SOCRATES conversation history per lesson
`agent_activity`	Agent invocation audit log
`notes`	Knowledge vault with wikilinks, tags, domain, vault sync
`review_items`	SM-2 spaced repetition cards (easiness, interval, reps)
`garden_plants`	Growth Garden plant state per learning path
`challenge_records`	Challenge mode results (score, combo, accuracy)
`notifications`	In-app notification feed (7 types)
`grokpedia_articles`	Encyclopedia articles with confidence scores
`grokpedia_sources`	Article citations (Reddit, SO, HN, DEV.to, GitHub)
`grokpedia_backlinks`	Bidirectional article links via `[[wikilinks]]`

AI Agents

NEXUS uses 5 specialized agents, each with focused tools and structured output schemas validated by Zod.

ATLAS -- Curriculum Architect

Designs personalized learning paths with 8-15 structured lessons, estimated hours, and skill trees. Adapts difficulty based on student level.

Actions: generate_curriculum, adjust_curriculum

SOCRATES -- AI Tutor

Interactive teaching via Socratic method. Maintains conversation history (last 10 messages) and streams responses via Server-Sent Events.

Actions: teach, chat, explain

MINERVA -- Assessment Engine

Generates quizzes, evaluates answers with detailed feedback, and creates spaced-repetition review cards using the SM-2 algorithm.

Actions: quiz, assess, generate_review, validate_lab

LEONARDO -- Research & Visualization

Creates concept diagrams (Mermaid/Excalidraw) and synthesizes research from GitHub repos, documentation, and web sources with a 7-day cache.

Actions: visualize, generate_diagram, research_concept

HERMES -- Deep Search & Knowledge Synthesis

Powers Grokpedia article generation. Performs multi-source deep search (Reddit, HN, SO, DEV.to, GitHub), synthesizes encyclopedic articles with citations, detects wikilinks, and creates backlink graphs.

Actions: deep_search, research, synthesize_article

Agent Execution

All agents are routed through a unified endpoint (POST /api/agents) with action-based dispatch:

POST /api/agents { action, payload }
  -> router.ts (action -> agent mapping)
  -> runner.ts (Claude API call with Zod schema validation)
  -> response { agent, action, data, timestamp }

Mock fallback: When ANTHROPIC_API_KEY is not set, the runner returns realistic mock outputs so the entire app works without an API key.

API Reference

Agents

Method	Endpoint	Description
POST	`/api/agents`	Unified agent router (action + payload)
POST	`/api/agents/stream`	SSE streaming for SOCRATES tutor

Learning

Method	Endpoint	Description
GET	`/api/paths`	List all learning paths
GET	`/api/lessons/[id]/status`	Lesson completion status
POST	`/api/lessons/[id]/complete`	Mark lesson complete

Labs

Method	Endpoint	Description
POST	`/api/sandbox/create`	Create lab container session
GET	`/api/sandbox/status`	Poll container status
POST	`/api/sandbox/exec`	Execute command in container
GET	`/api/sandbox/files`	List container files
POST	`/api/sandbox/files`	Write file to container
GET	`/api/sandbox/resources`	Container resource info
POST	`/api/sandbox/validate`	Run lab validation script
DELETE	`/api/sandbox/destroy`	Terminate container
GET	`/api/labs/active`	List active sessions
POST	`/api/labs/[id]/heartbeat`	Keep session alive
POST	`/api/labs/[id]/extend`	Extend session (30 min)
POST	`/api/labs/[id]/terminate`	End session

Review & Challenge

Method	Endpoint	Description
GET	`/api/review`	Fetch due review items (SM-2)
POST	`/api/review/submit`	Submit review with quality rating
POST	`/api/review/generate`	Generate review cards for topic
POST	`/api/challenge/complete`	Record challenge result

Knowledge

Method	Endpoint	Description
GET	`/api/grokpedia`	List articles (filter by domain/status)
GET	`/api/grokpedia/[slug]`	Single article with sources + backlinks
POST	`/api/grokpedia`	Generate article via HERMES
GET	`/api/grokpedia/search`	Full-text search articles
GET	`/api/grokpedia/graph`	Knowledge graph (nodes + edges)
GET	`/api/search`	Global search (notes, lessons, paths, achievements)
POST	`/api/research`	Research a concept (crawler)
POST	`/api/deep-search`	Multi-source deep research

Notes & Vault

Method	Endpoint	Description
GET	`/api/notes`	List all notes
POST	`/api/notes`	Create note
PUT	`/api/notes/[id]`	Update note
DELETE	`/api/notes/[id]`	Delete note
POST	`/api/vault/sync`	Sync notes to Obsidian vault

Gamification

Method	Endpoint	Description
GET	`/api/quests`	Fetch daily quests
POST	`/api/quests/claim`	Claim quest bonus XP
POST	`/api/goals`	Update daily XP goal
POST	`/api/streak-freeze`	Purchase/use streak freeze
GET	`/api/stats-card`	Shareable stats card

System

Method	Endpoint	Description
GET	`/api/health`	Health check
GET	`/api/me`	Current user context
POST	`/api/settings`	Update settings
POST	`/api/reset`	Reset all progress
GET	`/api/export/progress`	Export progress (JSON)
GET	`/api/export/notes`	Export notes (Markdown)
GET	`/api/notifications`	List notifications
POST	`/api/notifications/read`	Mark notifications read

Deployment

Docker

# Build and run with Docker Compose
docker compose up -d

# Or build manually
docker build -t nexus .
docker run -p 3000:3000 -v nexus-data:/app/data nexus

The Dockerfile uses a multi-stage Alpine build:

deps -- Install dependencies with npm ci
builder -- Build Next.js standalone + seed database
runner -- Minimal Alpine runtime (~150MB image)

SQLite data persists via Docker volume at /app/data.

Fly.io

# Deploy to Fly.io
fly launch
fly deploy

# Create persistent volume for SQLite
fly volumes create nexus_data --size 1 --region sjc

Configuration in fly.toml: 512MB RAM, 1 shared CPU, HTTPS with auto-TLS.

Lab Templates

Template	Domain	Difficulty	Duration	Description
Hello World C	CS	1	20 min	Write, compile, run, and modify a C program
Git Basics	CS	2	30 min	Init, commit, branch, and push with Git
Docker Basics	Infrastructure	2	30 min	Pull images, run containers, build custom images
Nginx Basics	Infrastructure	2	25 min	Configure and deploy Nginx web server
File Permissions	Security	1	15 min	Linux chmod, chown, and umask
SSH Hardening	Security	3	45 min	SSH key generation and server hardening
Python Data	AI/ML	2	35 min	Pandas and NumPy data analysis
Jupyter Notebook	AI/ML	2	40 min	Jupyter setup and Python visualization

Each template includes template.json (metadata + objectives), provision.sh (container setup), validate.sh (objective checking), and seed files.

E2E Tests

Playwright test suite with 7 spec files:

# Install Playwright browsers (first time)
npx playwright install

# Run all tests
npm run test:e2e

# Run specific test
npx playwright test e2e/dashboard.spec.ts

# Run with UI mode
npx playwright test --ui

Spec	Coverage
`dashboard.spec.ts`	Hero section, XP ring, quick actions, daily quests
`learn.spec.ts`	Path browsing, lesson launch, tutor interaction
`review.spec.ts`	Review session, SM-2 scheduling
`challenge.spec.ts`	Challenge modes, scoring, combos
`notes.spec.ts`	Note CRUD, markdown editing, deep search
`navigation.spec.ts`	Global navigation, command palette, shortcuts
`api.spec.ts`	API route integration tests

Keyboard Shortcuts

Shortcut	Action
`Cmd+K` / `Ctrl+K`	Open command palette
`?`	Open keyboard shortcuts modal
`1-9`	Navigate to Dashboard/Learn/Labs/Progress/Review/Achievements/Notes/Digest/Challenge

License

MIT

Built with Claude • Next.js • React • Tailwind • SQLite

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
e2e		e2e
public		public
scripts		scripts
server		server
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
components.json		components.json
docker-compose.yml		docker-compose.yml
drizzle.config.ts		drizzle.config.ts
eslint.config.mjs		eslint.config.mjs
fly.toml		fly.toml
next-env.d.ts		next-env.d.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
postcss.config.mjs		postcss.config.mjs
setup-nexus.sh		setup-nexus.sh
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

NEXUS

Features

Learning & AI Tutoring

Hands-On Labs

Knowledge System

Notes & Vault

Gamification

Spaced Repetition

UI/UX

Screenshots

Getting Started

Prerequisites

Installation

Development Scripts

Environment Variables

Architecture

Tech Stack

Project Structure

Database Schema

AI Agents

ATLAS -- Curriculum Architect

SOCRATES -- AI Tutor

MINERVA -- Assessment Engine

LEONARDO -- Research & Visualization

HERMES -- Deep Search & Knowledge Synthesis

Agent Execution

API Reference

Agents

Learning

Labs

Review & Challenge

Knowledge

Notes & Vault

Gamification

System

Deployment

Docker

Fly.io

Lab Templates

E2E Tests

Keyboard Shortcuts

License

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages