LearnWorld

Inspiration

Many computer science topics feel abstract and difficult to grasp when presented on static slides or textbook pages. Students struggle to build a mental model of how pointer manipulation, recursion call stacks, or complex tree balancing actually execute step-by-step. While generic tutoring chatbots can explain concepts, they lack context of the specific diagram, code state, or custom input a student is working with.

We wanted to build a "playable textbook" where every CS concept becomes a dynamic playground with a built-in AI tutor looking at the exact same execution state as the student.

What it does

LearnWorld is a local-first, gamified computer science education platform featuring:

• Interactive CS1/CS2 Curriculum: A library of 32 core computer science skills (pointers, dynamic memory allocation, trees, Skip Lists, Big-O analysis, Greedy algorithms, Trie traversal, and DP) mapped in a prerequisite graph.
• Multi-topic Learning Quests: Students can assemble custom learning quests by picking topics. Quests track progress, reward XP, levels, streaks, and achievements locally.
• Deterministic Simulation Engines: Every skill features a custom TypeScript simulation engine where users can change input values, step forward/backward, inspect variables/memory/heaps in real-time, and run branch-decision points.
• AI Custom Workshop: Students can ingest textbook PDFs or lecture notes. LearnWorld parses it securely using Gemini via structured schemas, transforming it into a Zod-validated custom curriculum item complete with interactive simulations, with zero generated executable code.
• State-aware AI Tutoring: Grounded Gemini AI chat that understands the precise simulation inputs and step-by-step states of the user's screen to provide guided, zero-hallucination tutoring.

How we built it

• Framework & Runtime: Built with Next.js 15, React 19, and TypeScript.
• Visual Simulations: Leveraged Cytoscape.js for interactive tree/graph layouts, along with responsive CSS layouts for dynamic call stacks, arrays, memory/heap grids, and skip lists.
• AI Ingestion & Tutoring: Integrated Google Gemini via the @google/genai SDK. We used schema-constrained JSON structures (structured outputs via Zod) to ingest raw text and PDFs into curriculum items securely.
• Local Database: IndexedDB (using the idb library) for robust, local-first storage of levels, XP, lesson history, custom imported skills, and achievements with full import/export functionality.
• Quality & Verification: Verified using a rigorous suite of unit tests via Vitest and end-to-end user path tests with accessibility checks (Axe Builder) using Playwright.

Challenges we ran into

• Authentic TypeScript Engines: Building 30+ custom, deterministic logic engines (like Skip Lists, AVL balance, dynamic memory allocators, and backtracking trace trees) that can step forward and backward seamlessly without using simple mock-ups was a massive engineering undertaking.
• Safe Dynamic Material Ingestion: LLMs can easily produce unpredictable structures. We solved this by using strict Zod schema validation combined with Gemini's structured output settings, guaranteeing that the ingested material has a valid interactive layout, custom objectives, and correct question metadata without running any untrusted executable scripts.
• Next.js Dev Server Resource Contention in E2E: Parallel Playwright testing on a cold dev server often ran into timeouts because compiling dynamic React routes under multi-core load exceeded standard limits. We resolved this by adding custom timeout strategies for cold page loading.

Accomplishments that we're proud of

• Completeness: 32 fully interactive simulation engines implementing authentic algorithms (no mock data!) with complete state tracking (steps, events, environment heaps/stacks).
• 100% Client-Side Gamification: Built a fast, reactive leveling and XP progression system that is completely offline-first, offering high privacy and snappy performance.
• State-Awareness: Providing the Gemini tutor with a structured JSON snapshot of the active step, variables, and history so it acts like a true companion who is pointing at your screen rather than guessing.
• Accessibility: 100% clean integration of accessibility checks in automated tests, ensuring high contrast, clean headings, and proper aria labels.

What we learned

• Schema validation at the API boundary is the key to building robust AI-driven features. Zod schemas kept our custom workshop perfectly typed and safe.
• Splitting complex simulation steps into deterministic state snapshots makes time-travel debugging (stepping back/forward) trivial to implement and test.
• Local-first architecture (via IndexedDB) combined with JSON backup-import is extremely liberating, avoiding database setup while providing instant page loads.

What's next for LearnWorld

• Collaborative Quests: Synchronizing local learning states between study groups or classrooms using peer-to-peer WebRTC.
• Extended Algorithm Visualizer SDK: Creating a community catalog where students can write their own custom simulation engines.
• Speech-to-Speech Tutoring: Integrating Gemini Live API to let students voice-chat with their tutor while manipulating algorithms.

Built With

• css
• cytoscape.js
• google-gemini-api
• indexeddb
• next.js
• playwright
• react
• tailwind-css
• typescript
• vitest
• zod