System Architecture Design (SAD)

0. Document Control And Design Views

Item	Baseline
Document ID / type	SPEC-SAD / System Architecture Design
Upper contract	SRS, Product and the Module Registry
Design views	context, logical module, runtime, data, integration, security, and deployment and operations
Applicability	the current implementation, the target structure, and what is unwritten or unresolved are separated
Basis	C1 Legacy and C2 reference and New-System are not mixed
Approval and review	the review of the document structure is separated from the architecture and operations approval and the deployment evidence

Each view links the interests of the stakeholders, the quality goals, the reason for a choice, the alternatives, the risks and the verification method. The technology choices, numbers and layout examples in the template are not adopted as decisions of the current system.

1. Design Scope And Criteria

This document covers the execution boundary, the responsibility split, and the data and external linkage boundaries that connect the whole work of SRS in one system. It is not a Booking-only architecture. It links the existing runtime foundation and the module responsibility criteria and keeps the distinction between the implementation point and the target in those documents. This comparison is about the document structure and the existing contract criteria, and it does not verify the current operational deployment.

2. System Boundary And Runtime Composition

flowchart LR
    User[Work user] --> Web[Web screen and HTTP]
    Web --> Access[Session, tenant, authority and policy]
    Access --> Modules[Work commands and queries]
    Modules --> DB[DB adapter and transaction]
    DB --> MySQL[(MySQL)]
    Modules --> Projection[Document source query and rendering]
    Web --> Adapters[External adapters such as files and AI]
    Catalog[Development UI Catalog] --> UI[Shared UI and tokens]
    UI --> Web

Web assembles the request and the screen, and the work owner handles the commands and queries. SQL stays in the DB adapter. Document rendering, file storage and external dispatch are effects other than a work record save. The UI Catalog is for development and is not the owner of a work record. No new Worker, queue or service is created because of this document.

2.1 Current Identifier Transition UML

This is the identifier boundary compared against the 2026-09-21 Production information_schema and the current source. The public and API contract is a UUID, and a numeric ID is left only for Legacy compatibility. Because some relations are currently ID-only, the CompatibilityAdapter below is still needed, but it is a removal target in the target structure.

classDiagram
    class WebSurface {
      +UUID requestIdentity
      +sendCommand()
      +renderReadModel()
    }
    class ApplicationOwner {
      +validateTenant()
      +executeCommand()
      +readByUuid()
    }
    class DbMysqlAdapter {
      +persistUuidRelation()
      +authoritativeReadback()
    }
    class CompatibilityAdapter {
      +resolveUuidToLegacyId()
      +dualWriteDuringTransition()
    }
    class BusinessTable {
      +BINARY(16) UUID
      +BINARY(16) relation_UUID
      +BIGINT legacy_ID
    }
    class LegacyPhp {
      +numeric compatibility callers
    }

    WebSurface --> ApplicationOwner : UUID-only command/query
    ApplicationOwner --> DbMysqlAdapter : typed UUID relations
    DbMysqlAdapter --> BusinessTable : UUID read/write
    DbMysqlAdapter --> CompatibilityAdapter : transitional only
    CompatibilityAdapter --> BusinessTable : legacy ID mirror
    LegacyPhp --> CompatibilityAdapter : staged migration

A forbidden target structure is one where the API exposes a numeric ID again, or where a UUID input is validated and then only a numeric ID is stored permanently. A current table without a UUID relation column is managed through the gap list of the data and ERD specification. After a relation UUID is applied, the Legacy reader and writer are switched, and the numeric relation columns and the compatibility adapter are removed in the last step.

3. Logical Modules And Area Placement

Area	Design responsibility	The neighbouring responsibility that must be separated
Administration, access and settings	identity-access, platform-administration and policy	the work ledger, the price and the physical execution
Master data	master-data	the trade price and state
Trade	commercial	the reservation and the physical inventory
Inbound and outbound	fulfillment	the weighing evidence and the inventory ledger
Field work and Transload	operations	the separate ownership of the reservation, the settlement and the inventory
Weighing	scale	the ownership of the price and the inventory
Inventory and warehouse	inventory	the commercial contract and the transport execution
Transport and Booking	transportation	the order, the inventory remaining quantity and the equipment lifecycle
Equipment and yard	equipment-lifecycle	the booking schedule and the settlement
Documents and output	documents	modifying the work original and the provider transmission
Billing and settlement	settlement	the source work state and the payment and provider completion

This table is a system-view summary of the existing responsibility criteria. The real file, public contract and transaction units are linked in SDD. It does not mean every target module capability is implemented.

4. Data, Integration And Security View

A public record and reference is a UUID, and a numeric mapping and SQL stay inside the DB adapter. A shared physical DB and a semantic writer ownership are different. The tenant, role and valid policy are composed in the authenticated session, and the target record and relationship are verified. A screen menu or a Client input is never a substitute for a server authority.

