Logistics Workspace Module Registry¶
- Status:
CANONICAL TARGET OWNERSHIP - Product:
../PRODUCT.md - Product reality:
../PRODUCT_REALITY.md - Architecture method:
ARCHITECTURE_CHANGE_METHOD.md - Placement and creation:
SYSTEM_STRUCTURE_STANDARD.md
Implementation may not silently add, merge, split or fork modules/packages. A validation tenant, customer name, numeric client ID, rollout cohort, menu alias or deployment never owns a business module.
This registry owns domain state, commands, queries, transaction responsibilities and adapter
boundaries. It is not a commercial offering or license catalog. Use
PRODUCT.md for package names, scope and feature mapping.
A domain module and a commercial package are not required to correspond one-to-one.
Only the responsibilities registered below are the current owners. Even when a sub-feature, screen or table is added, it is handled within the existing owner,
and a new module, package or writer is not created automatically. When no owner fits, the boundary is first decided in the existing approval procedure. Adding a row to this table, or creating a file, is not by itself an approval. TARGET OWNERSHIP is a responsibility definition, not a declaration that every feature is implemented, activated or accepted. The owner's documents, code and tests are linked, and no separate module registry or per-customer ownership table is created. The authority of the operator manual body is the DB T_WIKI_PAGE, and the authority of assets is the WIKI_ASSET relation of T_FILE plus the existing file store. The detail, publication and verification boundary follows the Wiki contract; the generated development specifications and the operator manual do not overwrite each other.
1. Platform And UI Packages¶
| Package | Owns | Must not own |
|---|---|---|
@ctc/platform-core |
execution context, UUID types, result/error, clock/ID/idempotency/audit primitives | MySQL, HTTP, React, business records |
@ctc/runtime-config |
validated server configuration and public/secret separation | authorization or business state |
@ctc/identity-access |
authentication/session/principal/role/capability application contracts | SQL/cryptography implementation, business state |
@ctc/platform-administration |
user, role, menu, favorite, tenant/company/settings contracts; target offering-assignment administration contracts | tenant business settlement, payment execution or auth cryptography |
@ctc/policy |
operating profile, capability, typed policy and effective surface; target entitlement/activation resolution | persisted contract writers, pricing/payment execution, business records or customer branches |
@ctc/observability |
redacted logs/traces/metrics and release/request/tenant correlation | business completion authority |
@ctc/design-tokens |
semantic visual/interaction tokens | tenant/business state |
@ctc/ui |
React primitives, forms, overlays, data, feedback, navigation, layout and patterns | business policy, DB/provider |
@ctc/test-support |
deterministic fixtures/builders/fakes | Production dependency |
@ctc/user-wiki |
Wiki contracts and safe rendering; Git-derived read-only development specifications | engineering execution authority, a second operational-manual store or DB writer |
2. Business Modules¶
| Module | Owns | Important facts | Must not own |
|---|---|---|---|
master-data |
Party, Company, Commodity/Grade, UOM, Location, external references | Party, Material, UOM, Location | transaction price/balance/lifecycle |
commercial |
purchase/sales intent, agreement/order, lines, accepted price snapshots | PurchaseOrder, SalesOrder, OrderLine, PriceSnapshot | Booking, inventory, physical execution |
fulfillment |
inbound/outbound execution intent and explicit source links | FulfillmentRequest/Line, SourceReference | Scale, inventory ledger, carrier schedule |
operations |
transload plan, assignment, field/office execution and correction | TransloadPlan, Assignment, ExecutionEvidence | Booking, inventory, settlement |
scale |
weigh session/readings/ticket/correction/void | WeighSession, ScaleTicket, WeightAllocation | price, Booking, inventory ownership |
inventory |
lot, ledger, placement, cost layer and allocation | InventoryLot, LedgerEntry, Placement, CostLayer, Allocation | order, Booking, transport execution |
transportation |
Ocean Booking, Packing source projection, Shipment, Transport Leg, carrier milestones | OceanBooking, PackingProjection, Shipment, TransportLeg | Sales Order, inventory balance, equipment lifecycle |
equipment-lifecycle |
container/chassis assignment, yard/availability/return and photo relation | ContainerLifecycle, EquipmentPhotoRelation, YardPosition | Booking schedule, settlement |
documents |
template, rendering, preview and output metadata | DocumentRequest, Preview, Output, TemplateVersion | source mutation/provider transport |
settlement |
service charge, AP/AR evidence, landed cost and margin projection | ServiceCharge, Settlement, LandedCost, MarginProjection | source process state/provider completion |
Every public record/reference uses UUID.
3. Adapters¶
| Adapter | Owns | Must not own |
|---|---|---|
@ctc/db-mysql |
pool, unit of work, module repositories/read adapters, UUID codec, schema mapping, numeric compatibility bridge, DB errors/readback/reconciliation | public numeric identity, business policy, customer-specific backend authority |
@ctc/file-storage |
object upload/retrieval/delete, metadata, checksum and cleanup | source authorization/relation meaning |
@ctc/integration-ai |
provider request/response, timeout, provider error and safe model metadata | business decision or auto-save |
DB adapter files and exports are named for shared module capabilities, not the first tenant that uses
them. Existing cohort-named adapter debt is COMPATIBILITY_INTERNAL: no new caller/export and no use
as a pattern.
4. Cross-Owner Contracts¶
transportation authorizes Booking relation
-> @ctc/file-storage stores/retrieves object
-> db-mysql persists typed relation
-> transportation rereads relation
scale owns weight evidence
-> inventory receipt command consumes accepted evidence
-> db-mysql performs one transaction
-> inventory rereads Lot/Ledger authority
commercial/fulfillment/inventory/transportation source facts
-> settlement projects approved evidence
-> documents render without source mutation
Current reconciliation — 2026-09-11: operations owns Transload execution state; inventory owns T_INVENTORY_LOT, LedgerEntry and Allocation facts. Transload unload materialization must use the inventory owner in the same transaction and preserve an explicit source-transload link or an equivalent NULL-safe conflict rule. Current source still has separate Transload and physical-receipt lot writers; the NULL SOURCE_TRANSLOAD_ID case and runtime/DB acceptance remain NOT_RUN. Corrective implementation is registered with the existing receipt and Transload owners; implementation and runtime/DB acceptance remain NOT_RUN. This note adds no new authority.
5. Tenant And Profile Composition¶
Target composition (not a claim that subscription persistence/enforcement already exists):
authenticated session
-> server-verified tenant UUID; numeric alias remains in the DB compatibility boundary
-> effective offering assignments and explicit transition grants
-> union of eligible features
-> tenant operational activation within that eligibility
-> pinned operating profile, typed policy overrides and user action permissions
-> record tenant, relationship and business-state validation
-> effective menu/fields/actions/terminology
-> shared module command/query and authoritative readback
Profiles choose approved defaults and surfaces. They do not grant entitlements, assign roles,
select tenant-specific SQL/repositories/writers or rewrite historical business facts. Menu URL
substrings and legacy modules API field names are compatibility terms, not ownership authority.
Current resolver behavior and gaps are in policy/README.md.
Platform administration owns offering-assignment contracts and change provenance; policy resolves
eligibility/activation/effective behavior; identity-access owns principal/role/action contracts;
db-mysql implements persistence and transactions. Existing Admin composition and transport use
these owners. This target adds no new workspace package, public export or SQL writer by itself.
settlement continues to own tenant service/trade settlement, not platform SaaS subscriptions.
Work Operations and Field Execution both use the existing operations business owner. Office and
field capture may have different intermediate commands and surfaces, but share result invariants,
correction semantics and record authority. Do not invent field events for office-entered results.
Transport & Shipping uses transportation; a reference to equipment does not expose all Yard &
Equipment functions. Warehouse & Inventory coordinates fulfillment, inventory and scale
through explicit contracts, not direct writes into another owner's records.
Shared master data, weighing and document support keep their semantic owners. Reuse does not move all business code into platform-core. Internal support calls stay tenant-scoped, permission-aware and limited to the declared projection/use case; they are not an entitlement bypass. Turning off an offering cannot suppress integrity checks or ledger obligations of an existing linked record.
Basic management and advanced operations¶
Basic administration connects these existing owners as an early-foundation correction before dependent migration acceptance; the Task document and git history identify current work. Platform administration owns allowlisted configuration-change intent and audit provenance; policy owns the shared preview/runtime decision; the DB adapter owns the coherent revision-checked transaction and authoritative reread. UI and transport do not duplicate these rules. Old compatibility writers that can race the same state share the concurrency contract.
Phase-5 release/import/support tooling extends this accepted applied-state boundary. It may store release envelopes but cannot introduce a second assignment writer or make ordinary single-tenant management depend on the complete Control Plane. Revision, audit and manual restore are basic safety; restore applies revalidated choices as a new change, not a rewind of business records or permissions.
6. Composition Root¶
apps/web/src/bootstrap/**
Only the Web composition root constructs config, pools, cryptography, provider adapters, command/query handlers and telemetry. No Worker exists until a persistent source and real consumer are delivered together.
7. Admission¶
A new package/module/adapter/public export requires:
- an admitted Product Reality capability and action;
- one exact operator/operational result;
- a previously accepted ADR under
ARCHITECTURE_CHANGE_METHOD.md; - at least three serious options and an independent review;
- distinct semantic state/use cases or a stable provider boundary;
- immediate production consumer;
- typed UUID API and acyclic dependency;
- explicit effect/failure/recovery/rollback;
- focused tests and complexity report;
- proof that it is not a tenant fork, generic bag or advance scaffolding.
First use stays internal unless the boundary is already stable or a second real consumer exists.¶
Source:
new-system/docs/architecture/MODULE_REGISTRY.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged. A user instruction quoted inside the text is kept in its original language.