# Orchard Suite Porting Assessment

> Generated: 2026-05-21 — last updated: 2026-06-03  
> Scope: `~/src/virtual-sales-rep` (apps/vsr frontend + vsr-graphql-server)  
> Reference: `research/other_repos/orchard-suite` (local copy, currently stale)

---

## TL;DR

VSR is **~25–35% aligned** with Orchard Suite conventions. Dependencies and architectural intent are correct, but the rendered UI layer is still predominantly custom markup. Approximately **65–75% of the frontend port remains**.

---

## 1. Orchard Suite Reference Repo Status

| | Value |
|---|---|
| Local HEAD | `ce22a513ef217da4a89f48ac59273e8746c83c78` |
| Upstream (`origin/master`) | `d64eb7b04fdc2525965933917f9c424d677f76bc` |
| Status | **Behind** — 70+ commits, 453 files changed |

Notable upstream tags not yet in local copy:

- `@theorchard/suite-frontend@9.8.0`
- `@theorchard/suite-components@13.5.2`
- `@theorchard/suite-components@13.5.1`
- `@theorchard/suite-components@13.5.0`
- `@theorchard/suite-components@13.4.0`
- `@theorchard/suite-components@13.3.0`
- `@theorchard/suite-icons@7.22.1`
- `@theorchard/suite-icons@7.22.0`
- `@theorchard/suite-icons@7.21.0`

**Action needed:** update `research/other_repos/orchard-suite` to latest before doing detailed component-level comparisons.

---

## 2. What VSR Has Already Adopted

### Package dependencies (apps/vsr/package.json)

```
@theorchard/suite-apollo: "*"
@theorchard/suite-components: "*"
@theorchard/suite-frontend: "*"
@theorchard/frontend-cli-vite: "^2.3.0"
@theorchard/frontend-cli: "*"
@theorchard/vitest-config: "*"
```

### Package dependencies (packages/vsr-graphql-server/package.json)

```
@theorchard/graphql-server: "*"
@theorchard/vitest-config: "*"
```

### Architecture intent documented in code comments

| File | Comment |
|---|---|
| `apps/vsr/src/app.tsx` | `initApplication() from @theorchard/suite-frontend will wrap this once suite-auth is wired (Phase 10)` |
| `apps/vsr/src/devMode.tsx` | `This replaces @theorchard/suite-auth entirely in local lab.` |
| `apps/vsr/src/apollo/apolloClient.ts` | Uses relative `/graphql` endpoint via Vite proxy (D006 — lab mitigation). Target: `createApolloClientOptions()` from `@theorchard/suite-apollo`. |

---

## 3. Current Custom UI Inventory

Inspected 16 key TSX files across `apps/vsr/src/pages/` and `apps/vsr/src/components/`.

### Raw HTML primitive usage

| Primitive | Occurrences | Orchard Replacement |
|---|---:|---|
| `<button>` | 46 | `Button`, `GlyphButton`, `SegmentedButton` from suite-components |
| `<table>` | 10 | `GridTable`, `ListView`, `Section` table patterns |
| `<input>` | 16 | `Field`, `NumberInput`, `SearchInput`, `SegmentedInput` |
| `<select>` | 2 | `Select`, `MultiSelect` from suite-components |
| `<form>` | 2 | Suite form patterns (no dedicated Form component, but Field-based layouts) |
| `<label>` | 12 | Handled by `Field` component labels |
| `<nav>` | 2 | `MainNav`, `PageHeader` breadcrumb, tab patterns |

### Suite import adoption

- **1 of 16 inspected files** has a direct `@theorchard/suite-*` import in the source
- **15 of 16 files** use only raw HTML elements or custom CSS classes (`vsr-*`)

---

## 4. File-by-File Gap Analysis

### `apps/vsr/src/app.tsx`
- **Current:** `BrowserRouter` + `Switch` + `Route` + `ApolloProvider`
- **Target:** `initApplication()` from `@theorchard/suite-frontend` (wraps routing, Apollo, auth, theming)
- **Gap:** Full bootstrap replacement needed

### `apps/vsr/src/components/VsrLayout.tsx`
- **Current:** Custom header, tabs, subtabs, breadcrumb, sidebar/content layout
- **Target:** `MainNav`, `PageHeader`, suite shell patterns (see `frontend-solfege` reference app)
- **Gap:** Complete shell rewrite to suite conventions

### `apps/vsr/src/pages/DashboardPage.tsx`
- **Current:** 4 buttons, 3 tables, custom CSS
- **Target:** `Section`, `GridTable`/`ListView`, `Button`, `PageHeader`
- **Gap:** Full page migration

