Pseudogen
Algorithm visualization and pseudocode development environment. A React PWA with six interconnected modes for writing, visualizing, and learning pseudocode and algorithms. Currently in staging as a graduation candidate for apps/.
Overview
Pseudogen provides a multi-mode interface for pseudocode authoring and algorithm exploration:
- Editor — CodeMirror 6-based pseudocode editor with custom syntax highlighting and document management
- Flowchart — ReactFlow canvas with bidirectional pseudocode-to-flowchart conversion via a stack-based nesting parser
- Algorithms — Library of teaching algorithms with a visualization framework
- Narrative — Interactive adventure-based guided code generation using YAML-defined story graphs
- Templates — Reusable pseudocode templates with variable substitution
- Analysis — Complexity analysis engine with pattern detection and Big-O estimation
All data persists client-side via AP Ecosystem standards using IndexedDB (Dexie), with Zustand stores and temporal middleware (Zundo) for undo/redo. See AI & Agents for context on the narrative engine’s agent-like directed-graph traversal.
Tech Stack
| Technology | Purpose |
|---|---|
| React 19 + TypeScript 5.9 | UI framework (strict mode) |
| Vite 7 | Build tool + dev server |
| CodeMirror 6 | Pseudocode editor with custom language |
| ReactFlow 11 | Node-based flowchart editor |
| Zustand 5 + Zundo 2 | State management + undo/redo |
| Dexie 4 | IndexedDB persistence (50MB+ capacity) |
| Tailwind CSS 4 + Radix UI | Styling + accessible components |
| Vitest + Playwright | Unit/integration + E2E testing |
| vite-plugin-pwa + Workbox | Offline-first PWA support |
Key Architectural Decisions
- Stack-based nesting parser — Regex parsing failed on nested control structures (IF inside FOR). Custom 430-line parser with proper scope tracking handles arbitrary nesting depth.
- Feature-based Zustand stores — One store per feature with persist middleware. Prevents store bloat, enables per-feature data migration.
- Middleware order matters —
temporal(persist(...))works;persist(temporal(...))breaks undo/redo. Zustand middleware composition is order-sensitive. - IndexedDB over localStorage — Migrated after users with 20+ documents hit the 5-10MB localStorage cap. Dexie provides 50MB+ with async operations.
- Adventures extracted to YAML — Hard-coded 580-line adventure definitions moved to separate YAML files for content editing without code changes.
Health
| Metric | Status |
|---|---|
| Tests | 720 passing across 36 test files |
| TypeScript | 0 errors (strict mode) |
| Coverage | 42% overall, critical paths 82-100% |
| Dependencies | Current (React 19, Vite 7) |
| CI/CD | Not configured |
| Phase | Staging — graduation candidate |
Lessons Learned
- Test coverage metrics misleading for UI-heavy apps — 42% overall looks poor but critical business logic at 82-100%. Focus testing on pure functions and state logic.
- CodeMirror keyword order critical — “ELSE IF” matched as “ELSE” + “IF” when not sorted longest-first.
- Complexity analysis needs debouncing — running on every keystroke caused UI freezes with large code blocks (500ms debounce + useMemo).
- localStorage size limits bite when users accumulate 20+ documents — migrate to IndexedDB early.
- Template variable regex using
new RegExp(variableName)without escaping breaks on special characters.
See Also
- narrative-engine — Pseudogen’s adventure engine was one of three structurally identical models that led to narrative-engine extraction
- forge — Another consumer of the narrative-engine shared library
- BardFill — Shakespearean lorem ipsum generator; another staging-zone PWA with REST API