CTC Logistics Workspace Stable Context¶

Status: STABLE BACKGROUND / NOT EXECUTION AUTHORITY
Effective date: 2026-08-21
Product: ../PRODUCT.md
Phase order: ../ROADMAP.md
Live execution: ../EXECUTION.md
Documentation authority: ../README.md
Plugin boundary rationale: ../decisions/0009-modernization-plugin-reuse-and-greenfield-boundary.md
Identity standard: ../architecture/UUID_IDENTITY_TRANSITION_STANDARD.md

This file records durable background and constraints. It does not own current phase scope, exact Task order, active status or stage.

Program Boundary¶

Legacy root Runtime
= current operation, fallback and strongest current-behavior evidence

new-system/**
= independently developed successor frontend, backend, APIs and knowledge

transition/**
= route/writer/parity/cutover/rollback/caller-zero

historical Tasks, decisions and reports
= rationale or evidence, not executable authority

Successor development must not repeatedly destabilize the operating Legacy system.

Product Objective¶

The concrete near-term Product is one codebase and release lineage serving:

CTC execution-centered operation;
MK commercial/inventory-centered operation;
shared semantic modules and typed contracts;
profile/capability composition instead of customer source branches;
current MySQL coexistence during migration.

CTC and MK are operating profiles of one Product, not separate backends or raw numeric tenant branches.

Future Product Horizon¶

After CTC and MK are accepted and stable, compatible companies may be onboarded through versioned validated configuration without application-code deployment. Approved configuration may compose profiles, modules, capabilities, roles, menus, surfaces, defaults, document templates and provider bindings.

Configuration must not become arbitrary customer SQL, transaction code or an untyped business-rule scripting platform. Phase work implements only seams consumed by current CTC/MK journeys.

After onboarding, isolation, release and support operations are proven, the Product may be delivered as shared SaaS or managed hosting. Commercial control-plane and tenant-lifecycle work remain separately planned.

Current Operating Envelope¶

sites                    = 2
concurrent users         = approximately 20 total
current users            = employees
acceptance environment   = existing QA runtime and approved test accounts
current data authority   = central application and MySQL

Use this representative envelope before admitting speculative scale architecture. It does not justify microservices, hyperscale infrastructure or a broad distributed platform.

MFA, SSO and external customer/carrier/driver access remain later explicit scope. Identity contracts remain adapter-extensible.

In-Flight Work Rule¶

Current implementation state is read only from EXECUTION.md, the active Task and its manifest.

New clarification must not restart active Product work, reopen completed horizontal Foundation work or inject future onboarding, SaaS control-plane, local/cloud synchronization, MFA, SSO or persistence migration into the current slice unless the owning current phase and exact Task explicitly adopt it.

Current-Fact Precedence¶

current source/runtime/schema
-> authorized current MySQL readback
-> current role/menu/runbook/provider evidence
-> historical MK/reference evidence
-> dated documents/Tasks
-> inference

Classify material claims as:

CONFIRMED
INFERRED
UNKNOWN
CONFLICT
TARGET_APPROVED

Accidental current behavior is not automatically the preferred target, but current capability remains available until separately accepted replacement and retirement.

Legacy Preservation Contract¶

Product and migration work are additive coexistence until explicit retirement:

current Legacy capabilities, pages, popups, routes, APIs, data contracts and operational entry paths remain available;
backward-compatible schema, index, configuration and logic additions are allowed;
active tables, columns, contracts and behavior are not deleted, renamed, repurposed or made unreadable by the replacement feature Task;
unknown capability is inventoried and verified rather than silently omitted;
preferred/default routing changes require explicit transition evidence;
cleanup, schema contraction, caller retirement and feature removal require accepted replacement, caller/data zero where applicable, readback, rollback and explicit authorization.

Root Legacy business code is not modified merely to make a Logistics Workspace Task pass.

Product Authority¶

Tenant UUID Context
-> Operating Profile
-> Module/Capability
-> Typed Policy
-> Persisted Facts
-> Role/Record Access
-> Shared Command/Query
-> Repository/Transaction Owner
-> Authoritative Readback/Audit

No customer source fork, raw numeric tenant business authority or generic mutation endpoint.

Configuration may select approved composition but does not own lifecycle, transaction, security, reconciliation or arbitrary business code.

UUID Identity¶

Logistics Workspace route/API/domain/UI/audit/job identity
= UUID only

shared existing MySQL table during coexistence
= UUID/TENANT_ID/*_UUID canonical values
+ numeric compatibility aliases

Logistics Workspace-only table
= UUID primary/foreign keys from first migration

new identifiers use UUIDv7;
the client never supplies numeric aliases;
DB adapters resolve and dual-write aliases atomically when required;
both aliases identify the same active same-tenant row;
valid existing UUIDs remain stable;
numeric retirement requires caller/data zero and rollback approval.

Plugin Reuse¶

KJTable, KJModal, KJUpload, KJPhoto and other independently reusable modernization assets may be copied/owned or replaced natively.

A copied plugin records provenance, is isolated from root Legacy runtime, exposes a typed adapter, loads only where needed, has focused tests and accessibility/performance evidence, and owns no business policy, SQL or transaction.

Working table/modal/image behavior is not rewritten for stylistic purity. Mixed Legacy business composition remains evidence/transition input rather than target authority.

Backend And Data¶

transport
-> typed UUID application use case
-> policy
-> transaction/read-model owner
-> port
<- MySQL or provider adapter
-> authoritative UUID reread/reconciliation

No public DB rows, numeric compatibility aliases, SELECT *, SQL in routes/React or provider wait inside transactions.

One command/query/transaction/effect has one semantic owner. Unknown mutation results are reread before replay.

Web And UI¶

Server Components by default and Client Components at interaction boundaries;
UUID route/payload contracts;
URL/shareable state separated from authoritative server data and ephemeral UI;
semantic thin routes and typed errors;
native UI plus isolated copied-plugin adapters;
compact, keyboard-accessible, reduced-motion-safe surfaces;
CTC/MK variation through typed profile/capability composition;
visual acceptance through actual QA Product and captured evidence, not a mandatory design-file artifact.

Reliability And Security¶

server-side authorization and tenant UUID isolation;
validated config/secrets;
explicit session/cookie/origin/rate-limit behavior;
duplicate/concurrency/deadlock/timeout/unknown-result recovery;
dual-key mismatch/orphan/cross-tenant reconciliation;
redacted logs, correlation, health/readiness/release identity;
durable Worker/outbox only for a real persistent consumer/effect;
explicit rollback/fallback evidence.

UUID is not authorization or a secret.

Local And Cloud Distribution Timing¶

Local-primary/cloud-accessible distributed operation is not part of the current Product Core work. It becomes eligible only after accepted current CTC migration.

Before then, preserve prerequisites such as UUID identity, versions, idempotency, correlation, authoritative readback and explicit file/object relations, but do not build bidirectional DB replication, multi-writer synchronization or offline conflict infrastructure.

A later authorized track owns site authority, offline behavior, synchronization, conflict/reconciliation, file transfer, failover, recovery and deployment topology.

MK Stable Shape¶

MK remains order-first:

optional Commercial Purchase
-> Inbound Purchase
-> conditional Receipt/Scale
-> Inventory Lot/Ledger/Cost
-> Allocation
-> optional Commercial Sales
-> Outbound Sales
-> optional Booking/Container/External Carrier
-> conditional Documents
-> Trade/Margin reconciliation

New MK-owned tables are UUID-native. Shared tables use the temporary dual-key bridge. Do not force CTC Loader/internal trucking or a universal completed state.

Evidence And Effects¶

NONE
SOURCE
FIXTURE
LOCAL_RUNTIME
QA_RUNTIME
TARGET_ROLE
ACCEPTED

Source review does not prove runtime; runtime does not prove target-role acceptance; Git does not prove deployment, DB migration or cutover.

Development, review, QA deployment, DB/data change, provider/file/device effect, route/writer cutover, observation, caller-zero and retirement are separate actions with target, authorization, readback and rollback.

---¶

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