### `apps/vsr/src/pages/CatalogPage.tsx`
- **Current:** 11 buttons, 1 table, 1 input, 1 form, custom search/filter UI
- **Target:** `SearchInput`, `FilterCloud`, `Button`, `GridTable`, `Pagination`
- **Gap:** Full page migration (largest page)

### `apps/vsr/src/pages/ProductDetailPage.tsx`
- **Current:** 3 buttons, 1 table, 1 input, custom product layout
- **Target:** `PageHeader`, `Section`, `MetadataList`, `Button`, `NumberInput`
- **Gap:** Full page migration

### `apps/vsr/src/pages/OrderHistoryPage.tsx`
- **Current:** 1 table, 1 select, 1 label, custom filter
- **Target:** `Select`, `GridTable`, `Section`, `PageHeader`
- **Gap:** Full page migration

### `apps/vsr/src/pages/ShippingPage.tsx`
- **Current:** 2 buttons, 1 input, 1 select, 2 labels, custom form
- **Target:** `Field`, `Select`, `Button`, checkout flow patterns
- **Gap:** Full page migration

### `apps/vsr/src/pages/ReviewPage.tsx`
- **Current:** 3 buttons, 1 table, checkout summary layout
- **Target:** `Section`, `GridTable`, `Button`, checkout flow patterns
- **Gap:** Full page migration

### `apps/vsr/src/pages/ProfilePage.tsx`
- **Current:** 3 buttons, 2 inputs, 5 labels, custom form sections
- **Target:** `Field`, `Button`, `Section`, form layout patterns
- **Gap:** Full page migration

### `apps/vsr/src/pages/OrderToolsPage.tsx`
- **Current:** 5 buttons, 1 table, 2 inputs, custom upload/download UI
- **Target:** `Button`, `Field`, `UploadArea`, `Section`, `GridTable`
- **Gap:** Full page migration

### `apps/vsr/src/pages/OrderDetailPage.tsx`
- **Current:** 1 button, 1 table, custom detail layout
- **Target:** `PageHeader`, `MetadataList`, `Section`, `GridTable`
- **Gap:** Full page migration

### `apps/vsr/src/pages/CartPage.tsx`
- **Current:** 5 buttons, 1 table, 1 input, custom cart layout
- **Target:** `GridTable`, `NumberInput`, `Button`, `Section`
- **Gap:** Full page migration

### `apps/vsr/src/pages/RegisterPage.tsx`
- **Current:** 2 buttons, 5 inputs, 5 labels, 1 form, registration flow
- **Target:** `Field`, `Button`, form layout patterns (or redirect to suite-auth flow)
- **Gap:** Full page migration (may be superseded by suite-auth registration)

### `apps/vsr/src/components/ProductRow.tsx`
- **Current:** 2 buttons, 1 input, custom table row component
- **Target:** Inline with `GridTable` row patterns, `NumberInput`, `Button`
- **Gap:** Full component migration

### `apps/vsr/src/components/CheckoutSteps.tsx`
- **Current:** 1 button, custom step indicator
- **Target:** `Stepper` from suite-components
- **Gap:** Direct replacement available

### `apps/vsr/src/components/Pagination.tsx`
- **Current:** 3 buttons, custom pagination
- **Target:** `Pagination` from suite-components
- **Gap:** Direct replacement available

---

## 5. Porting Priority Matrix

| Priority | Area | Impact | Effort | Notes |
|---|---|---|---|---|
| P0 | App bootstrap (`app.tsx`) | High | Medium | Unlocks auth, theming, i18n globally |
| P0 | Auth integration | High | Medium | `suite-auth` + `suite-frontend` auth flow |
| P1 | Layout shell (`VsrLayout.tsx`) | High | High | Most visible alignment change |
| P1 | Pagination component | Medium | Low | Direct 1:1 replacement exists |
| P1 | CheckoutSteps component | Medium | Low | `Stepper` is a direct replacement |
| P2 | CatalogPage (largest page) | High | High | Most complex migration |
| P2 | DashboardPage | Medium | Medium | High traffic, visible alignment |
| P2 | CartPage | Medium | Medium | Core commerce flow |
| P3 | OrderHistoryPage | Medium | Low | Simple table + filter |
| P3 | ProductDetailPage | Medium | Medium | Detail layout patterns |
| P3 | OrderToolsPage | Medium | Medium | Upload/download patterns |
| P3 | ShippingPage | Low | Low | Simple form |
| P3 | ReviewPage | Low | Low | Simple summary + table |
| P4 | ProfilePage | Low | Low | May be superseded by suite-auth account pages |
| P4 | RegisterPage | Low | Low | Likely superseded by suite-auth registration |
| P4 | OrderDetailPage | Low | Low | Simple detail view |

---

