CTC Logistics Workspace Design

• Status: CURRENT TARGET DESIGN
• Product: PRODUCT.md
• Roadmap: ROADMAP.md
• Execution: EXECUTION.md
• Modules: architecture/MODULE_REGISTRY.md
• Historical implementation and acceptance evidence: operations/README.md

1. Runtime Boundary

Portal availability is Role×Screen per ADR 0023; device/viewport never selects Portal. Office uses AppShell tabs, Mobile uses tabless MobilePortalShell.

Browser
-> explicit route owner
   -> Legacy Runtime for unmigrated/fallback paths
   -> New Next.js Web for accepted Logistics Workspace paths

New Web
-> typed transport adapter
-> application command/query
-> semantic module owner/port
-> MySQL or provider adapter
-> authoritative readback / explicit effect reconciliation

A Logistics Workspace failure must not break unrelated Legacy operation.

2. Delivery Architecture

Foundation is not a horizontal phase that must expand indefinitely before Product work.

one real operator journey
-> only the shared capabilities required now
-> actual read/write/provider evidence
-> measured correction
-> next bounded slice

Existing Foundation packages remain valid at their recorded evidence levels. They are extended only when the active Product slice has an immediate consumer.

3. Modular Monolith

The target remains one modular monolith.

apps
-> semantic public contracts / policy / UI
-> platform-core

semantic modules
-> platform-core / policy / declared public contracts
-> ports

db-mysql / integrations
-> implement ports

-> presentation adapters only

Rules:

• platform/application/domain code has no concrete MySQL/provider/UI dependency;
• apps and route handlers own no business SQL or transaction;
• no customer package or backend fork;
• no cross-module table/repository access;
• no circular/deep imports;
• concrete dependencies are wired in bootstrap/composition roots.

4. Integrated Booking Workspace

Phase 1 uses Booking to prove the Product Core.

Booking List
-> Booking Workspace
   -> Summary / Status
   -> Core / Parties
   -> Schedule / Routing
   -> Equipment / Containers
   -> Files
   -> Photos
   -> Packing / Confirmation
   -> Instructions / AI Review
   -> Save / Conflict / Recovery

The workspace is one coherent context, not one monolithic component.

Shared workspace context

tenantUuid
bookingUuid?
profile
capabilities
bookingVersion?
summary
dirty state
conflict state
recovery state

Feature boundaries receive typed UUID context. Numeric aliases, DB rows and plugin globals do not cross the boundary.

5. Booking State And Write Model

UUID route/input
-> authentication and capability
-> transportation command/query
-> same-tenant reference validation
-> db-mysql transaction
-> atomic UUID/numeric coexistence where required
-> affected-row/conflict classification
-> authoritative UUID reread
-> typed success/error/recovery

Create and update are separate commands. Unknown mutation results are reread before retry. A provider call never runs inside the Booking transaction.

6. File And Attachment Model

Object storage and business relation are separate authorities.

upload intent
-> object stored
-> metadata recorded
-> Booking relation recorded
-> authoritative relation readback

Possible partial states are explicit:

object stored / relation absent
relation present / object unavailable
delete requested / still referenced
cleanup pending / cleanup complete

The file adapter owns storage transport, object metadata, checksum, retrieval and cleanup. The owning semantic module authorizes and owns the relation.

7. Photo Model

Photos reuse the file transport but have equipment semantics.

image object
+ equipmentUuid relation
+ category / sequence / representative state
= Equipment Photo

equipment-lifecycle owns relation, order and equipment validity. Image decoding, orientation, resize and preview may reuse copied modernization helpers behind typed adapters.

8. Packing And Confirmation Model

Booking facts
+ Equipment / Container facts
+ Commodity / Quantity / Weight
+ profile-required Reference / Rate
+ supporting attachment/photo references
= versioned Packing source projection

Ownership:

• transportation: Booking and Packing source projection, accepted edits;
• equipment-lifecycle: equipment/container facts;
• documents: template, rendering, output metadata;
• file adapter: supporting object retrieval;
• apps/web: workspace composition.

