Mirror Canonical Migration (Oct 8 2025)
This document establishes the mirror repository at
/Users/work-station/company/cloudalt-frontendas the canonical monorepo going forward and records rationale, source-of-truth decisions, and the operational migration process from the “active” snapshot at/Users/work-station/company/cloudalt/cloudalt-frontend.
1. Scope
Section titled “1. Scope”- Unify two local filesystem Git repositories containing overlapping Nx/Expo/React Native multi-brand application scaffolding.
- Preserve forward-looking tooling and dependency upgrades from the mirror repo.
- Salvage only purposeful, non-ephemeral artifacts from the active snapshot (config orchestration, unique types, brand assets, docs).
- Maintain forensic traceability: every file altered or added during migration will be logged in
MIRROR_CHANGE_LOG.mdwith timestamp.
2. Canonical Choice Rationale
Section titled “2. Canonical Choice Rationale”| Dimension | Active Snapshot | Mirror Repo | Decision |
|---|---|---|---|
| Dependency Freshness | Lean baseline only | Upgrades (Storybook 8.6.14, Yarn 4.10.3, RN ecosystem libs) | Favor mirror |
| Tooling Automation | Minimal | Rich scripts (verify, generation, audit) | Favor mirror |
| Path Aliases | Empty | Namespaced packages + brands | Favor mirror |
| Native App Structure | Generic + Pods noise | Named Xcode projects | Favor mirror |
| Experimental Capability | None | Navigation, forms, data, theming libs | Favor mirror |
| Technical Debt | Committed Pods | Nested node_modules (cleanable) | Clean mirror; adopt |
Conclusion: Mirror contains more strategic scaffolding with lower net future effort after a one-time hygiene pass.
3. Items to Migrate FROM Active -> Mirror
Section titled “3. Items to Migrate FROM Active -> Mirror”| Category | Source Path | Target Action | Notes |
|---|---|---|---|
| Config package | packages/config/ | Copy (evaluate merge into existing services/theme) | Validate no secret leakage |
| Universal types | packages/universal-types/ | Merge into packages/types/ or keep separate; add tsconfig path | De-duplicate shared interfaces |
| Assets (unique) | apps/stay_match/pinkguest/mobile/assets/splash-icon.png (if not in mirror) | Copy if missing | Non-generated branding |
| Documentation | docs/*.md (diff) | Append or integrate | Preserve provenance |
Exclude ephemeral content: Pods/, .expo/, any node_modules/, build outputs, caches.
4. Hygiene Tasks (Mirror)
Section titled “4. Hygiene Tasks (Mirror)”- Remove nested
node_modulesunder individual mobile app directories (pinkguest, staymatch_app) — rely on root Yarn PnP/workspaces. - Ensure
.gitignoreeffectively blocks reappearance; confirm withgit ls-files | grep node_modules. - Normalize Metro configuration (centralize via shared factory; remove per-app duplicates unless overrides exist).
- Add TypeScript path aliases for migrated packages.
- Run
./scripts/verify-repo.sh; address any reported gaps (targets, lint, typecheck, test placeholders). - Introduce a shared
Herocomponent inpackages/ui(future step) to replace inline temp UI elements.
5. Logging & Backups
Section titled “5. Logging & Backups”- Compressed backups created on external T7 drive (timestamped). Filenames:
cloudalt-active-<timestamp>.tgz,cloudalt-mirror-<timestamp>.tgz. - Each migrated or changed file: a
.bak.<YYYYMMDD-HHMMSS>sibling created prior to modification. MIRROR_CHANGE_LOG.mdaccumulates structured entries: timestamp, operation type (ADD / COPY / MODIFY / BAK), source, destination, hash (if feasible).
6. Git Strategy
Section titled “6. Git Strategy”Two local repos currently distinct:
- Active: HEAD detached at tag
basic-react-native-scaffolding-restore(commit54ed2ec). - Mirror: Branch
development-oct7-2025(commited10395). Approach:
- Treat mirror remote (if configured) as origin canonical. If active repo remote is same origin, avoid pushing from active.
- Create a convergence branch in mirror:
converge-active-importfor migration commits. - After successful verification & copy, fast-forward or merge into mainline branch (e.g.,
masterordevelopment-oct7-2025). Tag convergence:post-convergence-20251008. - Optionally archive the active snapshot tar in long-term storage; remove duplicate working tree to prevent future drift.
7. Validation Steps Post-Migration
Section titled “7. Validation Steps Post-Migration”| Step | Command | Success Criteria |
|---|---|---|
| Install | yarn install | Zero peer resolution failures |
| Lint sweep | nx run-many --target=lint --all | All succeed or only intentional TODO warnings |
| Typecheck | nx run-many --target=typecheck --all | No blocking TS errors |
| Mobile start (pinkguest) | nx run stay_match-pinkguest-mobile:start (placeholder) | Metro boots & loads splash |
| Mobile start (orangeguest) | Same pattern | Metro + navigation libs resolve |
| Verify script | ./scripts/verify-repo.sh | Pass or enumerated actionable items |
8. Future Improvements (After Convergence)
Section titled “8. Future Improvements (After Convergence)”- Introduce design tokens & theme contract package.
- Implement brand registry generation script integration into CI.
- Replace any redundant brand app boilerplate with templated generation.
- Add minimal unit test per package to enforce test target viability.
9. Rollback Plan
Section titled “9. Rollback Plan”- If a migration commit breaks builds: checkout prior commit (pre-convergence) and re-apply subsets incrementally.
.bak.*files allow single-file rollback; delete new file and restore from most recent backup sibling.
10. Open Questions
Section titled “10. Open Questions”- Are
configenvironment values secret-bound? If yes, consider extracting to.env+ vault before commit. - Is Module Federation experiment production-bound? If uncertain, quarantine config behind feature flag.
Generated: 2025-10-08T02:17:58Z