Plan the website and backend architecture for Hadron's Blessing

[hummat]

The long-term target includes a website/backend, but the first standalone release is CLI/library only.

Scope:

• decide static-site vs server-backed responsibilities
• define how the web layer consumes the canonical machine-readable contract
• plan import flows for GamesLantern and other build sources
• keep the website architecture downstream of the core data/tooling project

[hummat]

Brainstorming Analysis — 2026-03-31

Decisions Made

• Fully client-side static site on GitHub Pages (adapter-static)
• SvelteKit + Tailwind CSS + Svelte Flow (as planned in AGENTS.md)
• Build creator/optimizer, not just a browser — users construct builds and get live feedback
• Progressive disclosure as the core UX pattern — beginners see grades + verdicts, experts expand to full data
• Ground-truth data ~388KB gzipped on the wire — comfortable for client-side

MVP Scope (v1)

Core pages:

1. Build list / browse — scorecard table with letter grades, 7 dimensions, filtering by class/weapon/grade, sorting by any dimension. Direct port of npm run list.
2. Build detail view — scorecard with progressive disclosure (grade → dimension breakdown → per-dimension explanation). Build fingerprint radar chart from family_profile. Synergy graph (Svelte Flow, simple mode). Breakpoint matrix (color-coded HTK table). Stagger/cleave summaries.
3. Build comparison — side-by-side diff with score deltas, structural diff, breakpoint HTK comparison. Port of npm run diff --detailed.

MVP interactive features:
4. Import from GL URL — paste a Games Lantern URL, scrape → canonicalize → display. Leverages existing extract-build pipeline.
5. Build smells / coverage gap warnings — "Your build has no toughness regen source" style warnings from analyze-gaps. Educational for beginners.
6. "Explain This Grade" drilldown — every scorecard dimension expands to: inputs used, what helped, what hurt. Already computed by generateScorecard qualitative breakdowns.

Data layer:
7. Static JSON data loading — index.json, breed-data.json, damage-profiles.json, stagger-settings.json, class-base-stats.json, breakpoint-checklist.json as static assets loaded on demand.
8. Build fixtures — 24 builds shipped as static JSON, pre-computed scorecards/synergy/calc cached at build time.

v1.1 (post-MVP)

• Build editor — interactive talent tree (Svelte Flow), weapon/blessing picker with live scoring updates
• What-if swap analysis — change a talent/weapon, see score delta + gained/lost synergy edges + breakpoint changes
• Damage pipeline storyboard — visual left-to-right chain showing each pipeline stage with numbers
• Build autopsy — causal diagnosis ("A-rank because X, but drops Y")
• Regret minimizer — "most expensive wrong choices" sorted by score impact

v2+

• Goal-first optimizer (optimize for "Crusher stagger" or "Auric pub carry")
• Encounter lenses (same build scored under different engagement types)
• Sensitivity analysis (toggle buff uptime, crit rate, coherency)
• Constraint solver ("improve survivability without lowering Crusher breakpoint")
• Pareto frontier (plot builds on competing axes)
• Breakpoint query builder (arbitrary "show me every way to reach X")
• Shareable proof links (permalink to a specific analytical state)
• Template trajectories (upgrade paths from starter builds)

Key Architecture Constraints

• All computation in-browser — no server, no API calls
• Library functions (src/lib/index.ts) currently use fs for data loading — need a browser-compatible data layer (fetch static JSON instead of fs.readFileSync)
• SvelteKit adapter-static pre-renders all routes at build time; dynamic routes use client-side hydration
• Svelte Flow for synergy graph and (v1.1) talent tree editor

Differentiator vs Existing Tools

Ranald's Gift and Games Lantern are build planners — they help you select. Hadron's Blessing is a build analyst — it tells you why a build is good, what's weak, and what to change. The analytical engine (synergy, scoring, breakpoints, stagger, cleave, toughness) already exists in the library; the website's job is to make it visible and interactive.

[hummat]

Plan 3 is now implemented on main: website compare page, structural diff payload generation, shared compare helpers, build-list compare selection, and build-detail compare entrypoint. Local verification passed: website tests, data generation, and production build. Plan 4 (GL import / interactive features) remains next.

[hummat]

Status update after the compare-page work and current site cleanup pass:

• Plans 1–3 are effectively in place on main: build list, build detail page, and build comparison page.
• The recent frontend pass also cleaned up detail/compare presentation, widened the list view, fixed missing/misleading ranged breakpoint panels, and added explicit Unsupported messaging for ranged families the calculator does not actually model yet.

What remains under #6 is the website/product-level next step, not generic backend cleanup:

• Plan 4: GL import / interactive features
• any remaining architecture decisions specifically tied to the website flow

I split the newly discovered backend/data-contract follow-ups into dedicated issues so #6 stays focused:

• #22 Add breakpoint support for unsupported ranged weapon families in the current build corpus
• #23 Fix null weapon perk entries in generated scorecard/detail payloads
• #24 Extend damage-profile extraction to remaining template variants outside the current fixture corpus

That leaves #6 as the umbrella for website architecture/product scope, with the concrete backend/calculator tails tracked separately.

[hummat]

Website implementation sequence (2026-04-12)

Visual audit identified that #26 (IA restructure) cannot succeed without a visual hierarchy system. Created #27 as a prerequisite.

Recommended order:

1. Expand GL alias coverage beyond the canonical fixture set #21 — GL alias coverage verification pass (cheap, close it out)
2. Add design system foundation: typography, card tiers, progressive disclosure defaults #27 — Design system foundation (typography, card tiers, progressive disclosure defaults)
3. Redesign the website information architecture around verdict-first build analysis #26 — Website IA redesign (verdict-first, builds on Add design system foundation: typography, card tiers, progressive disclosure defaults #27's visual vocabulary)
4. Add structured hover detail cards for compressed or non-obvious website items #25 — Hover detail cards (builds on Redesign the website information architecture around verdict-first build analysis #26's restructured components)

Data pipeline work (#22, #24) is independent and can interleave at any point.

Plans 1–3 are merged. Plan 4 (GL import / interactive features) comes after the above sequence.