These are distinct states:

source valid
preview rendered
durable output created
provider delivered

A rendered page is not automatically a durable document or delivered effect.

9. AI Booking Reader

instruction file
-> provider adapter
-> typed extraction result
-> transportation field mapping/validation
-> source + proposed-value review UI
-> apply to unsaved form
-> normal Booking validation/save

AI never owns Booking state and never auto-saves. Provider failure preserves manual entry. Source content, secrets and protected payloads are not written to operational logs.

10. UI And Plugin Model

design tokens
-> React-native primitives/patterns
-> copied-plugin typed adapters where justified
-> Booking composition

Valid strategies:

COPY_AND_OWN
NATIVE_REACT

A copied plugin:

• records provenance and dependencies;
• has no root Legacy runtime dependency;
• loads only for active consumers;
• exposes typed application-neutral behavior;
• owns no policy, SQL or transaction;
• supports cleanup, accessibility and performance measurement;
• remains replaceable.

KJTable, KJModal and KJView runtime reuse is prohibited in New-System. Use the shared Native DataTable, forms and Dialog. The monolithic copied Booking editor is transition/reference evidence, not the target component boundary.

11. Phase-3 Visual Migration Contract

Shared UI authority (2026-09-11, direct Product-owner request): Inbound Purchases and Outbound Sales are the reference for both lists and ordinary create/edit popups, considered separately. Sections 12.1–12.3 define the shared implementation. This supersedes the earlier Booking-first popup reference. Booking and Transload lists remain valid shared-table consumers; their specialized popup summaries, previews, equipment and linked workflows are local business composition, not the template for ordinary forms.

Current comparison scope (2026-09-11, direct Product-owner correction):

Scope	Preserve or restore	Visual treatment and acceptance baseline
CTC pages, tables and popups	Executable Legacy columns, names/types/order/grouping, business button placement/grouping, click actions, selection scope, navigation/return, validation and operator process	Use common UI appearance; compare the same role/data/state against Legacy for business structure and workflow
Client 2 pages	Current New-System page composition, columns, actions and workflow; the Product owner will handle individual page changes separately	Current approved New-System screen plus shared-UI before/after evidence; no CTC Legacy layout reconstruction or Legacy screenshot prerequisite
Shared UI across both	Existing behavior and tenant theme semantics	Shared margins/gaps, button/control sizes, typography, color, borders, focus, accessibility and responsive mechanics through existing tokens/components

A generic toolbar or form recipe must not relocate, merge or omit CTC business commands required by Legacy continuity. Restore their order, grouping and placement through existing component slots; add only the minimum shared capability if those slots cannot express the required composition. Do not copy Legacy page CSS, DOM or plugin runtime. Common appearance differences from Legacy are intentional, not pixel-parity defects. Preserve previously requested cosmetic changes such as removing close-only Cancel; retain actual cancellation/rollback commands and their business semantics. Client/cohort names identify comparison scope only: do not add client-ID branches, packages or policy. A route slug, mk-* filename or old manifest label alone does not establish the actual tenant scope.

For each affected screen, record the actual tenant/role, representative data or disposable fixture, viewport/state, source revision, applicable baseline and current render, and comparison result. CTC evidence compares business composition/actions with executable Legacy and appearance with the shared recipe. Client 2 evidence compares its current approved Workspace baseline and confirms that shared changes preserve its own process. Missing CTC Legacy access blocks only that comparison; it does not create a Client 2 Legacy requirement or block unrelated shared work.

Keep operational and visual evidence separate. Screenshots do not prove save/readback, permissions, linked workflows or cleanup. Source/typecheck/HTTP results do not prove either acceptance axis. Unexecuted role/DB/behavior cases remain unaccepted; this scope correction does not close them. Independent review and explicit Product-owner disposition remain required for final acceptance or unrequested business differences. Attachments and old capture plans are dated inputs subordinate to this section, not instructions to recreate Client 2 or copy Legacy appearance.

