Skip to content

CTC Rebuild Dependency And Bootstrap Sequence

  • Status: CURRENT SYSTEM REBUILD ORDERING INPUT
  • Review baseline: qa/master@6dfa87c1dc68ff00eaa939bc954554566a1f7a97
  • Cross-family review: CROSS_FAMILY_RECONSTRUCTION_CONSISTENCY_REVIEW.md
  • System blueprint: CTC_SYSTEM_REBUILD_BLUEPRINT.md
  • Phase implementation: USER HOLD
  • Purpose: define dependency order for reconstructing, migrating, deploying and restoring CTC without copying legacy file structure or activating work

1. Why Ordering Matters

CTC cannot be safely rebuilt by converting pages or tables in arbitrary order.

The system depends on a chain of authorities:

Release / Environment
-> Schema / Files
-> Tenant / Profile / Config
-> Identity / Session
-> Authorization
-> Audit / Correlation
-> Provider / Worker boundaries
-> Business processes
-> UI / Wiki
-> Observability / Backup / Restore

A later layer may consume an earlier layer, but must not redefine it.

Examples:

React page cannot define tenant identity.
Route Handler cannot define business transaction meaning.
Worker cannot define business approval.
Wiki cannot define current Runtime state.
Backup tool cannot infer business completion from table age.

2. Dependency Graph

flowchart TB
    P0[0 Product / Context / Profiles]
    P1[1 Source Release / Deployment Identity]
    P2[2 Database / File / Schema Foundation]
    P3[3 Tenant / Module / Capability / Config]
    P4[4 Identity / Session / Actor / Subject]
    P5[5 Page / API / Action / Record Access]
    P6[6 Audit / Correlation / Evidence]
    P7[7 Integration / Callback / Worker Contracts]
    CTC[8A CTC Execution Families]
    MK[8B MK Order-First Families]
    UI[9 React / Next.js UI and Adapters]
    OPS[10 Runbooks / Wiki / Support]
    OBS[11 Health / Observability / Release Evidence]
    REC[12 Backup / Restore / DR]
    CUT[13 One-Writer Cutover / Caller-Zero]
    PG[14 PostgreSQL After Stabilization]

    P0 --> P1
    P1 --> P2
    P2 --> P3
    P3 --> P4
    P4 --> P5
    P5 --> P6
    P6 --> P7
    P7 --> CTC
    P7 --> MK
    CTC --> UI
    MK --> UI
    UI --> OPS
    P1 --> OBS
    P2 --> OBS
    P6 --> OBS
    P7 --> OBS
    OPS --> OBS
    P1 --> REC
    P2 --> REC
    P3 --> REC
    P7 --> REC
    OBS --> REC
    UI --> CUT
    OBS --> CUT
    REC --> CUT
    CUT --> PG

This graph is logical ordering. It does not require a single big-bang implementation.

3. Full Rebuild From An Empty Environment

Step 0 — Product and profile contract

Required inputs:

  • Product outcome and non-goals;
  • operating profiles (ctc-execution, mk-order);
  • Shared/Dedicated hosting intent;
  • current/future capability list;
  • accepted terminology;
  • current policy decisions and open questions.

Stop if a tenant-specific behavior would be invented from a numeric client ID or customer name.

Step 1 — Source and deployment identity

Establish:

source repository and SHA
release/change-set identity
deployment/environment identity
hosting mode
service list
config release reference
schema release reference
previous/rollback release

Do not call an environment rebuilt while the running service identity is unknown.

Step 2 — Database and file foundation

Establish:

  • MySQL version and database identity;
  • required schema and migration set;
  • lifecycle columns and tenant keys;
  • authoritative table/relationship map;
  • object-storage mode and root/bucket identity;
  • T_FILE metadata/link/readability behavior;
  • archive relationship;
  • backup/restore owner.

Current target order remains:

MySQL first
-> React + Next.js + MySQL stabilization
-> PostgreSQL later

Step 3 — Tenant, profile and configuration bootstrap

For each tenant/deployment:

portable tenant identity
-> local CLIENT_ID mapping
-> operating profile assignment
-> module state
-> named capabilities
-> typed config
-> credential owner references
-> effective configuration readback

Config values and credential references must remain separate from source and deployment identity.

Step 4 — Identity and session bootstrap

