ORG DESIGN STUDIO

A consulting-grade HR org-design and workforce-modelling web application. Upload employee data, visualize the organization, run spans & layers diagnostics, model future-state scenarios, and generate board-ready insights and reports — the kind of analysis typically produced by top org-design consulting teams.

Quick start

npm install
npm run dev        # development — http://localhost:3000
# or production:
npm run build && npx next start

Then either click Load demo organization (a deterministic ~300-person company, "Meridian Global Services", with intentional structural issues to explore), or go to Upload and import your own CSV/XLSX (a downloadable template is provided; columns are auto-mapped with a manual mapping step).

npm test           # vitest — 100 unit/integration tests over the analytics engine and store
npm run lint
npx tsc --noEmit

Browser-driven e2e scenarios live in tests/e2e/*.md (runnable with Claude Code's /e2e skill once the chrome-devtools MCP server is connected).

Embedding the engine (@org-design-studio/core)

The entire analytics engine (spans & layers metrics, validation, scenario economics, insights, headless org-chart layout) is packaged as an embeddable library so other HR tools and consultancies can run the methodology on their own data with their own UI. The public surface is the curated barrel src/lib/core.ts — pure TypeScript, no React/DOM, only d3-hierarchy as a runtime dependency.

npm run build:core   # tsup → dist-core/ (ESM + CJS + .d.ts)
npm run check:core   # fast build without type declarations

The publish manifest template lives at packages/core-package.json. Full API reference, quickstart, and the embedding guide: docs/API.md.

Privacy

All workforce data is processed locally in the browser (zustand + localStorage). Nothing is sent to any server. Handle real salary/personal data securely regardless.

Architecture

src/lib/            The analytical brain — pure, tested functions
  types.ts          Data model: Employee, OrgMetrics, Scenario, Assumptions, Insight, …
  hierarchy.ts      Tree building, layers, spans, rollups, cycle/orphan detection
  analytics.ts      OrgMetrics: spans/layers/cost/duplication/AI exposure/org health
  validation.ts     Upload parsing, field auto-mapping, data-quality score (0–100)
  scenario.ts       Immutable-baseline scenario engine, transition costs, change risk, scoring
  insights.ts       Rule-based, ranked consulting insights (AI-ready interface)
  demo-data.ts      Seeded deterministic demo organization
  store.ts          Zustand store + memoized derived-data hooks
src/components/     UI kit (shadcn-style), charts (Recharts + custom), org chart, app shell
src/app/            11 routes: / upload org diagnostics cost scenarios compare insights report settings help

Key design decisions:

• Baseline is immutable. A scenario is an ordered list of changes replayed onto the baseline; undo = drop the last change. Every metric is recomputed from the derived employee list.
• Every number is traceable. No mock values anywhere; all charts/KPIs derive from the loaded dataset through computeMetrics.
• Assumption-driven. Span bands by level, layer benchmarks, savings capture rates, transition cost (severance/backfill/change cost), location multipliers, scoring weights and AI-augmentation mappings are all configurable in Settings and flow through every calculation.
• AI-ready insights. generateInsights(data, assumptions, scenarios) is a clean interface; an LLM generator can be swapped in later without touching UI.

Methodology notes

• Spans are level-aware: managers are assessed against the target span band for their level (default: executives 5–8, middle 6–10, frontline 8–15); flat thresholds apply only as a fallback for unleveled employees.
• Opportunity levers are disjoint between delayering (narrow managers with 3+ reports) and span optimization (managers of 1–2); duplication is presented as a separate lens. All figures are framed as indicative opportunity requiring validation, never committed savings.
• Scenario financials are net-of-transition: role eliminations and location shifts incur severance (by level, on baseline cost), backfill drag and per-move change costs; the scenario score uses net year-1 saving, with run-rate shown alongside.
• Change risk scales with employees moved, roles eliminated, senior/critical roles affected, functions/locations impacted and layer/cost deltas, mapped to Low → Very High with implementation guidance.

Scenario actions implemented

Move employee/team (cycle-safe) · Remove role (3 report-handling modes) · Add role · Merge teams · Delayer (by layer × function/BU scope) · Apply target spans (rule-based consolidation suggestions, criticality-aware) · Shift location (cost multipliers) · Change cost — all logged with before/after metrics, undoable, resettable.

Known limitations / future enhancements

• Org chart image export and PDF generation rely on the print-friendly report view (Print / PDF).
• Sankey movement diagram not yet implemented (movement summary table covers the from-to flow).
• Insights are rule-based; the LLM insight generator is architected but not wired.
• Role-based access is a placeholder concept only — the app is single-user, local-first.
• Benchmarks are point estimates, not percentile bands against a peer database.
• The e2e markdown scenarios require a chrome-devtools MCP connection to execute.