12. Experience Design

Desktop

• compact list remains the primary scanning surface;
• workspace is a large, structured overlay or page-level workspace;
• header exposes Booking identity, status and critical schedule;
• main sections use progressive disclosure;
• preview/review uses split-pane or adjacent context where useful;
• Save, header close and recovery actions remain predictable; popup forms have no close-only Cancel button.

Small screen

• workspace becomes full-screen;
• no required capability is removed;
• sections remain navigable;
• primary actions remain reachable;
• preview and review preserve context.

Interaction

• URL owns shareable list/workspace state;
• server/application owns authoritative data;
• client owns ephemeral selection, focus and unsaved form state;
• close restores list selection, scroll and focus;
• superseded requests are aborted;
• loading, empty, denied, error, retry and partial-effect states are explicit.

12.1 Shared popup-form design

This is the default for all new and existing popup-form development, including create/edit, compact and wide editors. Apply it without requiring a separate style decision for each popup; deviations require explicit Product-owner direction. This contract defines the target, not a claim that every existing popup has already passed migration acceptance.

The existing Dialog and WorkspaceDialog automatically use ctc-dialog--form; compose existing FormSection, form controls, SummaryCard, DocumentPreview, CommandGroup and DataTable. Do not rebuild these components in a page. The recipe lives in @ctc/ui (contract.css), with its neutral tokens and locally hosted IBM Plex Sans in @ctc/design-tokens. Page CSS owns only unique geometry.

Element	Exact direction
Typeface	IBM Plex Sans 400/500/600; system sans fallback; locally hosted Latin variable font, font-display: swap
Hierarchy	dialog title 18px/600; section heading 14px/600; values 14px/400; labels 12px/400; normal case
Surface	white form body #fff; foreground #14141a; label #6b7280; boundary #e5e7eb; input underline #d8dce3
Header and summary	tenant primary background; on-strong text and close icon; summary uses 24px padding and 6px corners; fact tiles mix 90% primary with on-strong, with a 16% on-strong border and 12px 14px padding; switch states stay distinguishable on primary
Accent	inherit tenant --ctc-action-primary; hover/active use existing semantic tokens; never hardcode the mockup purple
Frame	10px corners; header 20px 24px; body 24px; footer 16px 24px; subtle dividers; backdrop 40% black
Fields	white, 1px underline, square corners, 6px 2px padding, 6px label gap; focus underline uses primary
Text areas	1px full border, 6px corners, 10px padding, 64px minimum height; remain resizable
Sections	unboxed, 18px row / 28px column gap; heading-width × 2px primary underline below heading; 48px effective gap between vertically stacked form sections (16px stack gap + 32px section margin)
Actions	primary filled button; no Cancel button (header close and Escape retain dirty protection); 14px/500, 9px 20px padding; footer remains outside body scroll
States	retain required labels, disabled distinction, danger errors, focus visibility, loading, conflict and dirty-close; do not invent an Open status

Booking Create retains form and instruction preview side by side on desktop. Edit retains summary, flags, grouped fields and equipment table. Keep existing field order and document/clone actions; never force a large operational editor into the mockup's 620px width. Narrow layouts stack existing content without dropping fields; at 640px and below the dialog fills the viewport and actions wrap. Tables remain tables and keep their operational data/selection behavior.

Inbound/Outbound Create/Edit are the approved ordinary-popup reference. Every popup uses the same shared recipe; custom Menu and Wiki editor frames reuse Dialog. Retain business cancellation commands; remove only close-only Cancel buttons. Compare representative create/edit, compact and wide forms at fixed viewports. Check desktop and narrow layouts, scroll/footer reachability, focus, native date input, autocomplete, unsaved-close and inherited primary colors. Fixed comparisons belong in the existing acceptance evidence directory; reusable mechanics belong in the shared recipe, design decisions here, and reproducible failures in focused checks. A screenshot is visual evidence, not saved-data or Production acceptance. Remove replaced page-local styling rather than stacking overrides.

