Admin / Merchant Shell Split — Design Spec

Date: 2026-04-27 Status: Approved (pending implementation plan) Scope: Restructure apps/admin/ into two role-scoped shells (AdminShell, MerchantShell) with a shared library zone, enforce the boundary at lint + build time, and align the auth API so both shells have well-defined surfaces. Merchants who are also Lantern users get a working self-service experience that doesn't pierce admin gates.

Problem

Iterating on the merchant integration surfaced a recurring pattern: every time a merchant-role user touches the admin app, something breaks (admin-only API gates, admin-shaped sidebar, "Merchant not found" landing failures, role-conditional UI cluttering shared components). The root cause is that apps/admin/ was built admin-first with merchants retrofitted via a merchantOnly flag and a MerchantsIndexRedirect. Every page assumes admin context.

Splitting into two shells with hard boundaries:

• Eliminates role conditionals across every page
• Gives merchants a clean, purpose-built experience
• Lets admins enter "merchant mode" deliberately (with switcher privileges) when they need to see what merchants see
• Sets up the eventual apps/merchant/ separate-app split as a mechanical lift, not a rewrite

Constraints

• Single PR, multi-commit. Each commit leaves the working tree green. No "halfway-migrated" intermediate state.
• No regression in admin functionality. Every existing admin URL keeps working (via back-compat redirects for one release cycle).
• Strict validation, not convention. Cross-shell imports fail lint with error severity. Build-time chunk-graph validation catches dynamic imports that lint can't see.
• No new shared package. Inside one Vite project, @shared/* path aliases are sufficient. Package extraction (@lantern/ui) only when a second app needs the chrome.
• Symmetric URL space. Both shells get a top-level prefix (/admin/*, /merchant/*). No "admin-at-root, merchant-prefixed" asymmetry that leaks into every routing conversation forever.

v1 Scope

Architecture

Two role-scoped shells. The top-level fork happens in App.jsx after Firebase auth state is resolved.

	AdminShell	MerchantShell
URL prefix	/admin/*	/merchant/:merchantId/*
Audience	customClaims.role === 'admin'	role === 'merchant' (own merchantId) OR role === 'admin' (any merchantId, via switcher)
Default landing	/admin/ (DashboardHome)	/merchant/:id/overview
Sidebar	Dashboard, Users, Merchants (list), Docs, Storybook, API, Config, Analytics, System, Billing, Profile, Feature Tracker	Overview, Offers, Venues, Notes, Photos, Address, Profile, ← Admin (admin-only), Sign out
Entry from the other	n/a	Admin sidebar "Merchants" → /admin/merchants/all → row click → window.open('/merchant/:id/overview', '_blank')

Three guarantees:

1. A merchant can never reach admin URLs. Real merchants accessing /admin/* are redirected to /merchant/<theirId>/overview. Enforced at the route guard, validated again at the API by requireAdmin.
2. An admin can reach either shell. Admins entering merchant mode use elevated switcher privileges (any merchantId).
3. No file in src/admin/ or src/merchant/ ever imports from the other. Enforced by ESLint import/no-restricted-paths (error severity) + a build-time chunk validator.

Directory layout

apps/admin/src/
├── App.jsx                     ← role fork; URL-mode handlers
├── main.jsx                    ← Vite entry
├── firebase.js                 ← stays at root (re-exports; will progressively shrink)
│
├── shared/
│   ├── components/             ← LanternLogo, PageHeader, PageTabs, StyledSelect,
│   │                             SetAdminPassword, SetMerchantPassword, SetPassword,
│   │                             LoadingScreen, AccessDenied, LoginScreen,
│   │                             AdminMigrationBanner, ReinitializeLanternModal
│   ├── lib/
│   │   ├── apiClient.js
│   │   ├── authApi.js          ← admin auth + merchant auth endpoint clients
│   │   ├── merchantApi.js      ← role-aware: picks /auth/admin/merchants/:id vs /auth/merchant/me
│   │   ├── currentMerchant.js
│   │   └── env.js
│   ├── hooks/
│   └── styles/                 ← styles.css, design tokens
│
├── admin/
│   ├── AdminShell.jsx          ← sidebar + Routes for /admin/*
│   ├── DashboardHome.jsx
│   ├── users/                  ← UserManagement, UserDetailPanel, CreateAdminForm,
│   │                             CreateMerchantUserForm, AttachMerchantDialog
│   ├── merchants/              ← MerchantsAll (list), MerchantsCreate, CreateMerchantForm
│   ├── docs/                   ← DocsEditor, MarkdownEditor, DocsEmbed, DocPage,
│   │                             SelfHostedDocsEditor
│   ├── api/                    ← ApiOverview, ApiReferencePage, ClientSdkPage, ClientSdkEmbed
│   ├── storybook/              ← StorybookEmbed
│   ├── config/                 ← ConfigOverview, ConfigServicesCors, ConfigRateLimits, ConfigVenue
│   ├── analytics/              ← (existing analytics subtree)
│   ├── system/                 ← SystemHealth
│   ├── billing/                ← Billing
│   ├── feature-tracker/        ← FeatureTracker
│   ├── profile/                ← MyAdminProfile
│   └── lib/
│       └── adminApi.js         ← admin-only API clients
│
└── merchant/
    ├── MerchantShell.jsx       ← sidebar + Routes for /merchant/:merchantId/*
    ├── MerchantSwitcher.jsx    ← dropdown; admin-only
    ├── tabs/                   ← Overview, Offers, Venues, Notes, Photos, Address
    ├── offers/                 ← OfferDetail, OfferForm, OffersList
    ├── profile/                ← MyMerchantProfile (new)
    └── lib/
        └── merchantSelfApi.js  ← merchant-only thin client

Component fates:

• MerchantDetail.jsx — deleted. Its responsibility (route shell + tab switching) is replaced by MerchantShell.jsx.
• MerchantsIndexRedirect.jsx — deleted. The role fork in App.jsx makes it obsolete.
• MerchantSwitcher.jsx — moves into the merchant shell (it's a merchant-shell affordance).
• Existing merchants/tabs/Merchant*Tab.jsx files — renamed (drop the "Tab" suffix) and moved to src/merchant/tabs/ since each is now a top-level page, not a tab strip entry.

Path aliases

apps/admin/vite.config.mjs and apps/admin/vitest.config.mjs:

resolve: {
  alias: {
    '@admin': path.resolve(__dirname, 'src/admin'),
    '@merchant': path.resolve(__dirname, 'src/merchant'),
    '@shared': path.resolve(__dirname, 'src/shared'),
  },
}

Lint enforcement (apps/admin/.eslintrc.json)

{
  "rules": {
    "import/no-restricted-paths": ["error", {
      "zones": [
        {
          "target": "./src/admin",
          "from": "./src/merchant",
          "message": "Admin code may not import from src/merchant. Move shared code to src/shared/."
        },
        {
          "target": "./src/merchant",
          "from": "./src/admin",
          "message": "Merchant code may not import from src/admin. Move shared code to src/shared/."
        },
        {
          "target": "./src/shared",
          "from": ["./src/admin", "./src/merchant"],
          "message": "src/shared may not depend on shell-specific code. Inline or invert the dependency."
        }
      ]
    }]
  }
}

App.jsx, main.jsx, and firebase.js at the root are the bootstrap layer. They are not in src/admin/ or src/merchant/ and are allowed to import from any of the three zones.

Build-time bundle validator

tooling/scripts/check-shell-isolation.mjs runs after npm run build (added to npm run validate). Reads Vite's dist/.vite/manifest.json and asserts:

• The chunk graph reachable from MerchantShell.jsx's entry includes no module under src/admin/.
• The chunk graph reachable from AdminShell.jsx's entry includes no module under src/merchant/.

Catches dynamic import() paths that ESLint can't statically analyze.

URL space

Admin shell route tree (/admin/*)

/admin/                          → DashboardHome
/admin/users                     → UserManagement
/admin/merchants                 → redirects to /admin/merchants/all
/admin/merchants/all             → MerchantsAll (list — entry to merchant mode)
/admin/merchants/new             → MerchantsCreate
/admin/docs/*                    → DocsEditor subtree
/admin/storybook                 → StorybookEmbed
/admin/api/*                     → ApiOverview / ApiReferencePage / ClientSdkPage
/admin/config/*                  → ConfigOverview / ConfigServicesCors / ConfigRateLimits / ConfigVenue
/admin/analytics/*               → analytics subtree
/admin/system                    → SystemHealth
/admin/billing                   → Billing
/admin/profile                   → MyAdminProfile
/admin/feature-tracker           → FeatureTracker

Note: there is no admin route that renders the merchant tabs. Admins view those only through the merchant shell. MerchantsAll rows include an "Open in merchant mode" affordance that calls window.open('/merchant/:id/overview', '_blank').

Merchant shell route tree (/merchant/:merchantId/*)

/merchant/:id/                   → redirects to overview
/merchant/:id/overview           → Overview
/merchant/:id/offers             → OffersList
/merchant/:id/offers/new         → OfferForm (mode=create)
/merchant/:id/offers/:offerId    → OfferDetail
/merchant/:id/offers/:offerId/edit → OfferForm (mode=edit)
/merchant/:id/venues             → Venues
/merchant/:id/notes              → Notes
/merchant/:id/photos             → Photos
/merchant/:id/address            → Address
/merchant/:id/profile            → MyMerchantProfile

Route guards

At the App.jsx fork (before any shell renders):

• Real merchants accessing /admin/* → redirected to /merchant/<theirId>/overview
• Real merchants accessing / or any non-admin/non-merchant path → redirected to /merchant/<theirId>/overview
• Admins accessing / or any non-admin/non-merchant path → redirected to /admin/

Inside MerchantShell (additional self-merchant guard):

• Real merchants whose URL :merchantId does not match their claimed merchantId → redirected to their own merchant
• Admins are free to navigate to any :merchantId

Backwards-compatibility redirects

For one release cycle, redirect old admin URLs to the new /admin/* namespace. The shipping list:

Old URL	New URL
/users/*	/admin/users/*
/docs/*	/admin/docs/*
/storybook	/admin/storybook
/client-sdk/*	/admin/api/client-sdk/* (note: was top-level, now nested under api)
/system	/admin/system
/billing	/admin/billing
/profile	/admin/profile
/feature-tracker	/admin/feature-tracker
/api/*	/admin/api/*
/config/*	/admin/config/*
/analytics/*	/admin/analytics/*
/merchants	/admin/merchants/all
/merchants/all	/admin/merchants/all
/merchants/new	/admin/merchants/new
/merchants/:merchantId/*	/merchant/:merchantId/* (note: plural→singular)

Track removal via a TODO comment + a /schedule follow-up agent (~2 weeks after merge).

Backend — shared handlers + dual route mounts

The merchant data API needs to serve both:

• Admins via /auth/admin/merchants/:merchantId/* (any merchantId)
• Merchants via /auth/merchant/me/* (merchantId resolves from token claim)

Refactor:

• Extract route handlers from services/api/auth/src/routes/adminMerchants.js into pure functions in a new services/api/auth/src/handlers/merchantHandlers.js.
• adminMerchants.js becomes a thin router that wires handlers under admin paths with requireAdmin middleware (unchanged behavior from today).
• New services/api/auth/src/routes/merchantSelf.js mounts a subset of those handlers under /me. A small middleware injects req.params.merchantId = req.user.merchantId before the handlers run.

New middleware: requireMerchant in services/api/auth/src/middleware/auth.js (mirror of requireAdmin).

What's mounted on each route:

Handler	/auth/admin/merchants/:id/...	/auth/merchant/me/...
getMerchantDetail	✓ (any merchant)	✓ (own merchant)
listMerchants	✓	✗ — admin only
createMerchantUserForMerchant	✓	✗ — admin onboards
detachUserFromMerchant	✓	✗ — admin manages
associateVenueWithMerchant	✓	✗ — admin claims
disassociateVenueFromMerchant	✓	✗ — admin un-claims

For v1, only getMerchantDetail is mounted on /me. Adding more handlers later is a single-line change in merchantSelf.js.

Client-side routing: in src/shared/lib/merchantApi.js, getMerchantDetail(merchantId) checks the current Firebase token's role claim and dispatches to the admin URL or the /me URL accordingly. Each shell calls the same function.

Merchant write paths:

• Offers (services/api/merchants/, port 8085) — already merchant-accessible via Firestore rules. No change.
• Photos (Firebase Storage) — existing merchant-writable rules. No change unless gaps surface.
• Business name / contact / notes / address — currently admin-only via PATCH /auth/admin/users/merchant/:userId (and merchant business updates). Add merchant-self versions in the migration phase if/when needed; otherwise the merchant tabs initially treat those as read-only and admin handles edits.

Migration sequencing (phased)

Each commit leaves the tree green.

Phase A — Foundation (4 commits, no behavior change)

1. Add path aliases to vite.config.mjs + vitest.config.mjs.
2. Create empty src/shared/, src/admin/, src/merchant/ (with .gitkeep).
3. Add ESLint import/no-restricted-paths rule (zones empty initially).
4. Add tooling/scripts/check-shell-isolation.mjs wired into npm run validate.

Phase B — Move shared infrastructure (5 commits) 5. Move design tokens / styles.css to src/shared/styles/. 6. Move LanternLogo.jsx to src/shared/components/. 7. Move PageHeader, PageTabs, StyledSelect, LoadingScreen, AccessDenied to src/shared/components/. 8. Move LoginScreen, SetAdminPassword, SetMerchantPassword, SetPassword, AdminMigrationBanner, ReinitializeLanternModal to src/shared/components/. 9. Move lib/apiClient.js, lib/authApi.js, lib/currentMerchant.js to src/shared/lib/.

Phase C — Build the shell skeletons (4 commits) 10. Create src/admin/AdminShell.jsx (initially imports admin pages from old paths). 11. Create src/merchant/MerchantShell.jsx (with placeholder pages). 12. Update App.jsx with the role fork + back-compat redirects. 13. Add requireMerchant middleware to the auth API.

Phase D — Migrate admin pages (7 commits) 14. UserManagement subtree → src/admin/users/ 15. Docs subtree → src/admin/docs/ 16. API/SDK subtree → src/admin/api/ 17. Analytics subtree → src/admin/analytics/ 18. Misc admin pages (Billing, SystemHealth, MyAdminProfile, FeatureTracker, StorybookEmbed) → src/admin/{billing,system,profile,feature-tracker,storybook}/ 19. Admin-side merchants management (MerchantsAll, MerchantsCreate, CreateMerchantForm + "Open in merchant mode" affordance) → src/admin/merchants/ 20. Update AdminShell.jsx imports to @admin/* paths.

Phase E — Migrate merchant pages (6 commits) 21. MerchantOverviewTab → src/merchant/tabs/Overview.jsx (rename, drop "Tab" suffix). 22. MerchantOffersTab/VenuesTab/NotesTab/PhotosTab/AddressTab → corresponding pages in src/merchant/tabs/. 23. OfferDetail, OfferForm, OffersList → src/merchant/offers/. 24. MerchantSwitcher → src/merchant/MerchantSwitcher.jsx. 25. Delete MerchantDetail.jsx and MerchantsIndexRedirect.jsx. 26. Replace placeholders in MerchantShell.jsx with real imports.

Phase F — Backend dual-mount (3 commits) 27. Extract handlers from routes/adminMerchants.js to handlers/merchantHandlers.js. Old route file becomes thin wiring. 28. Add merchantSelfRoutes at routes/merchantSelf.js. Mount under /auth/merchant/me. 29. Update src/shared/lib/merchantApi.js to do role-aware URL selection.

Phase G — Wire merchant write paths (2 commits, may grow) 30. Audit each merchant-shell page that writes data; document which endpoints are already merchant-accessible vs need /me mounting. The audit's findings drive how many follow-on commits are needed in this phase — if every write path turns out to use services/api/merchants/ (already merchant-accessible) or read-only fields, no further commits. If gaps exist, each gap = one additional commit (one per /me mount or new endpoint). Estimate 2-6 total commits including the audit. 31. Add /me mounts and/or new endpoints for any gaps surfaced by step 30.

Phase H — Profile + tests (4 commits) 32. Create src/merchant/profile/MyMerchantProfile.jsx. 33. Component tests for MerchantShell (renders, redirects on role mismatch, switcher visibility). 34. Component tests for AdminShell (renders, "Merchants" opens new tab — mock window.open). 35. Route-guard test: real merchant accessing /admin/users redirects to /merchant/<theirId>/overview.

Phase I — Final validation + PR (1 commit + close-out) 36. Run npm run validate end-to-end. Manual smoke matrix. Open PR.

Estimated total: ~36-40 commits (Phase G's audit may add a few), each small and self-contained.

Testing

Component tests (vitest + Testing Library)

• src/admin/__tests__/AdminShell.test.jsx:

  • Renders the admin sidebar with all expected items
  • "Merchants" sidebar item navigates to /admin/merchants/all
  • MerchantsAll row click calls window.open('/merchant/<id>/overview', '_blank')
  • Routes correctly resolve admin sub-pages

• src/merchant/__tests__/MerchantShell.test.jsx:

  • Real merchant whose merchantId === url:merchantId renders the shell
  • Real merchant whose merchantId !== url:merchantId redirects to their own
  • Admin viewing any merchant renders the shell with the switcher visible
  • Real merchant does NOT see the switcher
  • Real merchant does NOT see the "← Admin" sidebar item
  • Admin DOES see the "← Admin" sidebar item

• src/__tests__/App.test.jsx (or update existing):

  • Real merchant lands on /admin/X → redirects to /merchant/<theirId>/overview
  • Admin lands on / → redirects to /admin/
  • Old /users URL → redirects to /admin/users
  • Old /merchants/<id> URL → redirects to /merchant/<id>/overview
  • Real merchant lands on /merchant/<other-id>/... → redirects to their own

• src/shared/lib/__tests__/merchantApi.test.js:

  • When current user is admin → getMerchantDetail(id) calls /auth/admin/merchants/:id
  • When current user is merchant → getMerchantDetail(id) calls /auth/merchant/me

Existing tests updated:

• apps/admin/src/components/__tests__/AdminDashboard.test.jsx supersedes / merges into AdminShell.test.jsx. Legacy AdminDashboard component goes away.
• CreateMerchantUserForm.test.jsx, SetMerchantPassword.test.jsx — import paths shift; logic unchanged.

Backend tests

• services/api/auth/src/handlers/__tests__/merchantHandlers.test.js: confirms each handler reads req.params.merchantId correctly given different mock requests.
• services/api/auth/src/routes/__tests__/merchantSelf.test.js: confirms the /me middleware injects req.params.merchantId = req.user.merchantId.

The auth-API still has minimal route-level integration coverage. This PR does not add the integration scaffolding (deferred per existing "Known Gap"); the unit-level tests above cover the structural change.

Lint enforcement validation

A one-shot test fixture (tooling/scripts/lint-fixture-cross-zone.mjs) creates a temporary file with a deliberately-bad import, runs ESLint on it, asserts it fails, then deletes the file. Guards against the rule being silently disabled or misconfigured.

Build-time bundle validation

tooling/scripts/check-shell-isolation.mjs runs after npm run build as part of npm run validate. Reads Vite's dist/.vite/manifest.json and asserts no admin module is reachable from MerchantShell and vice versa.

Manual smoke matrix

Action	Real merchant	Admin
Sign in	Lands on /merchant/<theirId>/overview	Lands on /admin/
Visit /admin/users	Redirected to own merchant overview	Renders user management
Visit /merchant/<otherId>/overview	Redirected to own merchant	Renders other merchant's overview
Visit old /users	Redirects, then merchant guard fires → own merchant	Redirects to /admin/users
Open /merchant/<id>/offers	Loads offers for own merchant only	Loads offers for the picked merchant via switcher
Click "Merchants" in admin sidebar	n/a	Navigates to /admin/merchants/all
Click row in admin merchants list	n/a	Opens /merchant/<id>/overview in a new browser tab
Click "← Admin" in merchant sidebar	Doesn't appear	Returns to /admin/
Sign out	Returns to LoginScreen	Returns to LoginScreen
Forgot password	Same parallel-fan-out as today	Same

Files Touched

New

• apps/admin/src/admin/AdminShell.jsx
• apps/admin/src/admin/__tests__/AdminShell.test.jsx
• apps/admin/src/merchant/MerchantShell.jsx
• apps/admin/src/merchant/MerchantSwitcher.jsx (moved + lightly adapted)
• apps/admin/src/merchant/__tests__/MerchantShell.test.jsx
• apps/admin/src/merchant/profile/MyMerchantProfile.jsx
• apps/admin/src/shared/lib/merchantApi.js
• apps/admin/src/shared/lib/__tests__/merchantApi.test.js
• services/api/auth/src/handlers/merchantHandlers.js
• services/api/auth/src/handlers/__tests__/merchantHandlers.test.js
• services/api/auth/src/routes/merchantSelf.js
• services/api/auth/src/routes/__tests__/merchantSelf.test.js
• tooling/scripts/check-shell-isolation.mjs
• tooling/scripts/lint-fixture-cross-zone.mjs

Renamed/moved (no logic change beyond import-path updates)

• All admin-only pages from apps/admin/src/components/ → apps/admin/src/admin/<sub>/
• All shared chrome from apps/admin/src/components/ → apps/admin/src/shared/components/
• Merchant tabs from apps/admin/src/components/merchants/tabs/ → apps/admin/src/merchant/tabs/ (drop "Tab" suffix)
• Merchant offer flows from apps/admin/src/components/merchants/tabs/Offer*.jsx and OffersList.jsx → apps/admin/src/merchant/offers/
• apps/admin/src/lib/*.js → apps/admin/src/shared/lib/*.js

Modified

• apps/admin/src/App.jsx — role fork, back-compat redirects, URL-mode handlers
• apps/admin/vite.config.mjs — path aliases
• apps/admin/vitest.config.mjs — path aliases (mirror)
• apps/admin/.eslintrc.json — import/no-restricted-paths rule
• apps/admin/package.json — eslint-plugin-import dep if not already present
• services/api/auth/src/routes/adminMerchants.js — becomes thin wiring; handlers extracted
• services/api/auth/src/middleware/auth.js — adds requireMerchant
• services/api/auth/src/index.js — mounts merchantSelfRoutes under /auth/merchant/me
• tooling/scripts/validate.js — wires the new check-shell-isolation + lint-fixture-cross-zone scripts

Deleted

• apps/admin/src/components/AdminDashboard.jsx (responsibility split into AdminShell + App.jsx)
• apps/admin/src/components/merchants/MerchantDetail.jsx
• apps/admin/src/components/merchants/MerchantsIndexRedirect.jsx
• apps/admin/src/components/__tests__/AdminDashboard.test.jsx (superseded by AdminShell.test.jsx)

Intentionally untouched

• apps/web/ — Lantern consumer app unchanged
• firestore.rules, storage.rules — no rule changes
• All Cloud Run / Cloudflare deployment workflows
• services/api/merchants/ — already merchant-accessible

Out of Scope (deferred)

• apps/merchant/ separate-app split — this PR sets up the prerequisite. Separate Vite project + Cloudflare target is a future move when independent deploys justify the cost.
• @lantern/ui shared package extraction — not needed inside one Vite project.
• Greenfield merchant dashboard / KPIs / activity feed — Q1's option (c). Merchant landing stays on Overview (today's read-only summary). Track via "Merchant home redesign" issue.
• Merchant self-onboarding (signup, billing, plan selection) — product decision; orthogonal to architecture.
• "View as merchant" admin impersonation — distinct from "admin enters merchant mode." Add when QA / support workflows need it.
• Multi-role users (single uid both admin AND merchant) — existing guards reject this state; spec doesn't change that.
• Merchant-side mutation endpoints beyond what's already wired — additive. Drop handlers into merchantHandlers.js, mount on /me, done. No architectural change required.
• Removing the back-compat redirects — ships in this PR; follow-up agent removes them ~2 weeks after merge.
• Visual differentiation between admin and merchant shells — both use the same design tokens. Visual distinction is a separate frontend-design pass.
• Per-page test coverage parity — out of scope; admin-side coverage isn't great today either.
• Non-Vite bundlers / deployment changes — Cloudflare Pages auto-deploy and Cloud Run deploys unchanged.

If the implementer thinks any of these are needed for the PR to ship, stop and re-confirm.