# MojoPortal Doctrine Strategy summary for the legacy-to-upstream SQLite migration of the customized mojoPortal platform. ## 1. Purpose This doctrine captures the current migration strategy for moving the legacy customized mojoPortal system into a fresh upstream SQLite-based mojoPortal baseline. It is intended to be updated over time as the migration progresses and as new route, data, and behavioral evidence becomes available. ## 2. Verified insights ### 2.1 The migration is A-to-B, not a merge of equals A is the authoritative legacy customized system under the static ___Fire/mojoportal tree. B is the clean upstream mojoportal-master SQLite baseline. The practical task is not to merge two modified trees. It is to re-implant the custom routed application architecture from A into clean upstream B. ### 2.2 The legacy system is more than a CMS customization The legacy system behaves as a custom routed application platform embedded inside mojoPortal. The evidence for this includes custom route infrastructure, custom operational surfaces such as MoxOp, and application-slice patterns such as ACdash and the broader A?dash family. ### 2.3 The fresh upstream baseline already contains the route scaffold needed for the migration The fresh upstream tree preserves the core route registration framework used by mojoPortal. That means the migration can land on existing route registration infrastructure rather than inventing a new one. This is one of the most important verified advantages discovered so far. ### 2.4 The migration is SQLite-only Only the SQLite path is in scope. Other database-provider branches and offshoots should be ignored unless a shared abstraction forces temporary attention. This significantly reduces comparison noise and migration scope. ### 2.5 There are true custom domain additions The legacy system contains explicit custom business/data-layer additions such as Place and UserDevice, including supporting DB access classes. These are not cosmetic edits. They represent real domain extensions that must be restored explicitly in the upgraded system. ### 2.6 Stock field names are not always semantically trustworthy A major verified characteristic of the legacy system is that some existing stock fields, especially in core entities such as User, were repurposed or hijacked to carry application-specific meaning. This means field names alone are not authoritative indicators of function. ### 2.7 Some slices are application shells, not pages Named surfaces such as ACdash, ABdash, and related A?dash members should be treated as application slices or dashboard-entry shells. Likewise, MoxOp and Mop should be treated as operational or orchestration surfaces rather than ordinary content pages. ## 3. Strategic doctrine ### 3.1 Primary rule: route intent outranks field names The behavior and purpose of a route or slice is more authoritative than the names of the fields or tables it touches. During migration, route intent should be used as the primary organizing principle. ### 3.2 Secondary rule: preserve behavior before normalization The first migration pass should preserve working behavior, even where the legacy mapping is inept or semantically misleading. Cleanup and normalization should happen only after slice parity is proven. ### 3.3 Third rule: separate custom domain from stock-schema overlays The migration must distinguish between true custom domain constructs such as Place and UserDevice, and semantic overlays that are hidden inside stock mojoPortal entities and fields. ## 4. Migration structure ### 4.1 Four ledgers should guide all work The migration should be managed through four ledgers: a route and slice ledger, a semantic field ledger, a true extension ledger, and a port-strategy ledger. ### 4.2 Route and slice ledger This ledger records the outward application surface: ACdash, ABdash, other A?dash slices, Vehicle Trackers, MoxOp, Mop, and all custom route registrations. ### 4.3 Semantic field ledger This ledger tracks reused stock fields whose meanings were altered by legacy business intent. Each reused field should be classified as preserve, shadow, migrate, or retire. ### 4.4 True extension ledger This ledger records explicit custom domain artifacts such as Place, UserDevice, and any related tracking or portal-aggregation components that are not part of stock upstream mojoPortal. ### 4.5 Port-strategy ledger Each item should be tagged with a migration action such as preserve, preserve and rename later, shadow with a normalized replacement, rewrite against new upstream patterns, or retire. ## 5. Recommended migration phases ### 5.1 Phase 0: inventory Inventory the route platform, slice families, custom domain objects, SQLite-specific data access, and stock-field semantic overlays before making structural changes. ### 5.2 Phase 1: route framework landing Use the fresh upstream route infrastructure as the landing zone for custom route registrations. Preserve the legacy named route behavior wherever practical. ### 5.3 Phase 2: port one representative slice end to end Select one representative application slice such as ACdash or ABdash and port it completely: route entry, controller or page, client assets, data access, and semantic field behavior. This establishes the pattern for the remaining slices. ### 5.4 Phase 3: restore true custom domain entities Reintroduce explicit custom entities such as Place and UserDevice, together with the SQLite-specific support needed for them to function in the upgraded baseline. ### 5.5 Phase 4: port operational shells Port MoxOp, Mop, and related orchestration surfaces after the route and domain pattern is proven. ### 5.6 Phase 5: normalization bridge Only after the slices are functioning should the system begin normalization of field names, semantics, and contracts. Legacy semantics may be preserved temporarily through wrappers, aliases, or bridge mappings. ## 6. Preserve, normalize, rewrite ### 6.1 Preserve now Preserve route names, visible slice behavior, SQLite functionality, and any stock-field overlays that are required for runtime correctness. ### 6.2 Normalize later Normalize misleading field names, hidden semantic overloads, and unclear property contracts only after behavior has been recovered. ### 6.3 Rewrite selectively Rewrite only where upstream changes or legacy brittleness make direct carry-forward unsafe. Page lifecycle glue, client-asset wiring, and tightly coupled dispatch code are likely rewrite candidates. ## 7. Warnings and problem areas ### 7.1 Field names may be deceptive A stock field name may not represent stock meaning. Any field-level assumption made from naming alone is risky. ### 7.2 Custom behavior may be hidden in standard entities Some of the most important business logic may be encoded through repurposed fields in stock tables such as User, rather than through obvious custom tables. ### 7.3 Dashboard slices are not ordinary pages A?dash slices and MoxOp-like surfaces should not be treated as simple page ports. They may combine routing, dispatch logic, data aggregation, and client-code emission. ### 7.4 Normalization too early would be dangerous Trying to clean up names and semantics during the first crossing would risk behavior loss. A successful first port should favor compatibility over elegance. ### 7.5 SQLite scope must be guarded It is easy for comparison work to drift into unrelated provider branches. The doctrine should remain disciplined about SQLite-only relevance unless a shared abstraction proves necessary. ## 8. Next steps ### 8.1 Build the first file-by-file port matrix Create a port matrix for the highest-value targets: route registrar files, ACdash, ABdash, Vehicle Trackers, MoxOp, Place, and UserDevice. ### 8.2 Gather populated URLs and route evidence As route examples become available, tie them to concrete controllers, pages, views, client assets, and data anchors. ### 8.3 Create a semantic overlay inventory Document which stock fields are being used with non-stock intent, especially in User and related entities. ### 8.4 Prove one slice end to end Use one representative slice as the proving ground for the migration pattern before broad rollout. ### 8.5 Update this doctrine over time This document should be revised as the migration proceeds, with findings folded back into the doctrine so it remains the current strategic reference.