Choice controls and Legacy parity

• Multi-selection always uses Tom Select through the shared form owner, including Autocomplete multiple mode. A native multi-select list is never the operator-facing control.
• Fixed choices such as Inbound Equipment Type use a single-select populated from the applicable tenant master/reference table. Preserve its keys, labels and ordering; do not substitute free text or hardcoded fallback lists.
• Company, equipment and Booking relationships use tenant-scoped reference choices and persist the selected UUID through the existing command. A selector is incomplete if saving ignores its value.
• For CTC popups, compare executable Legacy fields, labels, section/order, requiredness, relationships, button placement and workflows; current forms may have omissions. For Client 2, preserve its current approved New-System composition and process under Section 11. Apply only explicitly requested behavior changes, including removal of close-only Cancel buttons.
• Do not add unrequested Evidence, UUID or debug fields, such as Delivery Evidence or Scale UUID. Restore missing actions through their actual commands; identify unavailable backends as incomplete rather than adding cosmetic buttons or substituting a different action.
• Keep the Inbound/Outbound 48px effective gap between sequential form sections so the next legend does not touch the preceding input. Preserve the heading/field spacing and nested grid gaps defined by the shared recipe.
• In a dialog body, directly stacked fields use a 16px gap (--ctc-space-4). Keep --ctc-field-gap for the label-to-control relationship only; it is not the gap between fields.
• Use Button's icon slot for visible symbols such as Create's plus; do not embed the symbol in the label. FormSection actions use the same 30px, 4px × 12px button rhythm as collection actions.

Before marking a popup complete, verify its Section 11 field/action baseline comparison, actual button behavior, and edited values through save/readback, in addition to the visual checks above. Record unavailable checks separately; applying the shared appearance alone does not establish functional parity.

12.2 Shared table and collection core

The approved outbound_sales_table_mockup.html extends the popup token set through the existing DataTable and CollectionToolbar defaults. ProductSurface collections inherit ctc-collection--light; every DataTable automatically uses ctc-data-table--standard, including embedded tables. CollectionToolbar defaults to date range → Refresh → Filters on the left and page-specific business actions followed by Create on the right. Section 11 CTC business placement takes precedence over this default. CollectionPagination owns the gear on the left and page-size/record-range/page movement on the right; the gear first offers Columns and Rules, then opens the selected tool. Callers supply business action order/grouping/placement, columns, rules and handlers through shared composition; do not duplicate toolbar styling or create a second toolbar engine. Reuse local IBM Plex Sans and tenant primary; the attachment's fixed purple and sample rows are not Product values. No Tailwind or second table engine is needed. The unused live tailwind-runtime.css artifact was removed; preserve all real columns, ordering, filters, sorting, selection, pagination and APIs.

• White full-width collection surface, no per-page outer card or padding; title 18px/600 when present; table values 13px.
• Headers 11px/600, uppercase, 0.04em spacing, muted color and hairline separators.
• Resize-enabled DataTable leaf headers (th[data-column-key]) expose a col-resize cursor; selection, group headers, sort and filter controls do not advertise resize independently.
• Collection QA covers Outbound and Inbound in cobalt and indigo: IBM Plex Sans, compact row scanning, themed checkbox affordance, toolbar/pagination alignment, and resize cursor where the consumer enables it.
• Row hover uses 4% primary tint; category tags use 8% primary tint with primary text, 12px/500, 2px 8px padding and 6px corners. These are reusable table patterns, not status badges.
• Identifier links use primary and underline on hover; empty values use a muted em dash.
• Date ranges use the existing joined boxed control with internal separators; retain date navigation and clear actions. The default places Refresh after the date range, then Filters; table-specific actions such as Sales contracts precede Create on the upper right. Preserve required CTC Legacy business placement and Client 2 current composition under Section 11 when they differ from this default. Do not add a global Search by default; preserve page-specific search only where the workflow requires it. The footer keeps the gear on the left and 1–10 of 2248 with pagination on the far right; narrow toolbars wrap without dropping controls. Standalone scope/page-size controls have a light border and 6px corners. Preserve Sales contracts as its existing action rather than inventing selector behavior from the mockup.
• Toolbar actions, including custom actions, use an icon plus visible text (Create, Filters, Columns, Refresh and Sales contracts); retain existing commands and do not add a Rules action without behavior. Active Filters uses primary fill. Date and pagination utilities remain compact icon buttons; Create uses the popup primary colors. Compact collections use 8px 12px toolbar/footer padding, 6px button gaps with no individual margins, 30px controls and 2px 6px table-cell padding. Use a 24px row-content minimum so checkbox wrappers do not inflate compact rows. Keep keyboard focus and horizontal table scrolling.