An external file, AI, device or dispatch distinguishes the target and the failure and recovery in the interface specification. A DB commit is not treated as a provider success, and a provider call is not put inside a DB transaction. Client 1 uses the external Legacy, and Client 2 uses the external reference and the internal implementation as the basis for the described difference.

5. Cross-Area Cooperation And Detail Views

Commercial intent → execution order → weighing and work evidence → inventory and allocation → transport and equipment → document and settlement is an order that explains the connection, not a single workflow that every transaction must pass through. The per-area preconditions and the branches and independent state are defined in Sequence And State.

The existing Booking system boundary of the transportation area is one detail view. Receipt design in the inbound and inventory area is also a detail view inside the same system. The runtime placement and external linkage detail views of the other areas are unwritten, and the responsibility table is not promoted to implementation evidence.

5.1 Separation Of The Current Implementation From The Target Model

View	Current source-confirmed structure	Target direction or open item
Execution context	the Legacy scalar tenant and a selected typed TenantExecutionContext coexist	applying the typed context to every caller and combining the profile, capability and action is incomplete
Commercial and execution	Agreement is T_COMMERCIAL_ORDER; execution is T_LOAD; service and appointment are in the T_TRANSLOAD family	an explicit lifecycle of the three aggregates and the bridge
Work	T_TRANSLOAD and T_LOADING_PLANNER mix the plan, assignment and execution mirror	separate Plan, Assignment, ExecutionEvidence and CorrectionEvidence; the canonical of the two existing representations is unresolved
Weighing	T_SCALE_TICKET and an optional event adapter	the whole policy and the real schema of ScaleCorrection, Void and Reconcile are undetermined
Inventory	the lot, the remaining balance, the location and the allocation relation are spread over several tables	explicit ownership of identity, balance, placement, allocation and the cost layer
Transport	Booking, Delivery, Yard, Equipment and Return are independent current sources	Shipment and TransportLeg are candidates and persistence is unimplemented
Documents	several work sources are rendered as an HTML preview	the issue, storage and transmission lifecycle and the provider evidence are separately incomplete
Settlement	a source read projection and some calculation	finalisation, posting and payment and the margin and landed-cost policy are incomplete

In this table, a target is not an approved completed implementation. It places a candidate from an existing source-reconciled document in the system design. It is not the authority to remove the current compatibility path or to create a new aggregate.

5.2 Cross-Area Effect Boundary

flowchart TB
    Agreement[Commercial Agreement] -->|explicit source| Fulfillment[Execution Order]
    Fulfillment --> Work[Field work]
    Scale[Weighing evidence] --> Receipt[Receipt command]
    Work --> Receipt
    Receipt --> Lot[Inventory Lot·Ledger]
    Lot --> Allocation[Allocation]
    Booking[Ocean Booking] --> Outbound[Outbound Execution]
    Allocation --> Outbound
    Outbound --> Delivery[Transport/Equipment Execution]
    Agreement --> Docs[Document Projection]
    Booking --> Docs
    Lot --> Docs
    Docs --> Settlement[Billing/Settlement Projection]

An arrow is a candidate explicit reference and evidence consumption, not an automatic cascade. The command, transaction, and failure and resume method of each connection are defined in SDD and Sequence And State. A document or settlement projection has no source mutation authority.

5.3 SYS-F05 Transload Architecture View

flowchart LR
    UI[Planning·Assignment·Loader·Office UI] --> Web[semanticTransloadRoutes]
    Web --> Ops[operations/transload public owner]
    Ops --> DB[transload DB readers·writers]
    DB --> TR[(T_TRANSLOAD)]
    DB --> PL[(T_LOADING_PLANNER)]
    DB --> TM[(T_STAFF_TIME_EVENT)]
    DB --> FI[(T_FILE)]
    Ops --> Yard[Yard queue·location owner]
    Ops --> Equip[Equipment·load owner]
    Ops --> Inv[Inventory receipt·placement owner]
    Ops --> Effect[Operation event·provider effect]

ARC ID	Responsibility boundary	Architecture verdict
TRN-ARC-01	the Web route → the Operations public contract → the DB reader and writer	the UI and HTTP assembly is not the semantic owner of the SQL or the Transload state
TRN-ARC-02	Appointment, Plan, Assignment, Execution and Office Confirmation	the save and decision point of each is preserved instead of being reduced to a single STATUS
TRN-ARC-03	Yard, Equipment and Inventory	Operations calls an explicit owner command and does not directly own the neighbouring ledger
TRN-ARC-04	File, event and provider	the success and failure of the work DB commit and the external effect are separated, and the authoritative read-back takes priority
TRN-ARC-05	Client application	the C1 Legacy Loader flow is preserved, and C2 applies the Office and common path according to the reference and New-System capability

T_OPERATION_EVENT is a notification and event projection, not the canonical record of a work completion. A Transload step is not forced into the non-physical C2 order and brokerage flow. Because the target canonical of the SPECIAL_INSTRUCTION representation and the ASSIGNMENT_DATA representation of an assignment is not yet decided, the architecture does not arbitrarily discard one of them.

