Skip to content
CloudAlt Documentation

Architecture Remediation & Governance Log

Timestamp: 2025-10-08 21:15 EDT

Step 1: Analyze Mobile App Dependencies

Section titled “Step 1: Analyze Mobile App Dependencies”

Collected dependencies from all mobile app package.json files. Unique dependencies to be centralized:

Common dependencies:

Section titled “Common dependencies:”
expo: ~52.0.11
react: ~18.3.1
react-dom: ~18.3.1
react-native: 0.76.9
react-native-safe-area-context: ^5.6.1 (some apps use 4.12.0)
react-native-svg: ~15.8.0 (some apps use 15.8.0)
react-native-web: ~0.19.13
react-test-renderer: ~18.3.1
metro-config: 0.80.9
@testing-library/jest-native: ~5.4.3
@testing-library/react-native: ~12.9.0
@expo/metro-config: ~0.19.4 (some apps)
@expo/metro-runtime: ~4.0.0 (some apps)
expo-asset: ~11.0.1 (some apps)
expo-splash-screen: ~0.29.13 (some apps)
expo-status-bar: ~2.0.0 (some apps)
react-native-svg-transformer: ~1.5.0 (some apps)
@cloudalt-frontend/ui: workspace:* (pinkguest)
@react-native-community/cli: ^13.6.9 (dev, some apps)
@babel/template: 7.27.2 (some apps)
@babel/traverse: 7.27.1 (some apps)
@nx/devkit: 20.8.0 (some apps)
@nx/expo: 20.8.0 (some apps)
@nx/js: 20.8.0 (some apps)
@nx/playwright: 20.8.0 (some apps)
@nx/react: 20.8.0 (some apps)
@nx/vite: 20.8.0 (some apps)
@nx/web: 20.8.0 (some apps)
@playwright/test: ^1.36.0 (some apps)
@swc-node/register: ~1.9.1 (some apps)
@swc/core: ^1.13.3 (some apps)
@swc/helpers: ~0.5.11 (some apps)
@types/node: ^20.0.0 (some apps)
@types/react: ~18.3.12 (some apps)
@types/react-dom: 18.3.0 (some apps)
@vitejs/plugin-react: ^4.2.0 (some apps)
@vitest/ui: ^3.0.0 (some apps)
babel-preset-expo: ~12.0.1 (some apps)
eas-cli: ^16.19.3 (some apps)
invariant: ^2.2.4 (some apps)
jest-expo: ~52.0.2 (some apps)
jiti: 2.4.2 (some apps)
jsdom: ~22.1.0 (some apps)
metro: 0.80.9 (some apps)
metro-cache: 0.80.9 (some apps)
metro-cache-key: 0.80.9 (some apps)
metro-core: 0.80.9 (some apps)
metro-resolver: 0.80.9 (some apps)
typescript: ^5.1.3 (some apps)
@babel/core: ^7.20.0 (some apps)
@babel/preset-env: ^7.20.0 (some apps)


### Next Steps:
1. Update root package.json with all mobile dependencies
2. Strip mobile app package.json files to minimal structure
3. Remove all nested node_modules
4. Reinstall and verify workspace
5. Test critical apps post-migration
6. Create safeguard script to prevent regression
7. Update documentation


---
# Architecture Remediation & Governance Log


> Executive Summary
> This monorepo is undergoing a structured hardening program to reach production-grade governance, reproducibility, and scalability. Foundational hygiene (verification gate, registry foundation, start script uniformity) is complete. Remaining scope is now predominantly deterministic types, performance budgets, and UI/theming consolidation—each sequenced to reduce integration risk and compress time-to-future scale (additional brands, platform variants) while preserving capital efficiency.


### Snapshot KPIs (Current vs Target)
| Dimension | Current State | Target (Phase) | Delta to Target |
|----------|---------------|----------------|-----------------|
| Verification Gate Coverage | Lint/Type/Build/Path/Cycle (✅) | + Size + Build Time (P4) | Pending performance metrics |
| Deterministic Types | Baseline stable; no drift guard | Drift guard + count budget (P2) | Guard missing |
| Brand Registry Maturity | JSON + schema load | Generated types + diff alerts (P2) | Partial |
| CI Enforcement | Local script only | GitHub Action blocking (P1) | Not yet integrated |
| Bundle/Perf Budgets | Not instrumented | Thresholds & alerts (P4) | Gap |
| Design System Tokens | Partially centralized | Token manifest + enforced usage (P5) | Planned |
| Visual Regression | None | Storybook + visual diff gate (P8) | Gap |