CollectionPagination requires numeric total and owns range formatting: 1-10 of 2248, or 0-0 of 0 when empty. It has no page-specific summary slot. Do not add a second N records, N of M records or Page 1 / 1 label. Existing page-size/filter/sort preferences remain state; they do not authorize different visual controls or invented data totals.

DataTable column resizing stays opt-in through its existing pointer callback. Do not show a resize cursor or native resize handle on a screen that has no resize callback. Selection checkboxes inherit the active tenant primary with accent-color.

Rules opens from the footer gear. Its header provides Reset and an accessible Add rule (+) action; row edits remain draft state until Save, while Cancel or close discards the draft. This Cancel is an editing rollback action, not the close-only popup Cancel prohibited by Section 12.1. Saved rules retain enabled state, field/condition/value, priority, description, row color and font color through the collection's existing local persistence.

Authenticated local verification on 2026-09-09 covered indigo Outbound Sales/Inbound Purchases and cobalt Booking/Transload at desktop width, plus the full-screen 390px Rules editor. The rendered list measured 29px headers and 30px rows while using the 28px/24px compact tokens; this is recorded evidence, not a claim of pixel identity. IBM Plex Sans loaded from the local woff2 asset and was applied to the visible table. Row selection, focusability, footer/menu placement, Escape focus return, rule save/reopen/ cleanup and both tenant primary colors were exercised. Production rendering and Transload provider/ file workflows remain separate evidence.

Native semantic tables that cannot use DataTable, including editable report rows, invoice previews and planning matrices, carry ctc-table-core. The shared compact grammar applies to standard native tables; the ctc-table-core--matrix exception keeps schedule/planner grid geometry while inheriting shared font and semantic colors. Raw <table> markup is limited to exported documents, not Product screens.

12.3 Binding reuse and selection actions

User correction — 2026-09-11: Ordinary Dialog sizes are default (760px), wide (960px), and workspace (1180px). The workspace width is shared with the existing WorkspaceDialog preset; Company uses it without a private width or fixed height. All widths remain capped at 96vw; the existing small-screen full-height behavior remains. Choose a shared preset before adding page-local geometry.

Brokerage exception — 2026-09-12 direct Product-owner request: The Brokerage editor uses the shared workspace dialog at near-full viewport width and height so Purchase and Sales can remain visible together. Its order and item section surfaces stay white.

All editable/record form tables use the Create Inbound Purchase → Line item appearance through the shared form-table recipe: white surface, subtle outer border and horizontal separators, compact muted uppercase headers, 2px × 6px cells, inputs filling cells without duplicate input borders, and existing add/remove row commands rendered as green Plus/red Minus 26px icon buttons. By default Add is in the final header cell and removal in the corresponding row cell; preserve the Section 11 business-action placement when it differs, including Client 2 current composition. Preserve field order, validation, command permissions and any minimum-row restriction. Do not add delete commands to read-only tables. Form tables fit their available width; narrow screens may scroll when actual columns cannot fit, but content must never be hidden to conceal overflow. This does not replace paginated list layout or embedded document-preview/print templates.

Every standalone master list must mount the existing ProductSurface kind="collection" so its table scrolls inside the page and the shared pagination stays visible. Embedded Company Rate content uses scroll="none" inside the parent dialog; it does not create a second full-height page. BillingPreset uses the same selection actions, FormSection and field components. Current verification and unresolved runtime defects are recorded in the owning Task; implementation alone does not imply every popup has passed visual review.