5.4 SYS-F06 Scale Architecture View

flowchart LR
    UI[Scale Portal·Ticket Editor] --> Web[scaleTicketsRoute]
    Web --> Scale[scale public owner]
    Scale --> Adapter[scale evidence/read/write adapter]
    Adapter --> Ticket[(T_SCALE_TICKET)]
    Adapter --> Event[(T_SCALE_TICKET_EVENT)]
    Fulfillment[Fulfillment Order] --> Scale
    Scale --> Bridge[Transload·Equipment Load link]
    Ticket --> Receipt[Inventory Receipt consumer]
    Ticket --> Other[Delivery·Settlement consumers]

ARC ID	Responsibility boundary	Architecture verdict
SCL-ARC-01	the Scale Portal and Editor → the semantic route → the Scale public owner → the DB adapter	Web is the authentication and request assembler, and the Scale owner handles the weight evidence and the correction meaning
SCL-ARC-02	T_SCALE_TICKET	the current authority of the accepted stage readings and the ticket identity
SCL-ARC-03	T_SCALE_TICKET_EVENT	the optional authority of the correction, void and reversal lineage; an environment without the schema is distinguished as SCHEMA_NOT_APPLIED
SCL-ARC-04	Fulfillment, Transload, Equipment, Inventory, Delivery and Settlement	a separate owner that explicitly links and consumes the ticket, and Scale does not own the completion of that work
SCL-ARC-05	Client and device application	the C1 field and office difference and the C2 Office-centred difference are preserved as a policy or provenance; a per-tenant Scale replica owner is not created

The LB correction event record of the current implementation is not expanded into a whole-system UOM or display rule. The device connection and offline capture, the conversion registry, the precision and rounding, and no-scale eligibility stay architecturally unresolved until a real contract is approved.

5.5 SYS-F07 Inventory Architecture View

flowchart LR
    Source[Order·Item·Transload·Scale Evidence] --> Receipt[Receipt Command]
    Receipt --> Lot[(Inventory Lot)]
    Receipt --> Ledger[(Ledger·Provenance)]
    Lot --> Placement[Placement Owner]
    Lot --> Allocation[Allocation Owner]
    Allocation --> Target[Outbound Item·Container]
    Lot -. separate .-> Cost[Inventory Cost Layer]
    Allocation --> Docs[Documents·Billing Projection]

ARC ID	Responsibility boundary	Architecture verdict
INV-ARC-01	the Receipt source and policy → the Inventory command	Order, Transload and Scale are the input basis and are not the owner that creates a lot
INV-ARC-02	the lot identity, balance, ledger and placement	the four facts and the transaction and read-back are separated even when the physical DB is shared
INV-ARC-03	the allocation relation → the outbound item and container	it owns the source consumption and the target execution link, and does not own the Booking or Delivery completion
INV-ARC-04	correction, reversal and reconcile	an immutable lineage and an exact identity are used, and a downstream document or billing is re-judged per owner
INV-ARC-05	C1 custody and C2 owned stock	the material ownership, the owner and custody party, and the costing applicability are distinguished as a persisted fact or policy

Inventory Lot ≠ Balance ≠ Placement ≠ Allocation ≠ Cost Layer is used as an architecture invariant. The CTC bale and count and the C2 owned-stock requirement are not merged into a single number or state.

6. Placement, Separation And Quality Decisions

The per-environment process, network, storage and external dependency placement and the performance, capacity, availability and RTO and RPO numbers are recorded when the real criteria are confirmed. The current document defines the logical boundary and the owner, and does not infer the Production placement state.

7. Architecture Decision And Review Card

Field	Authoring criteria
ARC or ADR ID and state	the proposal, approval, replacement and retirement, and the applied revision
Requirement and quality scenario	the stimulus, environment, target, expected response and measured value
Choice and alternatives	the reason for the choice, the excluded alternative, the constraints and the cost
Boundary and dependency	the owning module, the allowed and forbidden dependency, and the trust and data boundary
Runtime and deployment impact	the process, the transaction, the failure isolation and the rollback
Verification and risk	a structural check, real environment evidence, the remaining risk and the re-review condition

The design review checks requirement traceability, the single writer, tenant isolation, the separation of the transaction and the external effect, failure and recovery, observability, and deployment and rollback. When a decision changes, SDD, DATA, INTERFACES, TESTS and RTM are re-reviewed together.

The internal product paths follow apps/, packages/, docs/ and catalog/. The internal links and the structure are kept even if the current product folder becomes the root of a separate repository. Legacy and reference are an external basis, and the parent folder is not assumed to exist permanently. It follows the product structure criteria.

The performance, availability and recovery goals and the per-environment fixed values of the deployment topology are follow-up detail items. A design decision is linked to the corresponding decision in the existing docs/decisions/, and a deployment or service task is not executed because a document was corrected.

Source: new-system/docs/specifications/SAD.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.