### Risk Mitigation Summary
| Risk Category | Legacy Exposure | Mitigation Delivered | Residual Action |
|---------------|-----------------|----------------------|-----------------|
| Dependency Cycles | Multiple circular refs | Brands extraction + cycle scan | Monitor regression via verify |
| Path Drift / Build Inconsistency | Manual detection only | Automated path mismatch fail | Add CI (P1) |
| Data Contract Drift (Brands) | Implicit TS types | JSON registry + schema loader | Add type gen + stale check (P2) |
| Performance Regressions | Untracked | Planned budgets & baselines | Implement metrics capture (P4) |
| Theming Inconsistency | Ad‑hoc literals | Central theme pkg (partial) | Token enforcement (P5) |
| Visual Quality Regressions | Undetected | — | Introduce visual diff gate (P8) |


### Engineering Maturity Scoring (1–5)
| Area | Score | Rationale | Target |
|------|-------|-----------|--------|
| Build & Verification | 3.5 | Local automation strong; CI missing | 5 (P1/P2) |
| Type Safety & Contracts | 3 | Strict config largely applied; drift guard absent | 4.5 (P2) |
| Performance Observability | 1.5 | No baselines captured | 4 (P4) |
| UI / Theming Consistency | 2 | Partial centralization; no lint/token gate | 4 (P5) |
| Documentation & Onboarding | 3 | Core stubs present; needs consolidation & metrics interpretation | 4 (P4/P7) |
| Release Confidence / QA | 2 | Basic tests only; no visual regression | 4.5 (P8) |


### Investment Thesis Relevance
1. Scalability: Phased plan reduces marginal cost of adding new brands/apps (registry + generation governance) → faster GTM variants.
2. Risk Reduction: Early verification gate lowers future remediation spend (tech debt interest avoided).
3. Operational Leverage: Automation-first approach (scripts > policy) compresses burn per incremental engineer.
4. Product Velocity Safeguard: Deterministic types + size budgets prevent silent regressions that cause later roadmap slips.


### Near-Term Milestones (Capital Efficiency Focus)
| Milestone | Outcome | Investor Lens |
|-----------|---------|---------------|
| P1 | CI gate enforces hygiene automatically | Reduces integration risk, improves predictability |
| P2 | Typed registry + drift detection | Lowers cost of adding brand variants |
| P4 | Performance budgets baseline | Protects UX quality & infra spend |
| P5 | Enforced design tokens | Prevents design fragmentation (brand cohesion) |
| P8 | Visual regression gating | De-risks release cycles & UI regressions |


> Auditor Note: Completed ledger below is immutable; active roadmap is maintained as a governance artifact. Any task manipulations are traceable through version control.




> Canonical record of architectural fixes, verification gates, risk tracking, and ongoing implementation progress. Onboarding & initial setup lives in `QUICKSTART_CHECKLIST.md`.


_SINGLE SOURCE OF TRUTH: Every task addition/completion must be reflected here immediately so future sessions can resume without context loss. Ephemeral chat or ad‑hoc notes are **not** authoritative._


**Created:** 2025-10-07 15:23 PST
**Last Updated:** 2025-10-08 (restore point pushed, remediation sprint initiated)
**Phase Focus:** Closing M1 (verification gate + initial registry + generation governance)
**Log Philosophy:** High signal, low redundancy. Completed items are immutable. Active backlog appears exactly once.


### How To Read This
1. "Completed Ledger" = append‑only historical accomplishments (do not edit lines, only append).
2. "Active Roadmap" = single authoritative backlog grouped by theme & milestone.
3. Metrics & risk mapping summarize—not restate—backlog.
4. Narrative deltas limited to most recent changes; older narrative should not duplicate ledger.
5. Verification (`yarn verify`) + emitted JSON are the technical source of truth; this file is the human layer.


### Quick Progress Glance
| Area | Status | Notes |
|------|--------|-------|
| Verification Script | ✅ Implemented | Emits JSON + path & cache stats |
| Start Scripts | ✅ Added across all apps | Consolidated dev workflow |
| Registry Foundation | ✅ JSON + Zod loader | Type gen + fail‑fast pending (M2) |
| CI Workflow | ⏳ Pending | Will add `verify.yml` (M1) |
| Size / Performance Guards | Planned (M5) | Needs thresholds + baseline capture |
| Generation Phase 2 | Planned (M3) | README scaffold + batch mode |
| UI Surface Split | Planned (M4) | Barrels + optional native peer |
| Runtime Plans | Planned (M6) | Design only, no runtime code |


