Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Draft 5.5 project layout plan + supersede notes on 5.4 plan
Damian Legawiec99d691a23cba
diff --git a/docs/plans/5.4-spree-starter-and-create-spree-app.md b/docs/plans/5.4-spree-starter-and-create-spree-app.mdindex 7911f062e0..8136c50c3c 100644--- a/docs/plans/5.4-spree-starter-and-create-spree-app.md+++ b/docs/plans/5.4-spree-starter-and-create-spree-app.md@@ -6,6 +6,10 @@**Author:** Damian + Claude**Last updated:** 2026-03-18+> **Partially superseded by `5.5-project-layout-and-dashboard.md`:**+> - `backend/` directory renamed to `api/` for new projects scaffolded on 5.5+. Existing 5.4 projects keep `backend/` and can opt in via `spree upgrade layout`.+> - `apps/admin/` reference for the future React admin (mentioned in this plan's Problem #5 and Design Details) is replaced by `apps/dashboard/`, matching the `@spree/dashboard` package name.+## SummaryReplace the monorepo `server/` directory with an independent `spree/spree-starter` GitHub template repository that serves as the single Rails app for all contexts: user projects, core development, CI, and Docker image releases. Update `create-spree-app` to always include `backend/` (cloned from spree-starter) alongside the storefront, and add a `spree eject` CLI command to switch from prebuilt Docker images to local builds. Simplify the release pipeline by eliminating the multi-Gemfile / multi-Dockerfile approach in favor of a single Gemfile with a `SPREE_PATH` env var conditional and gems published to RubyGems.diff --git a/docs/plans/5.5-project-layout-and-dashboard.md b/docs/plans/5.5-project-layout-and-dashboard.mdnew file mode 100644index 0000000000..6c64e919ad--- /dev/null+++ b/docs/plans/5.5-project-layout-and-dashboard.md@@ -0,0 +1,576 @@+# 5.5 Project Layout & Dashboard Scaffolding++**Status:** Draft+**Target:** Spree 5.5 (Dashboard Developer Preview)+**Depends on:** `5.4-spree-starter-and-create-spree-app.md` (shipped), `6.0-admin-spa.md`+**Author:** Damian + Claude+**Last updated:** 2026-05-31++## Summary++Ship the React dashboard as part of `create-spree-app` in 5.5 (Developer Preview) and align the generated project layout with the future API-only Rails role. The Rails app directory is renamed `backend/` → `api/` for all **new** projects scaffolded on 5.5+ — the name change is more honest the moment a second frontend exists (the dashboard), even though Rails still serves the legacy admin until 6.0. Existing projects are unaffected: they continue to work as-is, and can opt in to the new layout via `spree upgrade layout` whenever they want. The dashboard scaffolds into `apps/dashboard/` alongside the existing `apps/storefront/`, and a new `spree add dashboard` command lets existing projects bolt it on. By 6.0 GA the rename is well-trodden and the legacy `backend/` layout becomes unsupported.++## Problem++1. **`backend/` no longer describes the role.** Even in 5.5 the Rails app is already serving two distinct frontends (storefront and dashboard) plus background workers. Generic role names ("backend") stop working as soon as two frontends consume the API — "which backend?". In 6.0 the Rails app loses its admin UI entirely and becomes a thin REST API plus workers, making the name even more misleading.++2. **The 5.4 plan reserved `apps/admin/` for the future dashboard.** That name collides with the legacy Rails `spree/admin` engine and with `@spree/dashboard`, the package name used everywhere else in the monorepo. We should land on one name and use it consistently.++3. **No way to add the dashboard after the fact.** A user who skipped the dashboard at scaffolding time (or generated their project before the dashboard existed) has no command to bolt it on. They have to clone `spree/dashboard-starter` manually, mint API keys, write `.env.local`, and install deps — none of which is hard, but it's exactly the kind of glue `create-spree-app` already automates for the storefront.++4. **No upgrade path for existing 5.4 projects.** Anyone who generated a project with 5.4's `create-spree-app` has `backend/` baked into Dockerfiles, CI configs, and shell habits. Without a migration command, every user has to do the rename by hand when they want to align with the new layout.++## Key Decisions (do not deviate without discussion)++- **`api/` is the new name for the Rails app directory** in generated projects (not `backend/`, not `server/`). Pairs with `apps/dashboard/` + `apps/storefront/` — three peers, three roles.+- **`apps/dashboard/`** is the canonical location for the React SPA admin (not `apps/admin/`, not `packages/dashboard/`). Matches the `@spree/dashboard` package name and avoids legacy `spree/admin` collision. **Supersedes the `apps/admin/` reference in `5.4-spree-starter-and-create-spree-app.md`.**+- **`apps/` holds JS/TS deployables; `api/` stays at the root.** Don't move the Rails app under `apps/api/`. It's qualitatively different (different language, different runtime, different CLI surface via `spree console`/`spree logs`) and keeping it at the root signals "this is the core; the JS apps consume it."+- **The dashboard is optional, like the storefront.** Default to including it interactively; allow `--no-dashboard` / `--dashboard` flags and a non-interactive default for CI.+- **Dashboard ships from a new `spree/dashboard-starter` GitHub template repo,** following the same pattern as `spree-starter` and `storefront`. Not bundled into create-spree-app.+- **Rename ships day-one in 5.5 for *new* projects.** `npx create-spree-app` on 5.5+ produces `api/` directly. We don't ship 5.5 with the dashboard inside `backend/` only to rename in 6.0 — that'd give the Developer Preview audience a layout we know will change. Get it right once.+- **Existing projects are NOT auto-migrated in 5.5.** They keep `backend/` and continue to work. The CLI detects the layout per-command (see `detectApiDir` in Design Details). Users opt in to the rename via `spree upgrade layout` on their own schedule.+- **Dual-layout support is bounded.** 5.5 and the 5.x line support both layouts; 6.0 GA drops `backend/` detection. Users have a full minor-version cycle to run `spree upgrade layout` before it's required.+- **Two new CLI commands ship in 5.5:**+ - `spree add dashboard` — clone dashboard-starter into `apps/dashboard/`, mint API keys, write `.env.local`, install deps. Idempotent (re-running with `apps/dashboard/` present is a no-op with a warning).+ - `spree upgrade layout` — rename `backend/` → `api/`, rewrite compose files, README, CI, `.env`. Refuses to run with a dirty working tree. Commits as a single atomic commit.+- **`spree add dashboard` works on both layouts in 5.5.** No need to upgrade first — it detects whether the Rails dir is `backend/` or `api/` and configures accordingly. (`spree upgrade layout` is independent of `add dashboard`.)+- **5.5 release notes call out the rename for *new* projects only.** Existing-project users see no surprise — their CLI keeps working unchanged. The upgrade is presented as an optional alignment step, not a forced migration.++## Design Details++### Target generated layout (5.5, new projects)++```+my-shop/+├── api/ ← Rails (API + admin engine in 5.5, workers); renamed from backend/+│ ├── Gemfile+│ ├── Dockerfile+│ ├── config/+│ ├── app/+│ └── ...+├── apps/+│ ├── dashboard/ ← new: React SPA (Vite, @spree/admin-sdk) — Developer Preview in 5.5+│ │ ├── package.json+│ │ ├── vite.config.ts+│ │ ├── src/+│ │ └── .env.local ← VITE_SPREE_API_URL + admin secret key+│ └── storefront/ ← unchanged: Next.js (optional)+│ ├── package.json+│ └── ...+├── docker-compose.yml ← prebuilt image by default+├── docker-compose.dev.yml ← context: ./api (after eject)+├── package.json+├── README.md+├── .env ← SECRET_KEY_BASE, PORT+└── .gitignore+```++**Why `api/` at the root, not `apps/api/`:**+- Different language/runtime/deploy story than the JS apps.+- The CLI surfaces it as a singleton (`spree console`, `spree logs` → implicitly mean "the api").+- Visually signals the hub-and-spoke relationship: one API, multiple consumers.++### Why `api/` over `server/` or `backend/`++| Name | Reads as | TS-dev expectation | Verdict |+|---|---|---|---|+| `backend/` | "the other thing, opposed to frontend" | Generic, legacy-feeling; ambiguous once 2+ frontends exist | ❌ |+| `server/` | "a server doing some stuff" | Implies generality (SSR, websockets, etc.); doesn't tell you what's served | ❌ |+| `api/` | "this is the API surface" | Matches Vercel/Turborepo/T3 conventions for API-only services; instantly legible | ✅ |++Even in 5.5, where Rails still serves the legacy `spree/admin` engine, the *contract* exposed to JS consumers is the REST API. By 6.0 the admin engine is gone and the directory contents perfectly match the name. Sidekiq workers (webhook delivery, event processing) are part of that API surface from any external observer's perspective. The directory name should describe the role to the outside world, not the internal process model.++### Dual-layout detection (`detectApiDir`)++In 5.5 the CLI must work against both `backend/` (5.4 projects, unmigrated) and `api/` (new 5.5+ projects, or migrated 5.4 projects). One helper centralizes the detection so individual commands don't repeat the check.++```typescript+// packages/cli/src/context.ts (extension)++export type ApiDirName = 'api' | 'backend'++export function detectApiDir(projectDir: string): ApiDirName {+ if (fs.existsSync(path.join(projectDir, 'api'))) return 'api'+ if (fs.existsSync(path.join(projectDir, 'backend'))) return 'backend'+ throw new Error(+ 'Neither api/ nor backend/ found. Is this a Spree project?',+ )+}++// Extend ProjectContext+export interface ProjectContext {+ mode: 'docker'+ projectDir: string+ port: number+ apiDir: ApiDirName // ← new+}++export function detectProject(cwd: string = process.cwd()): ProjectContext {+ // ... existing checks ...+ return {+ mode: 'docker',+ projectDir: cwd,+ port,+ apiDir: detectApiDir(cwd),+ }+}+```++**Usage pattern:** every command that references the Rails directory uses `ctx.apiDir` instead of a hardcoded string. Example: `spree eject` builds `path.join(ctx.projectDir, ctx.apiDir)` and looks for `docker-compose.dev.yml` whose `context:` already matches whatever the project was scaffolded with (compose files don't need rewriting — they were written correctly at scaffold time).++**Deprecation timeline:**+- **5.5:** both layouts supported; new projects scaffold as `api/`; `spree upgrade layout` available.+- **5.x:** same. No CLI warning yet — users on `backend/` see no nag.+- **6.0 RC:** `spree dev` (and other commands) print a deprecation warning when `backend/` is detected, pointing to `spree upgrade layout`.+- **6.0 GA:** `detectApiDir` drops the `backend/` branch. Old-layout projects must run `spree upgrade layout` before any CLI command works.++### Dashboard starter repo (`spree/dashboard-starter`)++New GitHub template repository, mirroring the `spree-starter` and `storefront` pattern:++```+dashboard-starter/+├── package.json # depends on @spree/dashboard, @spree/admin-sdk+├── vite.config.ts # proxies /api/* to localhost:3000 in dev+├── tsconfig.json+├── biome.json+├── .env.example+├── .gitignore+├── README.md+├── index.html+├── public/+└── src/+ ├── main.tsx # renders <Dashboard /> from @spree/dashboard+ ├── plugins.ts # user's defineDashboardPlugin() registrations+ └── styles.css+```++The starter is intentionally minimal — `@spree/dashboard` is the actual app shell; the starter is the user's customization point for plugins, theming, and deployment config. Same boundary as `spree-starter` vs the Spree gems.++### `.env.local` generated for dashboard++```bash+VITE_SPREE_API_URL=http://localhost:3000+VITE_SPREE_ADMIN_API_KEY=sk_<minted-by-spree-add-dashboard>+```++The admin secret key is minted via the existing `spree api-key create --kind secret --scopes "admin:*"` plumbing during scaffolding (or on `spree add dashboard`). Users can rotate via `spree api-key revoke` + edit `.env.local` later.++### Scaffolding flow changes (`create-spree-app`)++**Prompts (interactive):**++```+✔ Project name … my-shop+✔ Include the storefront (Next.js)? … Yes+✔ Include the dashboard (React SPA admin)? … Yes ← new+✔ Start Docker services now? … Yes+```++**Flags (non-interactive):**++```bash+npx create-spree-app my-shop \+ --storefront \+ --dashboard \ # new+ --no-start+```++Defaults: dashboard included unless `--no-dashboard`. Matches the storefront default behavior.++**New scaffolding phases (after backend, before storefront):**++```typescript+// scaffold.ts (excerpt — new phase 2b: dashboard)+if (dashboard) {+ s.start('Downloading dashboard template...')+ await downloadDashboard(projectDir)+ s.stop('Dashboard template downloaded.')++ // Mint admin key (requires Rails to be up — defer if --no-start)+ if (options.start) {+ const adminKey = await mintAdminApiKey(projectDir)+ writeDashboardEnv(projectDir, port, adminKey)+ } else {+ writeDashboardEnv(projectDir, port, null) // placeholder, instruct user in README+ }++ s.start('Installing dashboard dependencies...')+ await installDashboardDeps(projectDir, options.packageManager)+ s.stop('Dashboard dependencies installed.')+}+```++Mirror file: `src/dashboard.ts` following `src/storefront.ts` shape exactly.++**Constants additions:**++```typescript+// src/constants.ts+export const DASHBOARD_PORT = 5173+export const DASHBOARD_REPO = 'https://github.com/spree/dashboard-starter.git'+// rename:+export const API_REPO = 'https://github.com/spree/spree-starter.git' // was BACKEND_REPO+```++### `spree add dashboard` command (new)++For existing projects that didn't include the dashboard at scaffolding time.++```typescript+// packages/cli/src/commands/add.ts+program+ .command('add <thing>')+ .description('Add an optional component to your project (dashboard, storefront)')+ .action(async (thing: string) => {+ const ctx = detectProject()++ switch (thing) {+ case 'dashboard':+ return addDashboard(ctx)+ case 'storefront':+ return addStorefront(ctx)+ default:+ console.error(`Unknown component: ${thing}`)+ process.exit(1)+ }+ })++async function addDashboard(ctx: ProjectContext) {+ // 1. Idempotency check+ const dashboardDir = join(ctx.projectDir, 'apps', 'dashboard')+ if (existsSync(dashboardDir)) {+ log.warn('apps/dashboard/ already exists. Nothing to do.')+ return+ }++ // 2. Clone starter+ await execa('git', ['clone', '--depth', '1', DASHBOARD_REPO, dashboardDir])+ rmSync(join(dashboardDir, '.git'), { recursive: true, force: true })++ // 3. Mint admin API key via Rails (containers must be running).+ // ctx.apiDir is 'api' or 'backend' — works for both 5.4 and 5.5+ projects.+ if (!(await isWebContainerRunning(ctx))) {+ log.info(`Starting ${ctx.apiDir} so we can mint an admin API key...`)+ await dockerCompose(['up', '-d'], ctx.projectDir)+ await waitForHealthy(ctx)+ }+ const adminKey = await mintAdminApiKey(ctx)++ // 4. Write .env.local (always reads/writes apps/dashboard/.env.local —+ // the dashboard talks to the API over HTTP, not over a filesystem path)+ writeDashboardEnv(ctx.projectDir, ctx.port, adminKey)++ // 5. Install deps (package manager detected from project root)+ const pm = detectPackageManager(ctx.projectDir)+ await execa(pm, ['install'], { cwd: dashboardDir, stdio: 'inherit' })++ // 6. Note — suggest the layout upgrade if user is still on backend/+ const note = [+ `Dashboard added at ${pc.bold('apps/dashboard/')}`,+ '',+ `Start it with:`,+ ` ${pc.cyan(`cd apps/dashboard && ${pm} run dev`)}`,+ '',+ `Then open ${pc.bold(`http://localhost:${DASHBOARD_PORT}`)}`,+ ]+ if (ctx.apiDir === 'backend') {+ note.push(+ '',+ pc.dim('Tip: align with the new layout via `npx spree upgrade layout`.'),+ )+ }+ p.note(note.join('\n'), 'Dashboard added!')+}+```++**Why no layout-upgrade gate:** the dashboard is a separate Node app that talks to Rails over HTTP. It doesn't care whether the Rails directory is `backend/` or `api/`. Forcing the rename first would be friction without benefit.++**Idempotency rules:**+- If `apps/dashboard/` exists → warn and exit cleanly (no-op).+- If `apps/dashboard/.env.local` is missing but the directory exists → write `.env.local` and exit (recovery mode). User can opt in by running `spree add dashboard --force` to regenerate.+- Minting a fresh admin key on each run is fine; old keys can be revoked via `spree api-key list/revoke`.++### `spree upgrade layout` command (new)++Renames `backend/` → `api/` and rewrites every file that references the old name.++```typescript+// packages/cli/src/commands/upgrade.ts+program+ .command('upgrade <target>')+ .description('Upgrade your project to a newer layout or version')+ .action(async (target: string) => {+ if (target !== 'layout') {+ console.error(`Unknown upgrade target: ${target}`)+ process.exit(1)+ }+ await upgradeLayout(detectProject())+ })++async function upgradeLayout(ctx: ProjectContext) {+ // 1. Refuse if already on new layout+ if (existsSync(join(ctx.projectDir, 'api'))) {+ log.warn('Project already uses the api/ layout. Nothing to do.')+ return+ }+ if (!existsSync(join(ctx.projectDir, 'backend'))) {+ log.error('No backend/ directory found. Is this a Spree project?')+ process.exit(1)+ }++ // 2. Refuse if working tree is dirty+ const dirty = await isGitDirty(ctx.projectDir)+ if (dirty) {+ log.error('Working tree has uncommitted changes.')+ log.info('Commit or stash before running upgrade so the rename is a clean diff.')+ process.exit(1)+ }++ // 3. Stop any running containers (compose paths will change)+ if (await isAnyContainerRunning(ctx)) {+ log.info('Stopping running containers...')+ await dockerCompose(['down'], ctx.projectDir)+ }++ // 4. Git mv (preserves history)+ await execa('git', ['mv', 'backend', 'api'], { cwd: ctx.projectDir })++ // 5. Rewrite text files with backend/ references+ const filesToRewrite = [+ 'docker-compose.yml',+ 'docker-compose.dev.yml',+ 'README.md',+ 'package.json',+ '.env',+ '.env.example',+ '.gitignore',+ 'CLAUDE.md',+ 'AGENTS.md',+ ...(await findCiWorkflows(ctx.projectDir)),+ ]+ for (const file of filesToRewrite) {+ const abs = join(ctx.projectDir, file)+ if (!existsSync(abs)) continue+ const original = readFileSync(abs, 'utf-8')+ const updated = rewriteBackendReferences(original)+ if (updated !== original) {+ writeFileSync(abs, updated)+ await execa('git', ['add', file], { cwd: ctx.projectDir })+ }+ }++ // 6. Stage everything and commit as one atomic commit+ await execa('git', ['add', '-A'], { cwd: ctx.projectDir })+ await execa('git', [+ 'commit',+ '-m',+ 'Upgrade project layout: backend/ → api/\n\nGenerated by `npx spree upgrade layout`.',+ ], { cwd: ctx.projectDir })++ p.note(+ [+ `Layout upgraded. Review the commit:`,+ ` ${pc.cyan('git show HEAD')}`,+ '',+ `To restart services with the new layout:`,+ ` ${pc.cyan('npx spree dev')}`,+ '',+ `Want the dashboard too? Run:`,+ ` ${pc.cyan('npx spree add dashboard')}`,+ ].join('\n'),+ 'Upgrade complete!',+ )+}++function rewriteBackendReferences(content: string): string {+ return content+ // docker-compose: context: ./backend → context: ./api+ .replace(/context:\s*\.\/backend(?=\s|$)/g, 'context: ./api')+ // Path references in scripts, README, CI: backend/ → api/+ .replace(/\bbackend\//g, 'api/')+ // Standalone "backend" word references in prose+ .replace(/\bbackend\b(?=\s+(directory|folder|Dockerfile|Gemfile))/g, 'api')+}+```++**Safety:**+- **Dirty tree refuses.** No way to lose uncommitted work to an automated rename.+- **Single commit.** User can `git reset --hard HEAD~1` to undo.+- **Stops containers first.** Avoids docker-compose getting confused mid-rename.+- **`git mv` preserves history.** Doesn't matter for compose paths but matters for anyone who customized files under `backend/`.+- **Does not touch `apps/`, `node_modules/`, `.git/`** or anything outside the predefined file list.++**What it does NOT do:**+- Doesn't run `git push` — user reviews and pushes themselves.+- Doesn't restart services — the success note tells them to.+- Doesn't update upstream dependencies. Pure rename, nothing else.++### CLI surface summary++| Command | Purpose | New in 5.5? |+|---|---|---|+| `spree dev` | Start services | No (uses `ctx.apiDir` internally) |+| `spree stop` | Stop services | No |+| `spree eject` | Switch to local Rails build | No (uses `ctx.apiDir` internally) |+| `spree console` | Rails console in api/backend container | No |+| `spree logs [worker]` | Stream logs | No |+| `spree update` | Pull latest image + migrate | No |+| `spree seed` | Run seeds | No |+| `spree sample-data` | Load sample data | No |+| `spree user create` | Create admin user | No |+| `spree api-key create/list/revoke` | Manage API keys | No |+| `spree init` | Bootstrap a fresh project | No |+| `spree add dashboard` | Add dashboard to existing project (works on both layouts) | **Yes** |+| `spree add storefront` | Add storefront to existing project | **Yes** (parity) |+| `spree upgrade layout` | Rename `backend/` → `api/` | **Yes** |++### File rename map (across the toolchain)++The change touches several packages. Single-pass refactor:++**`packages/create-spree-app/`:**+- `src/backend.ts` → `src/api.ts` (function `downloadBackend` → `downloadApi`)+- `src/constants.ts` — `BACKEND_REPO` → `API_REPO`; add `DASHBOARD_REPO`, `DASHBOARD_PORT`+- `src/scaffold.ts` — every `backend/` path → `api/`; new dashboard phase+- `src/templates/readme.ts` — all references; add Dashboard section+- `src/templates/claude-md.ts`, `env.ts`, `gitignore.ts`, `package-json.ts` — same rename+- `src/prompts.ts` — add dashboard prompt+- `src/types.ts` — add `dashboard: boolean` to `ScaffoldOptions`+- **New:** `src/dashboard.ts` (mirror of `src/storefront.ts`)+- `tests/` — update fixtures and assertions++New projects scaffold straight to `api/`. There is **no dual-layout output mode** in `create-spree-app` — it's "new projects always use `api/`". The dual-layout work is entirely in the CLI (which has to handle pre-existing 5.4 projects).++**`packages/cli/`:**+- **`src/context.ts`** — add `detectApiDir(projectDir)` helper; extend `ProjectContext` with `apiDir: 'api' | 'backend'`; `detectProject()` populates it.+- `src/commands/eject.ts` — replace hardcoded `'backend'` with `ctx.apiDir`. Error message: `No ${ctx.apiDir}/ directory found.`+- `src/commands/init.ts` — same pattern.+- Any other command that references the Rails directory by name — same pattern.+- **New:** `src/commands/add.ts` (with `addDashboard`, `addStorefront`).+- **New:** `src/commands/upgrade.ts` (with `upgradeLayout`).+- `src/index.ts` — register `add` and `upgrade` commands.+- `src/lib/` — new helpers: `mintAdminApiKey`, `isGitDirty`, `findCiWorkflows`, `rewriteBackendReferences`, `detectPackageManager`, `waitForHealthy`.++**`spree/spree-starter` (separate repo):**+- No structural changes needed — it's the contents of `api/`, not the directory name.+- README references to "the backend" → "the API server" or just "this app".++**`spree/dashboard-starter` (new repo):**+- Created from scratch following the shape above.+- Pinned to `@spree/dashboard@^5.5.0-next` and `@spree/admin-sdk@^5.5.0-next` (Developer Preview dist-tag), rolling forward to `^6.0.0` at 6.0 GA.++## Migration Path++All phases ship in **5.5**. The dashboard ships as Developer Preview alongside `@spree/admin-sdk@next`. Versioning rolls forward to `^6.0.0` at 6.0 GA.++### Phase 1: Add dual-layout detection to CLI++1. Implement `detectApiDir(projectDir)` in `packages/cli/src/context.ts`.+2. Extend `ProjectContext` with `apiDir: 'api' | 'backend'`.+3. Refactor existing commands (`eject`, `init`, anything that names the Rails dir) to read `ctx.apiDir` instead of a hardcoded string.+4. Unit test against fixture projects for both layouts.+5. **Ship this first** — it's the prerequisite for everything else. Without it, the rename in Phase 2 would break existing-project CLI usage.++### Phase 2: Create `spree/dashboard-starter` repo++1. Bootstrap from `packages/dashboard/` as a reference (the deployable app shell). The starter is a *consumer* of `@spree/dashboard`, not a fork of it.+2. Write minimal Vite config that proxies to `localhost:3000` in dev. The proxy path is irrelevant to the Rails directory name — it's an HTTP URL.+3. Write README covering: dev workflow, building plugins via `defineDashboardPlugin`, deploying.+4. Add CI: typecheck, build, e2e smoke test against a Dockerized Spree backend.+5. Mark as a GitHub template repository.++### Phase 3: Rename `backend/` → `api/` in create-spree-app (new projects only)++1. Update all source files per "File rename map" above.+2. Update tests — fixtures, snapshots, integration assertions.+3. Update README of `create-spree-app` package itself.+4. Add changeset (minor bump — output layout changes, but no API/import contract is broken; existing CLI install continues to work against either layout).++### Phase 4: Add dashboard scaffolding to create-spree-app++1. Implement `src/dashboard.ts` mirroring `src/storefront.ts`.+2. Add prompt + flag in `src/prompts.ts` and `src/index.ts`.+3. Add `mintAdminApiKey` helper (talks to running Rails container via `spree api-key create`).+4. Update `src/scaffold.ts` to invoke dashboard phase after api, before storefront.+5. Update README template with Dashboard section.+6. Update tests.++### Phase 5: Add `spree add` and `spree upgrade` commands to CLI++1. Implement `commands/add.ts` with `addDashboard` and `addStorefront`.+2. Implement `commands/upgrade.ts` with `upgradeLayout`.+3. Add helpers: `isGitDirty`, `findCiWorkflows`, `rewriteBackendReferences`, `detectPackageManager`, `mintAdminApiKey`, `waitForHealthy`.+4. Register both commands in `src/index.ts`.+5. Update CLI README + `--help` examples.+6. Add unit tests for `rewriteBackendReferences` (pure function, easy to cover).+7. Add integration test that runs `upgrade layout` against a fixture project.++### Phase 6: Documentation++1. Update `docs/developer/getting-started/` to show new layout (use `api/` in examples).+2. Update `docs/developer/customization/` references.+3. Add a release-notes section in the 5.5 release notes:+ - "Dashboard Developer Preview" (the headline)+ - "New project layout: `api/`" (call out for newcomers)+ - "Existing projects: optional upgrade via `spree upgrade layout`" (set expectations — not forced)+4. Update `5.4-spree-starter-and-create-spree-app.md` with a banner noting the 5.5 rename and pointer to this plan.++### Phase 7: Smoke test the full flow++Manual QA checklist:+- [ ] `npx create-spree-app fresh --dashboard --storefront` produces working project with `api/` + `apps/dashboard/` + `apps/storefront/`.+- [ ] `npx create-spree-app fresh --no-dashboard --no-storefront` produces api-only project (single `api/` directory at root).+- [ ] `npx create-spree-app fresh --dashboard --no-storefront` works.+- [ ] In a 5.4-generated project (with `backend/`): all existing commands (`spree dev`, `spree console`, `spree eject`) keep working unchanged.+- [ ] In the same 5.4 project: `npx spree add dashboard` clones, mints key, installs, dashboard boots and connects to API — without forcing the layout upgrade first.+- [ ] In the same 5.4 project: `npx spree upgrade layout` succeeds, commit looks clean, `npx spree dev` boots after rename.+- [ ] After upgrade: `apps/dashboard/.env.local` still points at the API correctly (no rewrite needed — it's an HTTP URL).+- [ ] `npx spree upgrade layout` refuses on a dirty tree.+- [ ] `npx spree upgrade layout` is a no-op on an already-upgraded project.+- [ ] `npx spree add dashboard` is idempotent (second run is a no-op).+- [ ] In 5.5 RC: confirm no deprecation warning fires on `backend/` layouts. (Warnings ship in 6.0 RC, not 5.5.)++## Constraints on Current Work++- **Stop using `apps/admin/` in new docs, comments, or plans.** The dashboard lives at `apps/dashboard/`. The 5.4 plan's `apps/admin/` reference is superseded by this plan.+- **Use `api/` in new user-facing documentation that targets 5.5+.** For docs that span 5.4 and 5.5 (release notes, migration guides), either say "the Rails directory" generically or call out both names explicitly. Don't hardcode `backend/` as the permanent name.+- **Every new CLI command that touches the Rails directory must use `ctx.apiDir`,** never a hardcoded `'backend'` or `'api'` string. This is non-negotiable for 5.5 because both layouts coexist.+- **New `create-spree-app` templates and prompts must read the dashboard flag** even if dashboard scaffolding isn't fully wired up yet — so the option exists from the moment the dashboard-starter repo ships.+- **The `@spree/dashboard` package must keep its current name.** Renaming it would invalidate the entire "dashboard" naming convergence.+- **Admin API key minting needs to work with both publishable+secret separation.** When `spree add dashboard` mints a key for the dashboard, it must be a **secret** key with admin scopes — not a publishable key (which is for the storefront).+- **`spree upgrade layout` must not run automatically as part of any other command.** Even if a user runs `spree update` and we know they're on `backend/`, do not silently rename. Layout migration is opt-in only.++## Open Questions++1. **Should `spree add dashboard` write the admin secret key to `.env.local` plaintext?** The pattern matches what the storefront already does for its publishable key in `.env.local`, but a secret key is more sensitive. Options:+ - (a) Plaintext in `.env.local` (current proposal — matches storefront pattern, simple).+ - (b) Print to console only, instruct user to paste into `.env.local` manually (safer, more friction).+ - (c) Use an OS keychain integration (over-engineered for a dev tool).+ - Leaning toward (a) — `.env.local` is already gitignored, and the dev experience matters. Add a comment in the file warning users not to commit it even if their `.gitignore` is missing the entry.++2. **`spree upgrade layout` and user customizations.** If the user has added files under `backend/` (custom decorators, gems, etc.), `git mv backend api` moves them along. But if they've referenced `backend/` *paths* in their own code (e.g., a script that does `cd backend && rails c`), we won't catch that. Should `spree upgrade layout`:+ - (a) Scan and warn about likely user references (grep for `\bbackend/` in user files), or+ - (b) Just do the rename and leave it to the user.+ - Leaning toward (a) with a "review these files manually" report at the end.++3. **`spree add storefront` symmetry.** This plan proposes it for symmetry with `add dashboard`, but the storefront has been around since 5.4. Is there demand for adding the storefront to an existing api-only project, or is it always present? If demand is low, we could ship `add dashboard` first and defer `add storefront`.+ - Leaning toward shipping both — symmetry matters for the mental model ("if I can add a dashboard, I can add a storefront").++4. **Should `spree upgrade` be a single command with subcommands or `spree upgrade <target>`?** This plan uses `spree upgrade layout`, leaving room for `spree upgrade gems`, `spree upgrade image`, etc. later. Alternative: `spree upgrade --layout` flag-style. Subcommand form scales better.++5. **Does `mintAdminApiKey` need a stable name/comment so users can identify it later?** When `spree add dashboard` runs, the minted key shows up in `spree api-key list`. Suggest naming it `"dashboard (created by spree add dashboard)"` or similar so users know what it's for and don't accidentally revoke it.++6. **When exactly does `backend/` support get dropped?** The plan says "by 6.0 GA". Open: do we want a 5.6 deprecation warning step in between, or jump straight from "silent dual-support in 5.5" to "warning in 6.0 RC" to "removed in 6.0 GA"? The 5.5/6.0 cycle is short enough that one warning step at 6.0 RC is probably enough.++## References++- **Supersedes (partial):** `docs/plans/5.4-spree-starter-and-create-spree-app.md` — specifically the `apps/admin/` reference (now `apps/dashboard/`) and the `backend/` directory name (now `api/` in 5.5+ generated projects).+- **Depends on:** `docs/plans/6.0-admin-spa.md` — defines `@spree/dashboard`, `@spree/dashboard-core`, `@spree/dashboard-ui` packages and the `defineDashboardPlugin` API consumed by the starter.+- **Related:** `docs/plans/5.5-admin-api-key-scopes.md` — scope schema for the secret key minted by `spree add dashboard`.+- **Related:** `docs/plans/5.5-admin-auth-cookie-refresh.md` — auth model the dashboard uses against the API.+- Current `packages/create-spree-app/` — source layout to modify.+- Current `packages/cli/src/commands/eject.ts` — pattern for new commands; needs `ctx.apiDir` refactor.+- Current `packages/cli/src/context.ts` — extended with `detectApiDir` and `apiDir` field on `ProjectContext`.+- `spree/spree-starter` repo — existing template, no structural change needed.+- **New repo to create:** `spree/dashboard-starter` — GitHub template for `apps/dashboard/` contents.