Migration Roadmap

This is the active implementation roadmap for the BluntDashboard migration program.

It replaces the earlier compressed cutover sketch as the main execution baseline. The older Delivery Plan remains useful as a cutover-oriented summary, but this roadmap is the source of truth for what gets built, in what order, and what counts as done.

Roadmap rules

The roadmap is completion-based, not date-based.
A phase closes only when its exit gate is met.
Subprojects are defined by Subsystem Topology, not by ad hoc file grouping.
Every phase should land through small patch trains that obey Change Topology.
The old system stays live until the production cutover gate is passed.

Patch-series model

The roadmap is not only a phase plan. It is also the default patch-series plan.

Each subproject should land as a series of topology-aware PRs, not as one long-lived branch.
The default cross-plane ordering is DATA -> ORCH -> DOM -> EXP -> PLAT/GOV.
If a subproject only touches one plane, keep the series inside that plane and prefer leaf subsystem IDs.
If a later patch depends on an earlier one, do not merge it first just because the code is ready.
Stark sessions and PR drafts should be created per patch step, not per whole phase.

Default patch trains by subproject

Subproject	Default patch-series order
Foundation and Governance	`GOV.scenarios-and-architecture` -> `GOV.runbooks-and-migration` -> `PLAT.deployment-and-environment` -> `PLAT.observability`
Data Backbone	`DATA.contracts-and-schema` -> `DATA.domain-store` -> `DATA.analytics-store` -> `GOV.scenarios-and-architecture`
Ingest and Analytics Fabric	`DATA.contracts-and-schema` -> `ORCH.shopify-sync` -> `DATA.analytics-store` -> `PLAT.observability`
Performance and Taxonomy Vertical	`DATA.contracts-and-schema` -> `DOM.performance-intelligence` -> `DOM.taxonomy-attribution` -> `EXP.performance-workbench` -> `GOV.scenarios-and-architecture`
Combo and Asset Vertical	`DATA.contracts-and-schema` -> `DOM.combo-operations` -> `DOM.asset-redundancy` -> `ORCH.asset-and-export-jobs` -> `EXP.creative-workbench`
Fulfillment Vertical	`DATA.contracts-and-schema` -> `DOM.fulfillment-operations` -> `ORCH.casestry-and-release` -> `EXP.fulfillment-workbench` -> `PLAT.observability`
Shell and Auth Cutover	`PLAT.identity-and-access` -> `EXP.shell` -> `PLAT.deployment-and-environment` -> `GOV.runbooks-and-migration`
Production Cutover	`PLAT.deployment-and-environment` -> `PLAT.observability` -> `GOV.runbooks-and-migration`

Program structure

Subproject	Primary subsystems	Mission	Key deliverables
Foundation and Governance	`GOV.*`, `PLAT.deployment-and-environment`, `PLAT.observability`	Make the migration executable and governable	docs site as architecture source of truth, subsystem labels/PR rules, reproducible monorepo/toolchain bootstrap, Stark control-plane baseline, non-prod deployment skeleton
Data Backbone	`DATA.domain-store`, `DATA.analytics-store`, `DATA.contracts-and-schema`	Establish the target data model and migration-safe contracts	Drizzle schema, dbmate migration flow, PlanetScale branch strategy, R2 archive conventions, contract definitions for API and jobs
Ingest and Analytics Fabric	`ORCH.shopify-sync`, `DATA.analytics-store`, `PLAT.observability`	Consolidate ingestion, refresh, and replay behavior	Shopify client module, bulk sync pipeline, mart refresh jobs, watermarks, archives, run history, parity queries
Performance and Taxonomy Vertical	`DOM.performance-intelligence`, `DOM.taxonomy-attribution`, `EXP.performance-workbench`	Cut over the analytics and taxonomy workflows end-to-end	Worker endpoints, migrated frontend flows, scenario acceptance pack, parity signoff for analytics workflows
Combo and Asset Vertical	`DOM.combo-operations`, `DOM.asset-redundancy`, `ORCH.asset-and-export-jobs`, `EXP.creative-workbench`	Cut over creative testing and asset-management workflows	combo routes/jobs, asset ingest pipeline, dedupe behavior, retry/replay behavior, migrated creative workbench
Fulfillment Vertical	`DOM.fulfillment-operations`, `ORCH.casestry-and-release`, `EXP.fulfillment-workbench`	Cut over supplier and fulfillment operations	order lookup, CSV/export jobs, monitoring/reconciliation, webhook/release flows, fulfillment workbench parity
Shell and Auth Cutover	`EXP.shell`, `PLAT.identity-and-access`, `PLAT.deployment-and-environment`	Replace the old app shell and auth plane	Access-based auth, frontend shell pointed at Workers, Pages deployment path, legacy auth removal
Production Cutover	`PLAT.*`, `GOV.runbooks-and-migration`	Move real traffic safely and retire the old stack	cutover checklist, rollback drills, production alerting, runbooks, hold period, decommission plan

Phase 0: Foundations

Status: In progress

Goal: Make the migration buildable, reviewable, and reproducible before major runtime changes start landing.

Primary subprojects: Foundation and Governance

Deliverables

Arcadia-grounded architecture reference in docs/
canonical subsystem IDs and GitOps label topology
repo-local skills and PR SOPs for humans and agents
mise + just bootstrap path for the repo and sibling execution backends
project-oriented monorepo scaffold rooted at cmd/, pkg/, infra/, etc/
pnpm workspace + local-package Vite+ for JS/TS/Node surfaces
Stark baseline: durable runs, worktree/session materialization, Dagger handoff, Podman-backed Dagger execution, OpenShell bridge on Podman

Exit gate

