# Multi-Frontend Consolidation Strategy

This document records the intentional rationale for having multiple showcase shells in this repo, which shell each one replaces, and how packages target them during the transition.

> This is a transition-period strategy document. Once the rollouts below are complete, expect this doc to be updated or retired.

## Why multiple shells exist

Showcase is in the middle of **consolidating several external frontends into this repo** so they are built, deployed, versioned, and tested alongside the integration packages that back them. The fan-out in `showcase/` is intentional: each shell is the target replacement for a distinct external property, and they co-exist until their respective rollouts cut over.

The alternative — a single super-shell that hosts every audience — was rejected because the existing external frontends each have a different visual language, different audience framing, and different routing/embed conventions. Merging them into one shell would either lose each identity or require runtime mode switching that obscures what's actually rendered at a given URL.

## Current shells and their roles

| Directory          | Package name                           | Role                                                                                  | Status                         |
| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------ |
| `shell/`           | `@copilotkit/showcase-shell`           | Public showcase integrations browser at **showcase.copilotkit.dev**. Canonical today. | Production                     |
| `shell-dojo/`      | `@copilotkit/showcase-shell-dojo`      | Styled like the external ag-ui Dojo. Target replacement for the ag-ui Dojo property.  | Deployed (rollout in progress) |
| `shell-docs/`      | `@copilotkit/showcase-shell-docs`      | Docs-forward shell for the `docs.copilotkit.dev` consolidation.                       | Deployed (rollout in progress) |
| `shell-dashboard/` | `@copilotkit/showcase-shell-dashboard` | Internal feature × integration grid (ops / QA audience).                              | Internal                       |

All shells:

