emba-course-solver/openspec/changes/emba-specialization-solver/design.md

Context

Greenfield React web application. No existing code, backend, or infrastructure. The complete problem domain is documented in SPECIALIZATION_EVALUATION.md: 46 courses across 12 elective sets, 14 specializations, a course-specialization qualification matrix with special markers (■/S1/S2), required course gates, and a credit non-duplication constraint that makes this an optimization problem rather than simple counting.

The application runs entirely client-side. All data is embedded as static constants. The solver must be fast enough for instant feedback on every user interaction.

Goals / Non-Goals

Goals:

• Exact optimal credit allocation (LP-based, not heuristic)
• Sub-second recalculation on any user interaction (rank change, pin, mode switch)
• Clear visibility into trade-offs: what each open-set decision enables or eliminates
• Works on modern browsers, no install or backend required

Non-Goals:

• Multi-user features, persistence, or accounts (local-only tool)
• Supporting arbitrary program structures (hardcoded to J27 EMBA curriculum)
• Mobile-optimized layout (desktop-first, functional on tablet)
• Printing or export

Decisions

1. Project Tooling: Vite + React + TypeScript

Choice: Vite with React and TypeScript.

Why: Vite provides fast dev server and optimized builds. TypeScript catches data model errors at compile time — critical when the course-specialization matrix has ~100 entries that must be correct. No SSR needed since this is a static client-side tool.

Alternatives considered:

• Create React App: deprecated, slower builds
• Next.js: overkill for a single-page client-only tool

2. LP Solver: javascript-lp-solver

Choice: javascript-lp-solver — a pure JavaScript simplex implementation.

Why: The LP instances are tiny (~168 variables, ~26 constraints). This library is dependency-free, runs synchronously, and solves each instance in microseconds. No WASM compilation step or async loading. The API accepts a JSON model definition, which maps cleanly to our problem structure.

Alternatives considered:

• glpk.js (WASM GLPK port): more powerful, but WASM loading adds complexity for no benefit at this problem size
• Custom simplex: less maintenance burden on a library, but reinventing a solved problem
• No LP solver (combinatorial): credit splitting makes pure combinatorial approaches awkward; LP handles fractional allocation naturally

3. Optimization Architecture: Subset Enumeration + LP Feasibility

Both optimization modes share a common primitive: given a fixed set of selected courses and a target set of specializations, is there a feasible credit allocation where every target spec reaches 9 credits?

This is a small LP:

• Variables: x[course][spec] = credits allocated from course to spec
• Constraints: Σ_spec x[c][s] ≤ 2.5 for each course, Σ_course x[c][s] ≥ 9 for each target spec, x[c][s] = 0 where course doesn't qualify, x ≥ 0
• Strategy S2: at most one S2-marked course has x[c][strategy] > 0

The two modes differ only in how they search for the best feasible target set:

Maximize Count mode:

1. Pre-filter: remove specs missing required courses → get candidate list
2. For n = 3 down to 0, enumerate C(candidates, n) subsets
3. For each subset, check LP feasibility (with S2 enumeration for Strategy)
4. Among feasible subsets of the max size, pick the one with best priority score: Σ (15 - rank[spec])
5. Return first feasible size found

Priority Order mode:

1. Pre-filter same as above
2. Start with achieved = []
3. For each spec in priority order: check if {achieved ∪ spec} is LP-feasible
4. If yes, add to achieved; if no, skip
5. At most 14 feasibility checks (one per spec)

S2 enumeration: When Strategy is in the target set, enumerate which S2 course (if any) counts. With typically 0-3 S2 courses selected, this adds at most 4 LP solves per subset check.

Performance for fixed courses: Max count mode worst case: C(14,3) + C(14,2) + C(14,1) = 469 subsets × ~4 S2 options = ~1,876 LP solves. Each LP takes microseconds. Total: < 20ms.

4. Decision Tree: Per-Choice Impact Analysis

For open (unpinned) sets, the user needs to understand: "what does picking this course change?"

Approach: For each open set, for each course choice in that set:

1. Temporarily pin that course
2. Compute the ceiling — best achievable outcome assuming all other open sets are chosen optimally
3. Report: ceiling specialization count, which specs become achievable/unreachable vs. current state

Ceiling computation requires enumerating remaining open-set combinations. Cost: for each choice being evaluated, enumerate 4^(open-1) remaining combos, each running the subset enumeration.

Open sets	Combos per choice	× 4 choices × sets	Total optimizations
2	4	32	32
4	64	1,024	1,024
6	1,024	24,576	24,576
8	4,096	131,072	131,072
10	65,536	2,621,440	too many

At 6+ open sets, full enumeration becomes expensive (seconds). Solution:

Tiered computation:

• Instant (main thread): upper-bound reachability per spec using credit counting (ignores sharing). Runs on every interaction. Shows achievable/unreachable status.
• Fast (main thread): LP optimization on pinned courses only. Shows guaranteed achievements.
• Background (Web Worker): full decision tree enumeration. Runs after user interaction settles (debounced ~300ms). Progressively updates the UI as results arrive per open set.

Early termination: when computing ceilings, if we find a 3-spec feasible subset for a choice, we know the ceiling is 3 (the max) and can skip remaining combos for that choice.

Impact ordering: open sets are ranked by decision impact = variance in ceiling outcomes across their course choices. A set where all courses lead to the same outcome is "low impact." A set where one course enables 3 specs and another only 2 is "high impact." High-impact sets are shown first.

5. State Management: useReducer with Derived State

Choice: Single useReducer for user inputs, with derived computation results via useMemo.

State (persisted to localStorage):
├── specialization ranking: number[]  (ordered spec IDs)
├── optimization mode: 'maximize-count' | 'priority-order'
└── pinned courses: Map<SetId, CourseId | null>

Derived (computed):
├── optimization result (from LP solver)
├── per-spec status + credit allocation
└── decision tree (from Web Worker)

Why not Redux/Zustand: Only three pieces of user state. A reducer handles the interactions (reorder, pin, toggle mode) cleanly without external dependencies.

6. Drag-and-Drop: @dnd-kit

Choice: @dnd-kit/core + @dnd-kit/sortable for specialization ranking.

Why: Modern, accessible (keyboard support), lightweight, well-maintained. The only drag-and-drop in the app is reordering a 14-item list.

Alternatives considered:

• react-beautiful-dnd: deprecated by Atlassian
• HTML5 drag-and-drop API: poor accessibility, inconsistent browser behavior

8. UI Verification: agent-browser

Choice: agent-browser (Vercel Labs) for interactive UI verification during development.

Why: The interesting behavior in this app is visual — credit allocations, status transitions, decision tree structure. Unit tests cover the optimizer, but verifying the UI wires everything together correctly requires interacting with the running app. agent-browser is a headless browser CLI designed for AI agents: it produces accessibility tree snapshots with semantic element references (@e1, @e2) that are easy to reason about programmatically, and supports click, fill, drag, and screenshot commands.

How it's used: During implementation, after building each UI component group, launch the Vite dev server and use agent-browser to:

1. Take accessibility tree snapshots to verify rendered structure (14 specializations listed, 12 elective sets grouped by term, status badges present)
2. Interact with the UI (drag to reorder, click to pin courses, toggle optimization mode)
3. Snapshot again to verify results updated correctly
4. Take screenshots for visual confirmation of layout and styling

This is interactive verification, not a repeatable test suite. It complements vitest unit tests (which cover data integrity and optimizer correctness) by catching UI wiring issues — wrong props, missing state connections, broken drag-and-drop — that unit tests cannot.

Alternatives considered:

• Playwright: more mature, better for repeatable e2e test suites, but overkill for this project's size. The app is small enough that interactive verification + unit tests cover the risk.
• Manual browser testing: works but slower and less systematic than scripted agent-browser commands.

9. Data Embedding: Typed Constants Module

The course-specialization matrix is embedded as a TypeScript module (src/data/) exporting typed constants:

• COURSES: array of { id, name, setId, specializations: { specId: '■' | 'S1' | 'S2' }[] }
• ELECTIVE_SETS: array of { id, name, term, courseIds }
• SPECIALIZATIONS: array of { id, name, abbreviation, requiredCourseId? }

Derived lookups (courses-by-set, specs-by-course, etc.) are computed once at module load.

Data is transcribed from SPECIALIZATION_EVALUATION.md and verified by a unit test that checks row/column counts, required course mappings, and S1/S2 marker counts against known totals.

Risks / Trade-offs

[Decision tree too slow with many open sets] → Web Worker + progressive rendering + early termination. If 10+ sets are open, fall back to upper-bound reachability only (no full enumeration). Acceptable because with 10 open sets the user hasn't made enough choices for precise decision analysis to matter.

[Data transcription errors in embedded matrix] → Unit test validates the embedded data against known aggregate counts (46 courses, 14 specs, specific marker totals per spec from the reachability table in SPECIALIZATION_EVALUATION.md). Any transcription error changes a count and fails the test.

[LP solver library abandoned or buggy] → javascript-lp-solver is simple enough that the relevant subset (feasibility checking) could be replaced with a custom implementation if needed. The LP instances are trivially small.

[User confusion between optimization modes] → Show both results side by side when they differ. When they agree, the mode toggle is less prominent. The interesting moment — when the modes disagree — is where the user learns something.