a fresh machine or sandbox can run mise install and just bootstrap
just app-check, just docs-build, and Stark doctor paths pass
PRs can be classified by subsystem, patch class, and labels without ambiguity

Phase 1: Platform Backbone

Status: Planned

Goal: Stand up the target runtime substrate in non-production so vertical work stops depending on the old Express/Supabase hosting path.

Primary subprojects: Foundation and Governance, Data Backbone

Deliverables

dashboard-api Worker skeleton deployed to non-prod
ingest Worker skeleton deployed to non-prod
Pages preview path for the frontend
PlanetScale database, branch strategy, and migration workflow
Hyperdrive, R2, Queue, Cron, and secret/binding setup in Wrangler
health endpoints and basic observability/telemetry wiring
Access application configured for staff auth in non-prod

Exit gate

all target runtimes deploy successfully in non-prod
health checks are green end-to-end
DB migrations run repeatably in non-prod
Access-authenticated requests reach Worker endpoints successfully

Phase 2: Data and Ingest Parity

Status: Planned

Goal: Make the new data plane trustworthy before frontends or domain cutovers depend on it.

Primary subprojects: Data Backbone, Ingest and Analytics Fabric

Deliverables

Drizzle schema covering operational tables and analytics structures
consolidated Shopify client module
bulk sync pipeline with watermarking and retry semantics
mart refresh process replacing manual materialized-view refreshes
JSONL archival to R2 and replay tooling/runbooks
parity queries for raw counts, top products, classifications, tag coverage, and asset linkage

Exit gate

core parity checks are within agreed tolerance
ingest runs are queryable and replayable
no critical workflow depends on manual sync triggers anymore

Phase 3: Performance and Taxonomy Vertical

Status: Planned

Goal: Move the analytics-heavy staff workflows onto the new stack first, because they exercise the deepest parts of the new data plane.

Primary subprojects: Performance and Taxonomy Vertical

Deliverables

performance metrics endpoints on dashboard-api
tag analytics and classification behavior ported out of old RPC/stored-proc paths
designer assignment and tag-group APIs on the new stack
performance workbench UI pointed at Worker endpoints
scenario-level acceptance checks for performance, analytics, tag classification, tag groups, and designer assignment

Exit gate

staff can complete performance and taxonomy workflows against the new stack in non-prod
old and new outputs match closely enough for signoff

Phase 4: Combo and Asset Vertical

Status: Planned

Goal: Move creative workflow state and asset redundancy flows onto the new runtime and job fabric.

Primary subprojects: Combo and Asset Vertical

Deliverables

combo logs/templates/suggestions APIs on dashboard-api
combo import and suggestion generation jobs on ingest
asset ingest pipeline, dedupe semantics, and artifact linkage on the new stack
creative workbench UI switched to the new APIs/jobs
retry/replay runbooks for asset and combo job failures

Exit gate

combo workflows run end-to-end on the new stack
asset ingest and redundancy flows are observable, retryable, and no longer depend on Supabase Edge Functions

Phase 5: Fulfillment Vertical

Status: Planned

Goal: Move supplier and fulfillment-critical flows after the data and asset substrate is stable.

Primary subprojects: Fulfillment Vertical

Deliverables

order lookup and fulfillment monitoring APIs on dashboard-api
CSV generation and related exports on ingest
Casestry webhook/release/reconciliation behavior moved into the target workflow fabric
fulfillment workbench UI switched to the new stack
operational alerts and rollback notes for fulfillment-sensitive jobs

Exit gate

fulfillment and supplier workflows run on the new stack with validated outputs
webhook/reconciliation flows are observable and replayable

Phase 6: Shell and Auth Cutover

Status: Planned

Goal: Remove the legacy app shell assumptions once all major verticals have viable replacements.

Primary subprojects: Shell and Auth Cutover

Deliverables

frontend shell pointed at Worker endpoints by default
Access-based auth in place for all staff flows
Supabase Auth and Passport paths removed from the active UI/runtime
Pages deployment path used for preview and staging validation
end-to-end UAT pack across Ops, Creative, Fulfillment, and Design workflows

Exit gate

all primary staff workflows run through the new shell and auth plane
no production-critical route depends on legacy auth/session behavior

Phase 7: Production Cutover and Decommission

Status: Planned

Goal: Move production traffic with explicit rollback posture, then retire the old stack only after the hold period.

Primary subprojects: Production Cutover

Deliverables

production cutover checklist
rollback-tested DNS/runtime switch plan
live alerting and operational dashboards
runbooks for sync validation, replay, ingest failure handling, and incident response
old stack hold-period policy and decommission checklist

Exit gate

production traffic is stable on the new system
rollback triggers were not hit during the hold period
old infrastructure can be decommissioned without losing required recovery paths

Subproject dependencies

The default dependency chain is:

Foundation and Governance
Platform Backbone
Data and Ingest Parity
Performance and Taxonomy Vertical
Combo and Asset Vertical
Fulfillment Vertical
Shell and Auth Cutover
Production Cutover and Decommission

Some work can overlap, but only after the upstream substrate is real.

Performance/Taxonomy should not cut over before data parity exists.
Combo/Assets should not cut over before the workflow fabric and data contracts are stable.
Fulfillment should not cut over before the workflow and asset layers are trustworthy.
Shell/Auth cutover should happen after the major verticals have proven replacements.

How to use this roadmap

Use the roadmap to decide what to build next.
Use Change Topology to decide how to slice each phase into PRs.
Use Subsystem Topology to choose the right subproject and owner surface.
Treat each deliverable as an acceptance artifact, not just an activity list item.

The roadmap should evolve as phases close and new blockers are discovered, but it should stay phase- and deliverable-oriented rather than drifting into a task dump.