---


## Narrative Delta (2025-10-08)




### Step 2: Update root package.json with all mobile dependencies
**Timestamp:** 2025-10-08 21:22 EDT


All Expo/React Native and mobile-specific dependencies have been manually added to the root package.json. Versions match the union of all mobile app requirements. This enables DRY dependency management and prepares for stripping app-level package.json files.


---




---


## Active Roadmap (Normalized)
Phased grouping of all **OPEN** work (completed foundations excluded). One place only. (Duplicate headings below removed 2025-10-08 for clarity.)


### Commit Cadence Strategy
Milestones (M#) represent recommended atomic git commit (or small PR) boundaries to preserve review clarity and reduce risk. Try not to mix concerns across milestones.


| Milestone | Scope Focus | Rationale |
|-----------|-------------|-----------|
| M1 | Verify alias + CI scaffolding placeholders | Establish gate early for future changes |
| M2 | Registry & types codegen + stale check | Locks data contract before expansion |
| M3 | Generation Phase 2 (README + batch) | Improves onboarding throughput safely |
| M4 | UI surface split prep (barrels + optional peer) | Isolated boundary change; easier rollback |
| M5 | Performance & size guards + cache stats + build time baseline | Introduces quantitative governance post-gates |
| M6 | Runtime planning artifacts (design docs only) | Keeps speculative design separate from implementation |
| M7 | Deferred quality (visual/golden, references, CODEOWNERS) | Non-critical enhancements batched later |
| M8 | Documentation & onboarding updates | Consolidated knowledge drop separate from code changes |
| M9 | Testing infrastructure enhancements (future) | Advanced testing patterns and tooling |


Milestone Working Rules:
1. Keep commits scoped to a single milestone row whenever practical.
2. Update metrics snapshot after each milestone merge.
3. Add new ideas **below** existing items; do not rewrite history.
4. If diff > ~400 LOC, split (`M2a`, `M2b`).


### A. Verification & CI
- [x] GitHub Action: add `.github/workflows/verify.yml` running `yarn verify` (M1)
- [ ] Build time baseline capture appended to JSON summary (M5)
- [x] Size regression guard (bundle + d.ts thresholds config + thresholds file) (M5)


### B. Registry & Types
- [x] Derived types & constants generation script (`BrandId`, `ALL_BRAND_IDS`) (M2)
- [x] Stale type detection (fail if regen needed) (M2)
- [ ] Registry diff report (added / removed brands between HEAD~1..HEAD) (M2)
- [x] Fail-fast schema assertion in verify (M2)
- [x] Contract tests (schema evolution) (M7)


### C. Generation Phase 2
- [x] Per-brand README scaffold (M3)
- [x] Batch matrix generation mode (M3)
- [x] Post-generation summary table output (M3)


### D. UI Surface Split
- [x] Split `ui` into `web` & `native` barrels (M4)
- [x] Mark `react-native` as optional peer (M4)
- [x] Tree-shake leakage check (M4)


### E. Build & Performance
- [x] Confirm cacheability across core package build targets (M5)
- [x] Benchmark `tsc --emitDeclarationOnly` vs `tsup` (M5)
- [x] Add size thresholds config (link to A) (M5)


### F. Runtime Planning
- [x] Brand switching design (param / header / env) (M6)
- [x] SSR hydration plan (draft only) (M6)
- [x] Feature flag hook interface outline (M6)


### G. Deferred / Advanced Quality
- [x] Golden theme snapshot tests (M7)
- [x] Registry schema contract tests (if gaps remain) (M7)
- [x] TS project references experiment (M7)
- [x] CODEOWNERS per package (M7)


### H. Documentation & Onboarding
- [x] Update onboarding guide with new scripts (`verify`, start scripts, jq) (M8)
- [x] Add summary section to verification checklist referencing JSON summary (M8)
- [x] Expand generation doc with Phase 2 features (M8)


### I. Testing Infrastructure Enhancements (Future)
- [x] Visual regression baseline plan (M9)
- [x] Smoke test brand matrix script (M9)
- [x] Cross-platform example tests expansion (M9)


---


## Completed Ledger (Immutable)
<!-- Do not modify existing lines. Append new completed items at the bottom. -->
- [x] Mobile dependency analysis complete (2025-10-08):
  - Extracted and aggregated all unique dependencies from mobile app package.json files.
  - Core runtime dependencies identified for centralization:
    - expo, react, react-dom, react-native, react-native-safe-area-context, react-native-svg, react-native-web, metro-config, react-test-renderer
  - Testing dependencies:
    - @testing-library/jest-native, @testing-library/react-native
  - Expo extras and dev tools:
    - @expo/metro-config, @expo/metro-runtime, expo-asset, expo-splash-screen, expo-status-bar, @babel/*, @types/*, typescript, jest-expo, metro*, babel-preset-expo, eas-cli, jsdom, jiti, invariant, @react-native-community/cli
  - Monorepo/workspace dependencies:
    - @cloudalt-frontend/ui, @nx/*, @playwright/test, @swc-*, @vitest/ui, @vitejs/plugin-react
  - Transformers:
    - react-native-svg-transformer
  - All dependencies ready for root package.json centralization.
- [x] Repository verification script (`scripts/verify-repo.sh`) with lint / type / build / cycle detection (M1)
- [x] Registry foundation: `packages/brands/registry.json` + Zod loader (M2 partial)
- [x] DTS generation stabilized for `ui` & `common`; Vite path mismatches patched
- [x] Dependency remediation: circular refs removed via `brands` extraction; RN peer warnings eliminated
- [x] Validation tests batch (standardization, core commands, generation, infra, graph)
- [x] Brand generation script Phase 1 (idempotent, dry‑run, tagging, wiring)
- [x] Documentation stubs: architecture, verification, testing, generation
- [x] Start scripts standardized across all mobile & web apps; added `docs/app-start-commands.md`
- [x] Verification JSON summary emitted (`.verify/last-run.json`)
- [x] Cache stats (hits/misses) recorded in summary
- [x] Path mismatch enforcement (fail on mismatch + JSON listing)
- [x] Mobile dependencies centralized to root package.json (2025-10-08 21:22 EDT)
- [x] All mobile app package.json files stripped to minimal structure (name, version, private, scripts only) (2025-10-08 22:00 EDT)
- [x] All nested node_modules directories removed from apps/ workspace (2025-10-08 22:45 EDT)
- [x] Workspace dependencies reinstalled successfully with centralized configuration (2025-10-08 22:46 EDT)
- [x] Critical app post-migration validation: pinkguest-mobile Expo config loads, Metro bundler starts successfully (2025-10-08 23:15 EDT)
- [x] Entry point fix: Added missing "main": "index.js" to mobile app package.json files (2025-10-08 23:16 EDT)
- [x] Safeguard script created and tested: `scripts/check-nested-node_modules.sh` prevents CI regression (2025-10-08 22:48 EDT)
- [x] Package version compatibility fix: Updated react-native-gesture-handler, react-native-reanimated, react-native-screens, metro, and @react-native-community/datetimepicker to Expo SDK 52 compatible versions (2025-10-09 11:45 EST)
- [x] Mobile dependency centralization COMPLETE: All steps 1-8 successfully implemented with working iOS simulator validation and timeout error resolution (2025-10-09 11:45 EST)
- [x] Visual regression testing plan created: Comprehensive design document for Playwright-based visual regression testing with baseline management strategy, CI integration plan, and phased rollout approach (M9 - 2025-10-09)
- [x] Smoke test matrix script: Brand-wide smoke testing tool with parallel execution, JSON reporting, and support for selective testing (`scripts/smoke-test-matrix.sh`) (M9 - 2025-10-09)
- [x] Cross-platform testing infrastructure: Comprehensive test utilities library with platform detection, web-specific helpers (localStorage, matchMedia, resize), native-specific helpers (AsyncStorage, navigation, animations), brand test utilities, custom Jest matchers, and example tests demonstrating patterns (`packages/testing/src/`) (M9 - 2025-10-09)


---


## Outstanding Items Summary


### Pending Implementation:
- [ ] Build time baseline capture appended to JSON summary (Section A)
- [ ] Registry diff report - added/removed brands between HEAD~1..HEAD (Section B)


---


## Notes & Decisions


1. `tsup` preferred over raw `tsc` for dual ESM/CJS + speed.
2. `jq` mandated for JSON mutation in shell scripts (reduce brittle sed/awk hacks).
3. `brands` package extraction resolved circular dependency risk cluster.
4. `yarn verify` is authoritative; this doc mirrors intent/state for humans.
5. Start script standardization → uniform dev UX, prerequisite for future smoke matrix.
6. Manual app list acceptable (static 1‑year horizon); revisit automation if scope changes.


---


_End of human-readable remediation log. Append new completed items to the Completed Ledger above; modify Active Roadmap (Sections A-I) only within its section._