# Domain-first Migration Waves > Program: `ARCH.FullProjectSeniorCleanArchitecture` > > Rule: one independently reversible ownership change per wave. A later wave does not > start while an earlier wave has an unexplained regression. ## 1. Global wave contract Every wave records: - exact scope and forbidden scope; - pre-change Git status classification; - current public contracts; - files moved/created/compatibility paths; - focused and full test evidence; - browser/API/Socket/cron evidence as applicable; - generated-artifact status; - rollback patch or import switch; - final status `COMPLETE`, `PARTIAL`, or `BLOCKED`. No wave combines schema migration, UI redesign, API contract change, and architecture movement. ## 2. Completed baseline waves ### Wave A — editor/generated hygiene Status: complete. Tracked `.DS_Store` files were removed, Postman metadata was kept clean, and screenshot evidence remains ignored. ### Wave B — prior dashboard replacement proof Status: complete. The 27 deleted horizontal dashboard files have vertical replacements, zero runtime imports, route/middleware snapshots, and green record-backed browser QA. The closing status line in the historical Wave B document is stale; its final metrics and current repository tests establish the completed baseline. ## 3. Wave 0 — architecture blueprint Scope: - full ownership inventory; - target module structure; - dependency and compatibility rules; - dead-code register; - API/dashboard/socket/lint guides; - risk and rollback plans. Runtime result: complete as the approved blueprint baseline. Current blueprint/foundation exit-gate status: `COMPLETE`. The post-migration full suite reports 1,085/1,085 passing. The Auction schema is frozen and verified unchanged. Whole-program status remains `PARTIAL`: the browser smoke has no runtime, overflow, network, console, CSRF, image, ID, theme, or table-alignment failures, but it records 28 pre-existing intentional Dashboard Home line-clamps. The detector is not relaxed and the frozen Home UI is not changed inside this architecture wave. High-risk domain ownership waves also remain independently gated below. ### Wave 0.1 — baseline contract reconciliation Status: complete. Stale contract expectations were reconciled without Auction schema, route-path, UI, or API response changes. Postman output isolation is configurable through explicit output-directory environment variables used only by delivery tests. Scope one blocker family at a time: 1. keep the current Auction schema and indexes frozen; update stale source-text tests and incomplete fixtures to the current model contract without changing runtime behavior; 2. teach the CSRF route assertion about the approved Auction wrapper, or replace the brittle source-name check with middleware-order/runtime evidence; 3. decide whether Provider Product visibility formally returns `{ isHidden }`, then make documentation and tests match that contract without weakening behavior; 4. isolate Postman export tests so generated collection state cannot leak between test files. Forbidden in Wave 0.1: Auction schema/index/model changes, module moves, UI redesign, route-path changes, broad formatting, or unrelated cleanup. Exit gate: focused tests plus a fully green `npm test`, clean generated artifacts, and `git diff --check`. ## 4. Wave 1 — architecture test harness Status: complete. `module-ownership.json` and architecture boundary tests enforce public imports, model registration uniqueness, Socket registration, cron resolution, and sensitive-field boundaries. Create package-independent static tests for: - forbidden dependency directions; - module public-boundary imports; - route/middleware snapshots; - model registration uniqueness; - Socket event and listener-registration snapshots; - cron persisted-handler catalogue; - DTO sensitive-field denylist; - dynamic EJS allowlists and asset ownership manifests. No implementation is moved in this wave. This is the safety net for later moves. Rollback: remove only the new tests/manifests. ## 5. Wave 2 — shared infrastructure facade Status: complete. Shared facades preserve the exact legacy identities and are covered by `sharedKernelFacades.test.js`. Introduce `src/modules/shared/` facades for already shared technical contracts without moving implementations initially: - errors/response envelope; - logger; - localization; - pagination/money/date helpers; - upload/file ports; - notification delivery port; - socket transport port. Old paths remain authoritative re-exports. Do not move auth/CSRF/Passport in the first shared wave. Risk: medium. Exit gate includes all dashboard/API tests because these utilities are cross-cutting. ## 6. Wave 3 — first low-risk domain pilot Status: complete. Reasons established the canonical module plus dashboard compatibility pattern. Recommended pilot: Reasons or Socials. Steps: 1. freeze model, dashboard, and any API consumer contracts; 2. create `src/modules//domain` and `interfaces/dashboard`; 3. migrate the existing dashboard vertical files behind a new domain public index; 4. leave `src/modules/dashboard/` as compatibility exports; 5. leave EJS/assets at current URLs; 6. run full browser QA and tests. No model move is required in the first pilot; the module can import the compatibility model path until the separate model step is proven. ## 7. Wave 4 — low-risk catalogue/support domains Status: complete for the existing refactored dashboard domains: Socials, Coupons, Countries, Cities, Package Features, Packages, Premium Packages, and Subscriptions. One domain per sub-wave: - Socials/Reasons (whichever was not the pilot); - Coupons; - Countries/Cities after legacy location ownership is resolved; - Package Features; - Packages/Premium Packages/Subscriptions as one coordinated package-catalogue program. Do not combine all sub-waves into one diff. ## 8. Wave 5 — catalog taxonomy Status: complete. Departments/SubDepartments and Attributes/Attribute Values own dashboard boundaries and low-risk lookup APIs. Domains: - Departments/SubDepartments; - Attributes/Attribute Values. First define whether each pair is one bounded context or two child modules. Preserve API lookup paths, dashboard route groups, view paths, and Product references. Products remain a consumer; Product implementation does not move in this wave. ## 9. Wave 6 — dashboard registrar extraction Status: intentionally deferred. `adminRoute.js` remains the approved central aggregator and imports canonical module indices; route extraction was not required for vertical ownership and would add ordering risk. Extract only route groups whose modules and route snapshots are already stable. Start with read-only Subscriptions or Reasons. Each registrar returns an Express router or registers against the central router without changing order. `adminRoute.js` remains the central aggregator until every extracted registrar is proven. Products, Settings, People, Orders, Auctions, and Payments stay centralized until their own contract waves. ## 10. Wave 7 — API low-risk modularization Status: complete for Reasons, locations/catalogue lookups, Content, Support, Coupon apply, and Notifications. Settings, package subscriptions, and cross-domain global payloads stay behind compatibility helpers until dedicated contracts are approved. Start with lookup/support endpoints whose contracts are covered: - Reasons/lookups; - Socials/info content where ownership is clear; - Countries/Cities/Departments/SubDepartments/Attributes; - Coupons and package catalogue. For each domain: route/controller/helper/validator/DTO ownership migrates behind compatibility exports. Public/auth bucket placement and response shapes remain unchanged. ## 11. Wave 8 — communications Socket adapters Status: complete for Chat and Call, including Chat HTTP API ownership. Event names, payloads, registrar order, and legacy import identities remain unchanged. Split chat then call listeners: - event constant/DTO/policy first; - registrar delegation second; - domain service/repository third; - compatibility `SocketEvents` remains; - listener-registration-once and reconnection tests required. No event rename or mobile payload change. ## 12. Wave 9 — content/settings/support Status: partial by design. Content, Support, and Notifications are complete. Settings is frozen because it spans dashboard forms, uploads, SMTP, activation, orders, and auctions; it requires a dedicated contract wave rather than a blind move. Domains: - settings; - info-site/content; - complaints/contact/customer service; - notifications delivery orchestration. These appear simple but cross dashboard/API/i18n/uploads. Each capability needs an explicit owner map and browser/API contract tests. ## 13. Wave 10 — people and account boundaries Order: 1. Admins/Supervisors dashboard; 2. Clients; 3. Providers; 4. Provider requests/approval bridge; 5. AccountIdentity/auth adapter last. The dual-stack AccountIdentity behavior, legacy profile tokens, `req.user`, `req.authAccount`, active mode, provider approval, password ownership, and token invalidation are frozen contracts. No data migration occurs here. ## 14. Wave 11 — Products Products is a dedicated program: - model/import ownership proof; - read/list/details repositories and DTOs; - dashboard view models; - create/edit mutation orchestration; - upload/removed-media lifecycle; - variants and attributes; - AI pricing; - moderation/reports/notifications; - Product socket/cron consumers. Each slice can remain `PARTIAL` rather than inventing undocumented form or API contracts. ## 15. Wave 12 — Orders and return flows Freeze order/return state machines, commission snapshots, chats, notifications, deadlines, payment/shipping interactions, and actor-specific DTOs. Extract policies and repositories before moving routes. No transition value or response envelope changes. ## 16. Wave 13 — Auctions and realtime lifecycle Separate sub-waves: - auction catalogue/details; - provider mutations; - client join/payment; - bids and concurrency; - subscriptions/deposits; - live streaming; - winner/settlement/delivery lifecycle; - socket and cron adapters. Transactions, persisted cron names, event names, and payloads remain frozen. ## 17. Wave 14 — Payments, wallet, settlements, shipping This boundary requires actor-aware payment methods, order/auction integration, external gateways, wallet/balance history, provider settlements, OTO shipping, and webhooks. External call adapters and secrets stay in shared infrastructure ports. No provider or client financial behavior changes in an architecture-only wave. ## 18. Wave 15 — model physical moves Only after domain consumers import public module contracts. Move one model at a time with: - old-path compatibility re-export; - registration/name/index/hook/populate snapshots; - duplicate compilation test; - no schema/index/data migration; - full tests and all relevant runtime QA. High-risk models may remain in `src/models` indefinitely if the compatibility risk outweighs cosmetic folder consistency. ## 19. Wave 16 — EJS/assets cleanup Use domain ownership manifests to adjudicate duplicate partials, inline logic, and unreferenced assets. Require authenticated browser/network temporary-removal proof per family. No bulk deletion. ## 20. Wave 17 — lint/format enforcement After explicit package approval: - config/ignore proof; - changed files; - low-risk domains; - shared/adapters; - high-risk domains; - whole-project check only after legacy baselines are resolved. Formatting never shares a diff with a high-risk behavior change. ## 21. Wave 18 — compatibility retirement Old paths are removed only when: - all active consumers use public domain indices; - no dynamic/operational consumer remains; - import graph and temporary removal are clean; - full tests and API/dashboard/socket/cron gates pass; - rollback remains documented. ## 22. Final program gate The architecture program may report `COMPLETE` only when: - ownership is domain-first for active business logic; - compatibility debt is either removed with proof or explicitly accepted; - routes/models/events/contracts have no regression; - no unexplained dead/duplicate implementation remains; - full tests, syntax, Git, API docs, browser, Socket, cron, secret, and generated-artifact gates are green; - every Git-status entry is classified. Until then, reports use `COMPLETE_BLUEPRINT`, `PARTIAL`, or per-wave `COMPLETE` only.