Skip to content

PhonoLex 4.0.0 Release Design

Date: 2026-03-10 Status: Approved

What 4.0.0 Means

Coming out of beta. This release represents:

  • Architecture maturity — Hono/D1 rewrite is production, not experimental
  • Modern stack — React 19, MUI 7, Vite 7, ESLint 9, Vitest 4
  • Discoverable — static landing pages targeting SLP search terms, proper SEO
  • Professional — no donation widget, clean copy, proper documentation
  • Tested — baseline API tests, CI that means something
  • Maintained — Dependabot, .nvmrc, engine fields

Branch Strategy

develop
  └── release/4.0.0
        ├── cleanup/claude-md-roleplay     ← DONE
        ├── deps/react-mui-vite
        ├── deps/eslint-vitest
        ├── docs/4.0
        └── seo/landing-pages

Each sub-branch merges into release/4.0.0 via PR. When all are green, release/4.0.0 merges to main with a v4.0.0 tag.

Work Packages

1. cleanup/claude-md-roleplay (DONE)

  • CLAUDE.md rewritten (~445 lines to ~130)
  • Version bumped to 4.0.0 across all packages (3 package.json + pyproject.toml + README + CHANGELOG)
  • License fixed in python/pyproject.toml (MIT to CC-BY-SA-3.0)
  • Added .nvmrc (Node 20, matches CI)
  • Relocated config.py from webapp/backend/ to workers/scripts/
  • Deleted legacy FastAPI backend (webapp/backend/)
  • Deleted dead scripts (scripts/), orphaned embeddings (embeddings/phase2/), archive/
  • Deleted Docker artifacts (docker-compose.yml, Dockerfile, nginx.conf)
  • Removed unused frontend deps (zustand, recharts, jsdom, @testing-library/user-event)
  • Cleaned frontend copy: "cognitive graph" replaced with user-facing language
  • Updated CORS: .netlify.app to .pages.dev

2. deps/react-mui-vite

  • React 18 to 19, react-dom 18 to 19
  • MUI 5 to 7 (theming, Grid, component API breaking changes)
  • Vite 5 to 7, @vitejs/plugin-react update
  • Fix all breaking changes
  • Verify: build, type-check, all 5 tools render correctly

3. deps/eslint-vitest

  • ESLint 8 to 9 with flat config (eslint.config.js replacing .eslintrc.cjs)
  • @typescript-eslint 6 to 8
  • Vitest 3 to 4, @cloudflare/vitest-pool-workers 0.8 to 0.12
  • Write baseline API tests for workers/:
  • Health endpoint
  • Word lookup
  • Word search with filters
  • Similarity search
  • Enough that npm test means something

4. docs/4.0

  • New "Data & Methods" page (docs/reference/data-and-methods.md):
  • 18 datasets explained in plain language with full citations
  • Similarity algorithm explained for researchers (not devs)
  • Clinical research foundations (Gierut, Storkel) for contrastive tools
  • Property categories: what they measure and why an SLP would care
  • Delete 3 stale technical docs:
  • docs/VOCABULARY_FILTERING.md
  • docs/MAXIMAL_OPPOSITION_TOOL.md
  • docs/CONTRASTIVE_INTERVENTION_UNIFIED_ARCHITECTURE.md
  • Clean docs/technical/architecture.md: remove "cognitive graph" language, update version refs
  • Clean docs/index.md: remove "cognitive graph" reference
  • Update mkdocs.yml nav

5. seo/landing-pages

  • Remove Ko-fi widget from index.html (70 lines inline CSS/JS/iframe)
  • Static landing pages targeting SLP search terms:
  • "Minimal Pairs Generator" — links to Contrastive Sets tool
  • "SLP Word List Generator" — links to Custom Word Lists tool
  • "Phonological Therapy Materials" — overview linking to all tools
  • Each page: prerendered HTML, proper meta tags, internal links to the SPA
  • Fix sitemap: add landing page URLs, update lastmod dates
  • Fix JSON-LD: version to 4.0.0
  • Add "engines": {"node": ">=20"} to package.json files
  • Add .github/dependabot.yml for automated weekly dep PRs

Decisions Made

Decision Rationale
Delete stale technical docs (not update) User guides already cite the research; design docs are artifacts of a backend that no longer exists
Do React/MUI/Vite migration in 4.0.0 Major version is when you break deps; nobody is waiting on a release
Separate "Data & Methods" from "Architecture" Users/researchers need accessible explanation; devs need implementation details
Static landing pages over SSR migration Highest ROI for discoverability without rebuilding the frontend
Remove Ko-fi entirely Moving toward professional nonprofit model, not donation-based
Sub-branches into release branch Isolates MUI 7 breakage from doc/SEO changes