Evolver
Tools
What worked
Three full milestones in 16 days (v1.0 → v1.3), including 236 commits in the 8 days of v1.3 polish alone. Claude Code built two very different panel architectures — inline JSX for the Evolver (110 controls, unique UI elements like LCD and sequencer LEDs) and a data-driven render loop for Cascadia (179 controls with bezier cable routing that droops realistically with distance). The dual-mode content pattern (local Obsidian vault for real use, bundled for Vercel demo) worked the first time. SysEx capture/send/diff via Web MIDI API for the Evolver landed cleanly.
What broke
Audio recording infrastructure has slipped past v1.3 — sessions reference audio examples but there's no capture path yet. The panels are large (34KB Evolver, 42KB Cascadia inline SVG) because control definitions are hand-placed. Mobile is partial: v1.3 added responsive shells but panels still render at 1800px viewBox with no touch-optimized interactions. Reference PDFs must be user-supplied — Vercel deploy breaks unless bundled manually. The framework-as-product hypothesis is only validated across two synths; no third yet.
Roles
I wrote the framework — the ADHD design principles (zero activation energy, dopamine-by-design, sequence-not-calendar), the 15-30 minute session hard limit, the philosophy that missed days should create no guilt. I authored the 35 Evolver sessions and 25 Cascadia sessions as content. Claude Code wrote the Next.js app, the Zod schemas with .passthrough() tolerance for Obsidian metadata, the panel components, and the MIDI code. The decision to codify the framework in-repo (instead of a separate theory doc) was mine — single source of truth for methodology.
Evolver (Instrument Mastery System)
Overview
Evolver is an ADHD-friendly structured learning system for deeply mastering electronic synthesizers and instruments. It combines a reusable pedagogical framework, instrument-specific curricula (60 sessions across 2 instruments), and a Next.js web app with interactive SVG panel visualizations, MIDI integration, and Obsidian vault-backed content.
Core purpose: Turn "I bought this synth but never got deep with it" into fluent compositional use through 15-30 minute micro-sessions with tangible output (documented patches, technique guides, audio examples).
Target users: Electronic musicians with ADHD who own synthesizers but struggle to progress beyond surface-level exploration.
Key Features
Curriculum & Framework:
- 35-session Dave Smith Mono Evolver curriculum (10 modules: Foundations -> Analog Osc -> Digital Osc -> Filters -> Modulation -> Effects -> Sequencer -> Sound Design -> Performance -> Integration)
- 25-session Intellijel Cascadia curriculum (7 modules, semi-modular/CV-focused)
- Reusable instrument-agnostic framework with ADHD design principles codified (zero activation energy, dopamine-by-design outputs, sequence-based progression)
- 15-30 minute session hard limit — Consistency over intensity; no guilt-inducing calendars or streaks
Web Application:
- Interactive SVG panel visualizations — Evolver (110 controls, inline JSX) and Cascadia (179 controls, data-driven with cable routing)
- Session detail view — Markdown rendering with embedded panel parameter highlights
- Patch library — Documented patches with full parameter values, cable routing diagrams (Cascadia)
- MIDI workspace (Evolver only) — Web MIDI API for SysEx capture, send, diff, and parameter extraction
- Progress dashboard — Module journey tracking, completion metrics, count cards
- Dual-mode architecture — Local Obsidian vault for real use; bundled content for Vercel demo deployment
Content & Data:
- Obsidian-flavored markdown — Wikilinks, callouts, Mermaid diagrams, code blocks rendered natively
- Zod-validated content schemas — Sessions, patches, instruments validated with
.passthrough()for Obsidian metadata tolerance - 39 documented patches (16 Evolver + 23 Cascadia) with full parameter values and categories
Architecture
Tech Stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 15.5 + React 19 + Tailwind CSS 4 |
| Content | gray-matter + remark 11 + rehype 11 (Obsidian-flavored pipeline) |
| Validation | Zod 3.23 |
| MIDI | Web MIDI API (SysEx capture/send/diff) |
| Diagrams | Mermaid 11.13 |
| Icons | Lucide 1.7 |
| Testing | Vitest 3.0 + @testing-library/react 16.3 |
| Deployment | Vercel (demo mode) |
| Data Source | Obsidian vault (~/song) with bundled fallback |
Structure
framework/ # Reusable learning methodology (instrument-agnostic)
README.md # Framework overview & principles
adhd-design.md # ADHD design principles & guardrails
curriculum-authoring-guide.md
instruments/ # Per-instrument data
evolver/ # Overview, signal flow, modules, basic patch, instrument.json
cascadia/ # Overview, signal flow, ~20 module docs, instrument.json
sessions/ # Structured learning curriculum
evolver/ # 35 sessions (complete)
cascadia/ # 25 sessions (complete)
patches/ # Documented patches with full parameter values
evolver/ # 16+ patches
cascadia/ # 23 patches (bass/lead/pad/drum/texture/FX)
src/
app/ # Next.js App Router pages
instruments/[slug]/ # Overview, sessions, patches, modules, panel, midi, progress
components/ # 45+ React components
evolver-panel.tsx # ~34KB inline SVG (110 controls)
cascadia-panel.tsx # ~42KB data-driven SVG (179 controls, cable rendering)
session-detail.tsx # Markdown rendering + panel integration
midi-page.tsx # SysEx capture/send/diff
lib/
content/ # Vault reader + bundled fallback + Zod schemas
midi/ # SysEx parser, encoder, NRPN parameter map
markdown/ # Unified rendering pipeline (rehype-mermaid, wikilinks, callouts)
evolver-panel-data.ts # 110 control metadata (name, NRPN, section)
cascadia-panel-data.ts # 179 control metadata + cable lookup
content/ # Bundled content for demo/Vercel deployment
references/ # 6 reference PDFs (manuals, guides, patch books)
scripts/
bundle-content.ts # Vault -> src/content/ copy for build
validate-content.ts # Schema validation
Key Patterns
- Dual-mode content — Local vault path (evolver.config.json) for real use; bundled
src/content/for Vercel demo. Same reader code path, different data sources. - Two panel architectures — Evolver: inline JSX SVG with
K()helper per control (unique UI elements like LCD, sequencer LEDs). Cascadia: data-driven generic render loop overCONTROL_METADATA(highly modular, cable rendering via bezier curves with realistic droop). - SysEx as JSON sidecar — MIDI data stored as structured JSON alongside markdown; keeps markdown human-readable.
- Obsidian-flavored rendering — Full pipeline: gray-matter -> Zod validation -> remark/rehype with wikilinks, callouts, Mermaid, syntax highlighting.
- Sequence-based progression — No calendar, no streaks. Sessions are numbered, not dated. Skipping creates no guilt. ADHD-first design principle.
Development History
v1.0 – v1.3 shipped between March 29 and April 13, 2026. Three full milestones in 16 days.
| Milestone | Phases | Focus |
|---|---|---|
| v1.0 | 1-6 | Content pipeline, 35 Evolver sessions, patch library, MIDI workspace, progress dashboard, Vercel deploy |
| v1.1 | 7-13.1 | Cascadia curriculum (25 sessions), Cascadia panel visualizer (179 controls, cable rendering), demo mode |
| v1.2 | 14-17 | Learner state persistence (Zustand + vault scanning), navigation enhancements (resume bar, prerequisites, module journey markers), global search + patch filter UI, troubleshooting guides. Shipped Apr 7, 2026 |
| v1.3 | 18-24 | Visual redesign: OKLCH token palette, @tailwindcss/typography prose rendering, responsive page shells, unified card system, motion micro-interactions (motion@^12.38.0), panel zoom animations, practice heatmap (Monday-aligned calendar grid), per-instrument color identity (Evolver blue, Cascadia aluminum), ADHD-5-second-test acceptance criterion. 7 phases, 236 commits in 8 days |
v1.0 shipped March 30, 2026. v1.2 shipped April 7. v1.3 completed April 13 (in verification). Content volume stable: 37 Evolver + 27 Cascadia sessions, 24 patches.
Architectural Decisions
| Decision | Rationale |
|---|---|
| Obsidian vault as source of truth | Matches PM Toolkit pattern; portable, version-controlled, learner owns data |
| 15-30 min session hard limit | ADHD constraint — consistency over intensity prevents burnout |
| Sequence-based not calendar-based | Missed dates create guilt spirals; sequence eliminates pressure |
| Two panel architectures (JSX vs data-driven) | Evolver has unique UI elements (LCD, LEDs); Cascadia is modular enough for generic rendering |
| Cable rendering via bezier SVG | Pedagogical — learners see exactly which jacks to connect; droop scales with distance |
| Zod with .passthrough() | Strict on known fields, permissive on extras (Obsidian-added metadata) |
| Demo mode with bundled content | Share curriculum publicly without exposing personal practice data |
| Framework in-repo | Single source of truth for methodology; ships with curriculum |
Strengths
- Pedagogical rigor — Framework grounded in learning science (spaced repetition, isolation-before-integration, micro-sessions); ADHD design principles codified and non-negotiable
- Multi-instrument extensibility validated — Adding Cascadia proved the framework is reusable; clear pattern for any electronic instrument
- Content as code — All curriculum is markdown + YAML, version-controlled, shareable, no proprietary CMS
- Rich interactive panels — SVG visualization of hardware panels makes patching intuitive; Cascadia cable routing shows exact physical connections
- MIDI integration — SysEx capture/send/diff for Evolver makes hardware interaction visible and learnable
- Tangible output per session — Every session produces documented patches; exportable, shareable, composable
- Obsidian-native rendering — Wikilinks, callouts, Mermaid diagrams render without translation
Weaknesses & Risks
- Audio recording still deferred — Sessions reference audio examples but recording infrastructure has slipped past v1.3;
audio_previewfield still empty - Panel component size — Cascadia panel (42KB) and Evolver panel (34KB) still large due to inline control definitions
- Mobile still partial — v1.3 added hamburger nav and NarrowShell/WideShell responsive shells, but panels still render at 1800px viewBox (no touch-optimized interactions)
- Reference PDFs must be user-supplied — Works locally but breaks on Vercel unless manually bundled
- Panel authoring is labor-intensive — Each new instrument requires hand-placing ~100+ controls; no algorithmic layout
- No third instrument yet — Framework reusability was validated by Cascadia, but the 8 days of v1.3 went into polish instead of breadth. The framework-as-product hypothesis remains untested beyond two synths
Resolved since the v1.1 profile: learner state persistence, search/filtering, and troubleshooting guides all shipped in v1.2.
Connection to Other Projects
- PM Toolkit — Vault reader pattern inherited (Obsidian -> app, server components, Zod schemas)
- Haven — Shares ADHD-adapted design approach (session scripts, timed steps, sensory engagement, quick wins)
- Etyde — Both in music domain; complementary (learning instruments vs. learning music theory/practice)
- AbletonBuddy — Both in music production domain; complementary (learning synthesis vs. songwriting/arrangement)
- No infrastructure connections — No Roughneck, CNC, Ollama, or WireGuard dependencies; self-contained
What Makes This Project Different
Evolver is the portfolio's deepest exploration of:
- Pedagogical design — A reusable learning framework codified from scratch, validated across two instruments
- ADHD-first product design — Not retrofitted accessibility but fundamental design constraints (session length, sequence not calendar, zero activation energy, dopamine by design)
- Physical-digital bridge — Interactive SVG panels represent real hardware; MIDI SysEx connects software to physical synthesizer
- Content volume — 65K+ lines of curriculum markdown; the content IS the product, not the code
- Domain passion — This is not a tool built for others; it's a system for the developer's own deep practice, which makes the design decisions intensely personal and well-informed