A screen is not compliant merely because it imports Dialog or DataTable. Its rendered composition must use the shared recipe without local font, spacing, surface, section, toolbar, footer or button overrides. A different route/module/tenant, existing CSS, a previous AI-generated screen or a mockup is not approval for a variant. Only an explicit user request can authorize a screen-specific visual exception. Record the exact screen, element/state and requested difference here before applying it. Section 11 explicitly authorizes the CTC business-placement and Client 2 preservation boundaries; these are not permission for page-local fonts, margins or button sizes.

Surface	Common owner and fixed rule	Caller-owned content
List canvas	ProductSurface collection; full-width, zero extra inset, contained horizontal scroll	Existing columns, data, filters and page state
List header	CollectionToolbar; default arrangement above; 8px 12px padding, 6px gaps, 30px controls	Existing actions, required business order/grouping/placement and date availability under Section 11
Table	DataTable; 11px/600 uppercase headers including sort buttons, 13px rows, 2px 6px cells, shared selection and focus	Column names/order/grouping, alignment/type, values and permitted resize/sort callbacks
List footer	CollectionPagination; gear at left, page size and range/navigation at right, 8px 12px padding	Numeric total, page, page size and existing callbacks
Ordinary popup	Dialog default 760px, wide 960px, workspace 1180px; 96vw limit, content-driven height, shared viewport maximum	Title, form content and existing commands; no arbitrary fixed empty height
Popup frame	Header 20px 24px, body 24px, footer 16px 24px, white body; footer outside body scroll	Existing action availability and dirty-close protection
Popup section	FormSection; unboxed heading and primary underline, 18px row/28px column gaps, 48px effective vertical separation (16px stack gap + 32px margin); side-by-side sections remain aligned	Existing heading, field order and 1–5 column geometry required by content
Fields	Shared form owners; 12px labels, 14px values, underlined inputs; autocomplete/multiselect use Tom Select	Existing type, value, UUID choices and requiredness
Popup tabs	Shared workspace tab recipe; selected primary fill/on-strong text, separated tabs and visible keyboard focus	Existing labels, active section and section content
Selection actions	SelectionBar + SelectionActionButton; no visible N selected label; Edit (3), Delete (3)	Existing selection, permissions, disabled/busy conditions and confirmation/commands

Edit has the tenant primary fill and pencil icon. Delete has danger fill and trash icon. There is one Edit button: one selected record opens the existing single editor; multiple records open the existing batch editor when supported. Do not duplicate Edit and Multi Edit for the same command. Distinct Legacy commands with different selection scope, validation or effects must remain distinct under Section 11; do not merge them for cosmetic consistency. Preserve Client 2 current action composition. The count belongs inside the action label; an accessible selection announcement may remain. Preserve existing single-only delete/deactivate limits; visual unification does not grant bulk deletion. Clear remains at the right and clears selection. Row-embedded edit commands retain their row scope.

Implementation and verification: search the shared owner and every caller first; repair the owner and remove obsolete overrides, then migrate all affected consumers. List and popup are two independent checks. Compare Inbound and Outbound first, then Company, generic Catalog (including Fuel), Booking, Transload and the other changed families at the same viewport. Check populated/empty lists, sortable headers, selected 1/multiple/clear, popup sections/tabs/scroll/footer and narrow layouts. Preserve working fields/actions and test single/batch dispatch without saving business data when the request only concerns appearance. A source test, CSS rule or screenshot does not imply all-screen browser acceptance. Record the actual checked route/state and remaining gaps in the owning Task; do not mark unvisited screens visually verified. User visual approval remains separate from implementation checks.

12.3.1 Wiki Document Reading Layout