Establish:

  • user/login identity;
  • actor and effective subject;
  • session authority;
  • impersonation modes;
  • service/integration identity;
  • tenant provenance;
  • revocation and logout behavior;
  • PHP/Next.js coexistence contract.

Do not introduce a second independent session authority during migration.

Step 5 — Authorization bootstrap

Build the decision chain:

authentication
+ tenant context
+ module/capability availability
+ menu/page/API availability
+ role/action permission
+ record ownership/relation
+ record-state eligibility
+ config/credential validity

Seed explicit current parity before retiring missing/error compatibility behavior.

Step 6 — Audit, correlation and support evidence

Establish:

  • request/page/session correlation;
  • command request token;
  • process instance/correlation/causation;
  • immutable business transition reference;
  • domain/provider evidence reference;
  • operation-notification semantics;
  • safe support timeline;
  • retention/redaction/legal-hold policy.

Request diagnostics must not replace business transition evidence.

Step 7 — Integration and worker foundation

For every provider/effect family define:

owner process/application
effect intent
attempt identity
provider idempotency
success/failure/unknown
callback receipt/application
reconciliation
retry/manual recovery
credential owner
redaction/retention

The current generic outbox/replay design remains canceled. A shared worker runtime may host handlers but does not create shared provider/business authority.

4. Business Capability Bootstrap Order

4.1 CTC execution profile

Recommended dependency order:

flowchart LR
    APPT[Appointment / Request]
    PLAN[Planning / Assignment]
    LOAD[Loader Execution / Clock / Break]
    REVIEW[Final Loading Review]
    INV[Inventory / Source / Leftover / Placement]
    YARD[Yard Queue / Physical Move]
    DRIVER[Driver Delivery / Parking]
    BILL[Billing / QBO / Files / Email]

    APPT --> PLAN --> LOAD --> REVIEW --> INV --> YARD --> DRIVER --> BILL

CTC sequence requirements

  1. Appointment identity before Planning.
  2. Planning/assignment identity before Loader Start.
  3. Loader completion before Final Review eligibility.
  4. Final Review separate from Inventory adjustment.
  5. Inventory/placement before Yard source availability.
  6. Yard completion separate from Driver completion.
  7. Local billing separate from QBO/file/email effects.

Assign Work/Clock Out extends Planning/Loader/Workforce; it is not a new generic workflow platform.

4.2 MK order-first profile

Recommended dependency order:

flowchart LR
    COM[Commercial Agreement]
    INB[Inbound Purchase]
    SCALE[Physical Scale when required]
    LOT[Inventory Lot]
    ALLOC[Allocation]
    OUT[Outbound Sales]
    BOOK[Booking / Equipment]
    EXEC[Scale / Packing / Delivery]
    TRADE[Trade / Cost / Rate / Documents]

    COM --> INB
    INB --> SCALE --> LOT
    LOT --> ALLOC --> OUT
    OUT --> BOOK --> EXEC --> TRADE

MK sequence requirements

Commercial status != execution completion
Scale checkout != receipt finalize
Receipt != allocation
Outbound Save != allocation
Booking Save != every child synchronized
Trade projection != accounting close
Rendered output != durable document effect

Allocation and Scale remain independent child owners even when one UI guides users through both.

5. UI And API Bootstrap

5.1 Current compatibility

Current PHP remains authoritative until a selected capability/cohort cutover.

PHP page/API/helper
-> current MySQL owner
-> current Runbook/Wiki

5.2 Target read path

React UI
-> Next.js Server Component / Route Handler
-> TypeScript Query Application
-> MySQL Repository
-> read parity

Read-only conversion may proceed before write cutover when:

  • tenant/access parity is proven;
  • authoritative source is unchanged;
  • stale/partial/error states are represented;
  • no hidden mutation occurs.

5.3 Target write path

React action/form
-> Next.js adapter
-> TypeScript Command Application
-> validation/access/state policy
-> one MySQL transaction
-> exact authoritative readback
-> optional provider-scoped effect

React and Next.js adapters do not own business SQL, process transitions or provider retry.

6. One-Capability Migration Sequence

