System Overview and Runtime Foundation¶

Status: CURRENT ENGINEERING BASELINE
Product reality: ../PRODUCT_REALITY.md
External effects: NONE

0. Whole System Overview¶

Purpose And Current Scope¶

One multi-tenant logistics product connects booking, purchase and sales contracts, inbound and outbound execution, weighing, inventory, settlement and documents. Booking is the ocean-booking work among them. The structure does not build a separate programme per customer, and saving a Booking does not perform all subsequent work. The product root is currently new-system/ and ./ after extraction, and the internal paths below are relative to that root. Legacy and reference are external comparison bases.

The current implementation of this overview is source evidence from comparing the apps and package composition, the Web bootstrap and session, and the public connections of tradeData against the stated DB adapter on 2026-09-12. It does not mean DB or browser acceptance of every area, nor a current operational deployment. Target and open are distinguished separately below.

Runtime Composition And Request Path¶

flowchart TB
    U[Work user] --> W[Web: screens and HTTP]
    W --> S[Session: user, tenant, authority, effective policy]
    S --> C[Work commands and queries]
    C --> D[db-mysql: SQL, transactions, re-read]
    D --> M[(MySQL)]
    W --> F[External adapters such as the file store and AI]
    C --> P[Document projection and rendering]
    P --> V[Preview and output]
    T[Shared UI and tokens] --> W
    T --> G[UI Catalog: for development review]

The two running apps are apps/web and apps/ui-catalog. The UI Catalog is for development and does not store customer work records. There is no separate worker, general queue or scheduler app.
src/bootstrap/runtimeConfig.ts in the web supplies the server configuration as a validated object. src/adapters/workspaceSession.ts assembles the authenticated session and the effective tenant, role and policy. A screen or HTTP input is not used as-is as the basis of tenant or authority.
The web composition assembles the public module and DB boundaries. For example src/composition/tradeData.ts connects the real commands, queries and DB adapter of Fulfillment, Inventory, Scale and Settlement. There is currently no separate shared package called packages/workflows or packages/read-models.
SQL and transactions live in packages/db-mysql. A confirmed save result and recovery from an unconfirmed result follow the per-area contract. A successful file store, AI or provider call is not the same evidence as a DB commit.

Per-Module Responsibility And Data Ownership¶

The table below is a map for reading the product's semantic ownership and current connections. It is not a list stating that every target function of a module is implemented and accepted. Even when one physical DB is shared, ownership of each record and command is distinguished.

Responsibility	Owned fact	Connection and detailed basis
Master data	References such as company, item, unit and location	Work references them by UUID. Contract
Commercial	Purchase and sales intent, contracts, items and a price snapshot	Separated from execution orders and inventory. Contract
Fulfillment	Inbound and outbound execution orders, items and source linkage	`T_LOAD`/`T_LOAD_ITEM` differ from a commercial contract. Contract
Operations	Transload planning, assignment, field and office execution, and correction	Does not own booking, inventory or settlement on their behalf. Contract
Scale	Weighing input, ticket, correction and cancellation evidence	`T_SCALE_TICKET` is evidence consumed by inbound finalisation. Contract
Inventory	Inbound lots, the inventory ledger, placement, allocation and reversal	`T_INVENTORY_LOT` is created by an explicit inbound command, not by a booking header. Contract
Transportation	Booking reservation, schedule and Packing source projection	Distinguishes the link from `T_BOOKING` to an execution order. Data specification
Equipment lifecycle	Equipment assignment, yard, return and photo relations	Does not merge a booking schedule with an equipment return state. Contract
Settlement	Billing, purchase and sales source, cost and difference projection	The current query is compared against `T_TRANSACTION`/`T_TRANSACTION_LIST` and the pricing source. It is not a completed payment or accounting posting. Contract
Documents	Template, rendering, preview and output metadata	Output does not mean a change to the work source or a successful dispatch. Contract

The public work identifier is a UUID, and numeric compatibility stays inside an approved DB adapter. Whether the physical column widths, keys, enums and foreign keys also exist in the current DB requires comparing the real schema. The logical relations in the document, or a dump alone, do not settle that constraint. The overall ownership baseline is maintained in the Module Registry.

How The Main Work Connects¶

A purchase or sales contract records a trading intent. A Fulfillment execution order receives the items, schedule and source reference, and connects to the real inbound or outbound plan, but saving an order alone neither creates nor consumes inventory.
Inbound finalisation checks the source order and item, the quantity, the warehouse location and the weighing evidence the policy requires. The current trade/inventory-write.ts reads the source and location in the same tenant scope and records T_INVENTORY_LOT. When a location is chosen, placement is a separate transaction, so placement can fail after inbound finalisation. The receipt and placement design distinguishes retry, correction and reversal, and the effect on later allocation and use.
Outbound links demand with inventory allocation and loading. Booking supplies the carrier reservation, schedule and equipment plan, and the required booking and commercial-contract preconditions are judged by the effective policy. Direct allocation and a physical lot are distinguished.
Packing combines the execution and equipment source with an output overlay. The write scope of edit, restore and execution pricing is distinguished in the Booking design.
Settlement compares the work source, pricing and billing material, and the documents output that projection. Save, billing, payment and dispatch are not treated as one success state. After a source change a re-read and a follow-up impact check are needed.

Shared Functionality And Per-Client Differences¶

Session, tenant isolation and authority, reference data, the file and AI adapters, shared UI, observation logs and Wiki reading all use a shared owner. Settings and profiles supply application differences in presentation and policy, and do not create a new writer per customer. Authority or menu exposure alone does not decide acceptance of real work execution.