2026-09-13 user correction: with several work areas and individual specifications in mind, the Wiki structure and design are decided first. Menu, category and navigation labels are shown in English, and the Korean specification body is kept as it is. The User Manual and the Development Specifications are read in the same Wiki frame, not in a separate reader. The information structure, source ownership, update and migration order are owned by the Wiki structure. Booking is not treated as the home title or as the whole system.

Every Wiki path — Home is the current document in the same frame
┌ Knowledge Base / Wiki ───────────── Search ─────────────┐
├ Wiki tree ─────────┬ Current page ───────────────────────┤
│ Wiki Home          │ Title, summary                      │
│ ├ User Manuals     │ ┌ On This Page ──────────────────┐ │
│ │ └ Category       │ │ heading tree of the current body │ │
│ │   └ Document     │ └─────────────────────────────────┘ │
│ └ Development      │ Home: collection tree              │
│   Specifications   │ Document: Korean body, tables, diagrams, related links │
│   ├ System Specs   │                                     │
│   │ ├ SRS          │                                     │
│   │ ├ SAD ... RTM  │                                     │
│   └ Business Specs │                                     │
│     └ Booking ...  │                                     │
└────────────────────┴─────────────────────────────────────┘

The existing Wiki shell, shared tokens, buttons and search, and the local font are reused. Wiki Home and an individual document always use the same left tree and central current-page frame. On This Page is not a right sidebar but a collapsible table-of-contents tree shown directly below the page title and summary. The left side does not list documents in a single level but expands as collection → category/type → document. The Home body uses the same hierarchy, and each document's related links form an expandable knowledge structure that leads to the next document inside the same frame. The reading body is not compressed as densely as a work screen; the reading body is at most about 80 characters wide with generous line spacing. On a white background with neutral boundaries, only the selected item is highlighted, using the existing tenant primary. No large hero, duplicate card or separate Home dashboard is created. The top table of contents shows a numbered sub-section as a nested list under its parent section, joined by a connector line. For example, 4.1 through 4.n sit under 4, and a parent disclosure collapses and expands the sub-tree. Sub-items are shown with a vertical line and branch lines, while an item with no number and no parent is placed at the root. Existing section anchors are kept. The disclosure of a root that has children sits in the left margin of the title so that the start of sibling root titles such as 3, 4 and 5 lines up. A wide screen is made of document navigation on the left and the body in the centre. The central column and the table wrapper have a min-width: 0 boundary, and a wide table scrolls horizontally only inside the central body. Diagram zoom and print apply to the current document only.

On a narrow screen the left navigation and the body stack in one column, and the top table of contents collapses in the same place. It opens and closes with the keyboard, closes on Escape and restores focus. Changing document moves focus and the reading position to the title, and returning to the list restores the filter and position. The table of contents uses body anchors. Loading, no search results, no such document, and read failure or retry are distinguished. Mermaid renders only the diagrams of the current document and provides a readable description plus a render-failure notice. It does not render other documents hidden outside the body, and does not put a whole bundle of documents into the initial response.

A long left Wiki tree scrolls on its own within the viewport height on desktop, and within at most 42vh/360px at 900px and below. Therefore, however many tree items there are, there is no need to scroll to the end of the whole tree first just to read the current page title and body. The document title of the Development Specifications is shown in English in the menu and the page heading, while the sections and the body stay in Korean.

The existing generated HTML keeps the authenticated /wiki/specifications/<id> source, while user navigation is handled by the same Wiki frame at /wiki/<id>, which loads and shows only the current document's article and footer. It does not create a second React shell or a copy of the document body. It provides a return to the Wiki home, cross-document navigation and a table of contents, and related specification links inside a document are changed to the same frame path. The text index for search is included in the list only, while a document page includes just its own body.

This wireframe is a screen composition design and is not treated as an actual screenshot or as user visual approval. Implementation acceptance is split into individual document navigation, search, direct links, back and refresh, and desktop/mobile, keyboard and diagram checks.

13. C1 And C2 Composition

C1 and C2 share commands, queries, records and adapters.

Differences come from:

• capability policy;
• profile-native labels/sections;
• persisted facts;
• approved conditional rules.