- Consume the same `shared/` registry / constraints / manifest schema
- Pull from the same `registry.json` (generated by `scripts/generate-registry.ts`)
- Embed package demos via **iframe pointing at `integration.backend_url + demo.route`** (each package's own deployed Next.js app) — they do not import package code

They differ in chrome, nav, and audience framing, not in the underlying demo surface.

### `shell/` — public integrations browser

The canonical public site. Routes under `src/app/`:

- `integrations/` — list and per-slug profile, plus `[slug]/[demo]/page.tsx` with Preview / Code / Docs tabs
- `docs/[[...slug]]/` — MDX docs served from `src/content/docs/`
- `ag-ui/[[...slug]]/` — ag-ui reference content
- `matrix/`, `reference/` — matrix and reference surfaces

Build pipeline runs `generate-registry.ts` + `bundle-demo-content.ts` + `bundle-starter-content.ts` + `generate-search-index.ts` before `next build`. Docker image `showcase-shell`, Railway service `40eea0da-6071-4ea8-bdb9-39afb19225ec`.

### `shell-dojo/` — Dojo replacement

A single-page Dojo-style viewer (integration selector + demo list + preview iframe + code pane) styled to match the external ag-ui Dojo. This is **not abandoned spike or cleanup waste** — it is the rollout vehicle for replacing the external ag-ui Dojo site with an in-repo shell fed by the same registry every other showcase surface uses. Reference visuals are kept at `shell-dojo/agent-notes/reference-dojo.png` (external Dojo target) and `shell-dojo/agent-notes/v-final-handcrafted.png` (current iteration).

Built standalone (no monorepo scripts), Docker image `showcase-shell-dojo`, Railway service `7ad1ece7-2228-49cd-8a78-bddf30322907`. CI builds both shells independently in `.github/workflows/showcase_deploy.yml`.

### Adding future shells

The expected pattern for any additional consolidation target:

1. New directory at `showcase/<shell-name>/` with its own `package.json`, `Dockerfile`, `next.config.ts`
2. Consume `shared/` registry + `data/registry.json` generated by `scripts/generate-registry.ts`
3. Add a matching entry in `.github/workflows/showcase_deploy.yml` (`workflow_dispatch` option, change-detection filter, build-matrix entry) with its own Railway service id
4. Update this document with the target external property, deploy URL, and rollout status
5. If the shell needs its own demo-content bundling, extend `scripts/bundle-demo-content.ts` rather than forking it

## Rollout order

1. **ag-ui Dojo → `shell-dojo/`** (target #1, in progress).
   - Build in-repo against the live reference (`agent-notes/reference-dojo.png`)
   - Deploy Railway service `7ad1ece7-2228-49cd-8a78-bddf30322907` continuously from `main`
   - Visual parity pass against the reference screenshot
   - Domain cutover: point the external Dojo domain at the Railway service (see Open Questions)
   - Archive / redirect the external Dojo repo
2. **Further consolidations** (TBD). Any other external frontend that is semantically a view over the showcase registry is a candidate. Per-shell criteria:
   - Audience and visual language distinct enough that folding into `shell/` would lose identity
   - Currently lives outside this repo (the point of this exercise is consolidation)
   - Can be expressed as a view over the existing registry, or the registry schema can be extended to support it

Order is driven by which external property is most worth consolidating next — not by code readiness in this repo.

## Per-package shell selection

**There is currently no explicit shell-selection field on packages.** The relationship is one-to-many in the other direction: every shell can embed every package.

- **At runtime, in every shell:** each integration package is embedded via `<iframe src={integration.backend_url + demo.route}>`. Both `shell/` (`src/app/integrations/[slug]/[demo]/page.tsx`) and `shell-dojo/` (`src/app/page.tsx`) do this using the exact same `backend_url` and `route` fields from `manifest.yaml`. Which shell a user sees is determined by which **domain** they visit, not by anything on the package.
- **For per-package E2E:** tests in `packages/<slug>/tests/e2e/` run against the **package's own dev server** on `http://localhost:3000/demos/<id>` — not against any shell. `scripts/run-e2e-with-aimock.sh <slug>` starts aimock + the package's `pnpm dev` + Playwright; no shell is involved. See `QA-COVERAGE.md` for the current per-package/shared E2E split.
- **For shared E2E** (`scripts/__tests__/e2e/`): these target whatever is running at `BASE_URL` (defaults to `http://localhost:3000`). The starter hero tests (`starter-e2e.spec.ts`) expect the starter app; demo tests (`demo-e2e.spec.ts`) expect a package dev server. Again, no shell is mounted.
- **`NEXT_PUBLIC_BASE_URL`** on packages points at `showcase.copilotkit.dev` for production links back to the canonical shell. It does not gate which shell embeds a given demo.

**Implication:** as long as a package's `manifest.yaml` is valid and its backend is deployed with `deployed: true`, both shells pick it up automatically on the next `generate-registry.ts` run. No per-package change is required to appear in a new shell.

**If per-package shell targeting is ever needed** (e.g., a package should only appear in Dojo-replacement but not the canonical browser), this will require a new manifest field — something like `shells: ["shell", "shell-dojo"]` — plus a filter in each shell's registry consumer. That structural change is not in place today.

## Open questions

- **Domain / DNS cutover plan for ag-ui Dojo replacement.** Which domain does `shell-dojo/` land on, and is the external Dojo repo archived or redirected on cutover?
- **Shared vs. per-shell content.** `shell/` has substantial MDX docs under `src/content/`; `shell-dojo/` has none. When we add a third shell, is documentation shell-specific or hoisted into `shared/`?
- **Visibility filtering.** Do we ever need a package to appear in one shell but not another? If yes, add a manifest field now rather than after the second rollout makes the lack of one painful.
- **`extract-starter` and preview capture.** Preview capture scripts assume the `shell/` layout (`showcase/shell/public/previews/`, `showcase/shell/src/data/registry.json`). When a future shell wants previews, decide whether to hoist these assets into `shared/` or dual-write.
- **E2E strategy once shells proliferate.** Per-package E2E still tests the package dev server directly, which is correct. But do we want shell-level E2E (iframe load, nav, search) per shell, and if so, where do those specs live?
