@org-design-studio/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Aggrawal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# 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
+
+```bash
+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).
+
+```bash
+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.
+
+```bash
+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](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.