Class	Specification basis	Not settled by this document
Client 1	External Legacy work, screens, APIs and schema material, and the product correspondence	Replacing a C2 reference with C1 rules, or publishing a new C1 user manual
Client 2	The work and forms of the external `reference/mkmetal`, and the current product	Treating reference status or company column names as identical to native status or roles
Shared implementation	The `execution-service`/`trade-inventory` operational profiles, typed policy, and the effective settings per tenant	Using a numeric Client ID as a package or module owner

Reading The Detail Specifications For Current Implementation, Target And Open¶

Current implementation: the two apps above, the public module and DB assembly, reading the individual Booking specifications, and the explicit inbound, allocation and weighing commands and the settlement projection were confirmed in source. Writing this overview did not run an operational environment.
Target: a single record ownership, tenant isolation, source-to-follow-up-impact tracking and safe correction must actually hold in every area. A target package or setting name alone does not declare introduction or acceptance.
Open: the booking state and company role mapping, the real DB constraints, the copy consumer and real per-role execution remain in the Booking test/RTM. Recorded exceptions in the other areas are checked in the Task that owns the source. Phase-3 acceptance and exceptions stay as they are.
Read next: Booking Requirements → work composition → detailed design → data and interface → screens → test and traceability.

This document is the detailed basis built on the runtime. The default entry point is the nine whole-system specifications. It first defines the shared content and the table of contents of every area, and then details each chapter. Implementing Booking, achieving real acceptance, or completing the C2 manual are not prerequisites for writing the system document structure.

1. Toolchain¶

Tool	Pinned version
Node.js	`26.8.1`
pnpm	`11.21.0`
Next.js	`16.3.1`
React / React DOM	`19.2.8`
TypeScript	`5.9.3`
ESLint	`9.39.5`
Prettier	`3.9.6`
Vitest	`4.1.10`
Playwright	`1.62.1`

Exact versions and the lockfile are binding for this Foundation candidate.

Node 26.8.1 is the official Current release, not LTS, as of 2026-09-02. Next.js 16.3.1 requires Node 20.9.0 or newer, and pnpm 11.21.0 supports Node 26. The retained exact versions were verified against the official Node release, Next.js system requirements and pnpm compatibility table.

2. Current Applications¶

Application	Runtime class	Local port	Health	Readiness	Release identity
Web	Product runtime	`3000`	`/health`	`/ready`	`/release`
UI Catalog	development executable	`3001`	`/health`	`/ready`	included in responses

Web and UI Catalog build and run independently. They do not import one another.

No Worker application exists. A future Worker requires an admitted Product Reality capability, persistent source and real consumer in the same bounded slice. An empty queue/scheduler/retry framework is not a runtime.

3. Application Responsibilities¶

Web¶

Next.js routes and rendering;
application composition root;
session and concrete Web adapters;
health/readiness/release identity;
operator-facing Product pages.

Web does not own business rules, SQL, provider durability or durable background jobs.

@ctc/observability owns redacted structured logs, traces, metrics and release/request/tenant correlation. Logs never include passwords, session tokens, secrets, protected documents or full sensitive payloads, and do not replace immutable business audit evidence.

UI Catalog¶

executable shared token/component/pattern examples;
compact Foundation states and recovery compositions;
visual and interaction reference for shared UI.

UI Catalog does not own Product pages or business mutations.

4. Runtime Configuration¶

@ctc/runtime-config is the versioned server configuration contract. Server bootstrap/config loaders may read process.env; application and package code consume validated public/secret partitions.

Versioned non-secret inputs:

CTC_ENVIRONMENT = local | development | qa | production | test
CTC_RELEASE_ID  = local by default
PORT            = validated integer 1..65535 when supplied

Web session inputs include absolute/idle TTL, signing-key rotation metadata and secure-cookie policy. Production Web parsing requires the approved DB/session inputs and a non-local release identity. Validation errors name fields without printing secret values.

5. Evidence Boundary¶

Evidence	Current status
source/toolchain contracts	ENGINEERING VERIFIED at recorded revision
local Product runtime	capability-specific; see `PRODUCT_REALITY.md`
live DB	`NOT_RUN` unless exact acceptance evidence says otherwise
authenticated target-role browser	capability-specific
QA runtime	capability-specific
Production runtime	separately authorized

A source build does not prove runtime, role, data, performance or deployment.

6. Local Runtime Procedure¶

Package scripts describe build and development capabilities; they are not authorization to operate the local Web listener. Follow the local Web runtime runbook: start, stop and recover Web only through com.ctc.new-system-web, then verify /health and /ready. The Web build uses Next.js standalone output. Production secrets come from the approved runtime secret store and startup fails before listening when required inputs are absent.

Local start/stop and rollback¶

start, stop and recover Web through the approved service runbook and verify /health and /ready;
for source rollback, stop the candidate, restore the last verified Git revision through the authorized Git workflow, rebuild and reread /release, /health and /ready;
DB/data, provider, route/writer and Production rollback remain separate authorized effects.

7. Verification¶

pnpm product:validate
pnpm verify
pnpm test:e2e

pnpm product:validate verifies capability admission and removal state.

pnpm verify covers document authority, Product Reality, lint, type checks, unit tests, architecture, quality, catalog and all admitted application builds.

pnpm test:e2e proves only the scenarios it actually runs.

8. Unsupported Claims¶

An ignored or generated path is not runtime authority.
A package name is not implemented capability.
A registered page is not an accepted workflow.
A Git ref is not deployment evidence.
A future background use case does not justify a dormant Worker.

Source: new-system/docs/architecture/RUNTIME_FOUNDATION.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.