Forge

Developer Learning Platform — interactive coding tutorials delivered as narrative adventures with AI tutoring. First app in Phase 2 Wave A. Validates narrative-engine and eliza-engine under real load.

Overview

Forge provides interactive, branching coding tutorials guided by a Socratic AI tutor persona. Tutorials are modeled as narrative graphs: each node is a lesson step, branches represent choices, and the tutor provides hints without giving away answers. Core modules: TutorialRunner, QuizEngine, ProgressTracker, TutorAssistant.

Tech Stack

Technology	Version	Purpose
React	19	UI framework
TypeScript	5.6+	Type safety (strict mode)
Vite	7.3+	Build tool / dev server
Vitest	4.0+	Test runner
@ap/narrative-engine	workspace:*	Tutorial graph navigation and branching
@ap/eliza-engine	workspace:*	Tutor persona conversational AI

Port: 3120

Current Status

Phase: Active Development (v0.1) — last updated 2026-02-15

• React UI built with 4 views: Tutorial, Quiz, Progress, Tutor Chat
• 19 tests passing; test coverage 70%+
• Core logic modules complete; UI wiring not yet done
• CI/CD not yet deployed; no current blockers

Next cycle priorities:

1. Build React UI components for tutorial navigation
2. Create sample tutorial content (TypeScript fundamentals)
3. Wire up TutorAssistant persona responses
4. Add Dexie persistence layer for progress

Key Decisions

Decision	Rationale
React 19 + TypeScript + Vite	Matches source apps (pseudogen, gw, jp web) for pattern consistency
@ap/narrative-engine for tutorial graphs	Tutorials are branching narratives — exact fit for the narrative engine
@ap/eliza-engine for tutor persona	Socratic hints via pattern matching, no cloud AI dependency
TutorialRunner wraps NarrativeEngine	Adds learning-specific concerns (quiz tracking, progress) without modifying the shared package
Immutable progress updates	All ProgressTracker functions return new objects — simpler state management, undo-friendly
Difficulty auto-promotion/demotion	From jp Academy pattern — 80% threshold promotes, 40% demotes, minimum 3 attempts

Patterns

• NarrativeEngine wrapper pattern — TutorialRunner adds domain logic around @ap/narrative-engine. Any domain can wrap the narrative engine this way.
• Immutable progress tracker — Pure functions returning new state. Works with React state, Redux, or any immutable store.
• QuizEngine state machine — Question → Submit → Next loop with scoring. Self-contained, no dependencies.

Lessons Learned

• NarrativeEngine.processChoice takes a NarrativeChoice object, not a string ID — required adding choice lookup in TutorialRunner. Always read shared package API before wrapping.
• NarrativeEngine.toSession requires a sessionId parameter — wrapper must track sessionId.
• NarrativeEngine.getCurrentNode takes a nodeId parameter — the engine is stateless for current position; the wrapper adds that state.

See Also

• narrative-engine — shared library providing tutorial graph navigation
• eliza-engine — shared library providing Socratic tutor persona
• narrativeengine-wrapper-pattern — reusable pattern for wrapping the narrative engine in domain-specific logic
• ComposeFlow — another TypeScript/React app in staging following the same compliance path