## 6. Key Orchard Suite Components to Adopt

Based on the gap analysis, the following `suite-components` primitives map directly to current custom code:

| suite-components | Replaces | Files affected |
|---|---|---|
| `Button` | raw `<button>` | All 16 files |
| `GridTable` / `ListView` | raw `<table>` | 10 pages |
| `Field` | raw `<input>` + `<label>` | 7 pages |
| `Select` / `MultiSelect` | raw `<select>` | 2 pages |
| `SearchInput` | custom search `<input>` + `<form>` | CatalogPage |
| `Pagination` | custom `Pagination.tsx` | CatalogPage, others |
| `Stepper` | custom `CheckoutSteps.tsx` | Checkout flow |
| `PageHeader` | custom breadcrumb in VsrLayout | VsrLayout |
| `Section` | custom page sections | All pages |
| `NumberInput` | qty `<input type="number">` | CartPage, ProductDetailPage |
| `UploadArea` | custom upload UI | OrderToolsPage |
| `MetadataList` | custom detail layouts | ProductDetailPage, OrderDetailPage |

From `suite-frontend`:

| suite-frontend | Replaces | Files affected |
|---|---|---|
| `initApplication()` | manual `BrowserRouter` + `ApolloProvider` | app.tsx |
| `MainNav` | custom header + tabs in VsrLayout | VsrLayout |
| Auth flow (`useAuthFlow`) | DevModeProvider bypass | app.tsx, devMode.tsx |
| `ThemeProvider` | custom `vsr-theme.scss` global import | VsrLayout |

---

## 7. Orchard Suite Reference App

The best local reference for "what a suite-aligned app looks like" is:

```
research/other_repos/orchard-suite/apps/frontend-solfege/
```

Key patterns to study:
- `package.json` — dependency versions and workspace references
- How it uses `@theorchard/suite-frontend` for bootstrap
- How it uses `@theorchard/suite-components` for all UI
- Its `scripts/` directory for build/start patterns
- Its use of `@theorchard/frontend-cli-vite` for dev/build tooling

---

## 8. Estimated Effort

| Category | Files | Estimated days (1 dev) |
|---|---:|---|
| Bootstrap + auth | 3 | 3–5 days |
| Shell / layout | 1 | 2–3 days |
| Simple replacements (Pagination, Stepper) | 2 | 0.5 day |
| Page migrations (11 pages) | 11 | 8–12 days |
| Component migrations (ProductRow, etc.) | 3 | 2–3 days |
| Theming / CSS cleanup | all | 2–3 days |
| **Total** | **~20** | **~18–27 days** |

This assumes familiarity with suite-components API. If learning curve is included, add ~30%.

---

## 9. Open Questions

1. Should `RegisterPage` and `ProfilePage` be migrated at all, or will `suite-auth` handle account management flows?
2. What version of `suite-components` should VSR pin to — latest (`13.5.x`) or the v13 baseline mentioned in decision logs?
3. Is the embedded `orchard-suite` copy meant to be a git subtree, a submodule, or just a manual snapshot for reference?
4. Should the migration happen incrementally (page-by-page) or as a single large effort?
5. **GraphQL endpoint configuration (suite-apollo wiring) — proxy removal required.** The current local dev setup uses a Vite proxy (`server.proxy: { "/graphql": "http://localhost:4000" }`) as a temporary mitigation for local and LAN development. This proxy exists only in the Vite dev server and has no effect in built artefacts — but the Apollo client's relative `/graphql` default will not resolve correctly in a deployed environment without a real endpoint being injected. When porting to Orchard Suite, the proxy must be removed and replaced with `createApolloClientOptions()` from `@theorchard/suite-apollo` with environment-specific endpoint configuration from `@theorchard/frontend-cli`. This is **P0 work** (same priority as the `initApplication()` / `suite-auth` wiring in step 2 below) and is blocked by INT-2697 (auth) and INT-2698 (GraphQL server). See decision log D006.

---

## 10. Next Steps

1. **Update `research/other_repos/orchard-suite`** to latest upstream
2. **P0 — App bootstrap:** wire `initApplication()` and `suite-auth` in `app.tsx`; simultaneously remove the Vite dev proxy and replace `apolloClient.ts` with `createApolloClientOptions()` from `@theorchard/suite-apollo` with environment-specific endpoint config from `@theorchard/frontend-cli` (see D006, blocked by INT-2697 + INT-2698)
3. **P1 — Layout shell:** replace `VsrLayout.tsx` with `MainNav` + `PageHeader` patterns
4. **P1 quick wins:** swap `Pagination.tsx` → suite `Pagination`, `CheckoutSteps.tsx` → suite `Stepper`
5. **P2–P4:** migrate pages in priority order