Numeric CLIENT_ID branches and separate backend implementations are prohibited.

14. Performance Design

• initial Booking List loads only list dependencies;
• workspace/editor code is route/interaction lazy;
• Files/Photos/Packing/AI load by feature use, not globally;
• query count and indexes are explicit;
• critical p50/p95 and bundle costs are measured;
• caching/background work is introduced only for a measured need;
• no generic Worker or event infrastructure without a real consumer.

15. Reliability And Observability

Every request/effect has correlation, classified errors and safe structured logging.

• health and readiness are distinct;
• Booking DB commit survives provider failure;
• object/relation/document/provider partial effects are recoverable;
• retries are bounded and idempotent;
• audit evidence is separate from operational telemetry;
• no secret, password, token or protected file content is logged.

16. Phase-2 Reuse

MK reuses:

• identity/access/profile composition;
• list/workspace patterns;
• master-data selectors;
• attachment and photo transport/patterns;
• document source/render/output separation;
• AI review/apply pattern where applicable;
• UUID/MySQL compatibility;
• conflict/readback/recovery conventions.

It does not copy Booking internals or create MK-specific framework variants.

17. Release Boundary

Development, target-role acceptance, page exposure, default route, writer ownership, observation, caller-zero and retirement are separate decisions with explicit readback and rollback.

18. Reusable Management Structures

Admin and other management surfaces use one CTC visual language and three complementary structures. They are interaction structures, not separate themes.

Workspace Hub

Use for collection-level work:

• search, filters, sorting, saved views and column preferences;
• dense resource table or hierarchy;
• pagination, sticky header and preserved list state;
• row selection and selection-aware actions;
• explicit loading, empty, error, denied, stale and unavailable states;
• a stable relationship between the selected row and its Inspector.

Operational records remain tables when scanning and comparison are primary. Cards do not replace proven columns or reduce useful density.

Inspector View

Use for one selected resource:

• persistent record identity and current context;
• assigned, effective or applied state only when an authoritative source exists;
• related facts, validity, source/version, diagnostics and audit when available;
• primary and high-risk actions with explicit context;
• deterministic close/back behavior and list-state restoration.

Desktop uses a contextual side panel. Mobile uses a full-screen detail surface and restores Hub filter, sort, selection and scroll state on return.

Configuration Builder

Use only for multi-part, high-impact or dependency-sensitive changes:

• section or step navigation;
• current, proposed and applied values kept distinct;
• validation and impact preview;
• review, apply and authoritative readback;
• dirty-close, conflict and recovery states;
• predictable Back, Next and Apply actions.

Simple record forms must not be inflated into unnecessary wizards, and complex settings must not be compressed into small modal dialogs.

AppShell and Admin placement

The structures live inside the existing AppShell. They do not add a second Product shell or duplicate global navigation.

Surface	Primary structure	Supporting structure
Users	Workspace Hub	Inspector plus compact create/edit form
Roles	Workspace Hub	Effective-access Inspector plus Configuration Builder
Tenants	Workspace Hub	Applied-state Inspector plus Configuration Builder
Menus	Configuration Builder	Page Catalog, Menu Tree and selected Menu Inspector
System Settings	Settings Hub	sectioned forms, Builders or read-only Inspectors by effect

Users retain the current high-value scan and action contract: Username, Name, Email, Role, Status and Last Login remain visible; create/edit retains Username, Password, Confirm Password, Name, Email, Company and Roles. Change Status may operate on one or more users only when the selected users share the same current status. Reset Password and Login as User require exactly one selected user, and impersonation is available only in System mode. The UI must not invent effective-access, audit or applied-state facts that the current query does not provide.

Tenant, environment, access mode, applied-state validity and impersonation context remain visible in the existing shell/context area. A design artifact, screenshot or generated prototype is advisory until it preserves current contracts, uses one shared component system, and receives explicit Product- owner selection. Stable direction belongs here; exact rollout, fields and action cardinality belong in the executable Task.

---

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