sequenceDiagram
    participant Legacy as Current PHP Writer
    participant Read as Target Read Shadow
    participant Target as TypeScript Writer
    participant DB as MySQL
    participant Evidence as Audit / Evidence
    participant User as Target Role

    Legacy->>DB: Current writes continue
    Read->>DB: Read-only parity
    Read-->>Legacy: Compare identity/state/result
    Note over Legacy,Target: Resolve policy and evidence gaps
    Legacy->>Target: Select tenant/capability cohort
    Target->>DB: One authoritative write
    Target->>Evidence: Transition/effect evidence
    User->>Target: Normal/denied/recovery scenarios
    Note over Legacy,Target: Roll back routing, not business/provider evidence
    Target->>DB: Stabilized target writes
    Legacy-->>Legacy: Caller-zero and retirement

Required steps:

W0 current caller/schema/role characterization
W1 typed read model
W2 React/Next.js read-only reference
W3 policy/field/error/duplicate/recovery acceptance
W4 one-writer target command
W5 rollback and unknown-result proof
W6 target-role/browser/provider/physical evidence
W7 observation/stabilization
W8 legacy caller-zero

No cohort may be written by PHP and TypeScript simultaneously.

7. Deployment Bootstrap Order

source release
-> deployment manifest
-> external config/credential references
-> schema compatibility
-> file/object dependency
-> PHP/Next.js/worker/gateway service identity
-> liveness
-> readiness
-> read-only canary
-> selected write canary
-> provider/scheduler enablement
-> field acceptance
-> stabilization

Do not enable schedulers/providers before restore/cutover reconciliation.

8. Restore And Disaster-Recovery Sequence

flowchart TB
    INC[Declare incident / rehearsal]
    SET[Select complete Backup Set]
    ISO[Create isolated target]
    OFF[Disable traffic / callbacks / schedulers / sends]
    DB[Restore DB + schema identity]
    ARC[Reconcile archive]
    FILE[Restore files + metadata/link/readability]
    CFG[Apply config + credential recovery]
    SRC[Deploy compatible source/services]
    READY[Verify release/config/schema/liveness/readiness]
    EFF[Reconcile provider/callback/outbox state]
    READ[Read-only canary]
    WRITE[Approved write canary]
    ON[Enable effects one family at a time]
    OBS[Observe and measure RPO/RTO]

    INC --> SET --> ISO --> OFF --> DB --> ARC --> FILE --> CFG --> SRC --> READY --> EFF --> READ --> WRITE --> ON --> OBS

Restore ordering is not optional when provider/physical/file effects exist.

DB restored
!= file objects restored
!= provider state reconciled
!= system ready

9. Minimum Rebuild Artifacts By Layer

Layer Required artifact
Product/profile Product/Context and profile contract
Source/deployment release/deployment manifest
Data schema/data authority map and migration set
Files object/metadata/link/readability contract
Tenant/config effective tenant/profile/module/capability/config snapshot
Identity/access actor/session/tenant/access decision matrix
Audit transition/evidence/correlation contract
Integration provider-scoped effect contract and recovery
Process capability rebuild packet and state/handoff diagrams
UI current entry and target React component/server-client boundary
Operations role Runbook and escalation packet
Wiki stable topic/current/future route/publication package
Migration read shadow, one writer, rollback, caller-zero
Verification stable scenarios and accepted evidence
Recovery complete Backup Set and RestoreAttempt evidence

10. Stop Conditions

Stop planning/implementation of a selected layer when:

  • an earlier dependency has conflicting authority;
  • tenant/actor/record ownership is unknown;
  • field/UOM/state meaning would be invented;
  • duplicate/timeout/partial recovery is undefined;
  • provider or physical replay risk is unresolved;
  • one-writer or rollback is missing;
  • current schema/environment identity is unknown for an external effect;
  • current user procedure cannot be stated safely;
  • backup/restore cannot preserve required state;
  • a Phase/user decision is required.

Document the question, owner and evidence package instead of expanding scope.

11. Current Use

This sequence is a reconstruction and review input. It does not activate:

  • P4/P5/P6/P7/P9/P11/P12 implementation;
  • Next.js or worker scaffolding;
  • DB or schema changes;
  • provider retries;
  • role/menu changes;
  • Wiki publication;
  • deployment/restore operations.

The next implementation session for any family must start from its current authority, this dependency order and the accepted evidence register—not from a legacy page/file list alone.

---

Source: docs/reconstruction/REBUILD_DEPENDENCY_AND_BOOTSTRAP_SEQUENCE.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.