Logistics Workspace Filesystem And Package Standard

• Status: CANONICAL / BINDING
• Product reality: ../PRODUCT_REALITY.md
• Module ownership: MODULE_REGISTRY.md
• Documentation classes: ../README.md
• Architecture method: ARCHITECTURE_CHANGE_METHOD.md

This document owns the shared generation decision for a document and code, and the allowed placement and removal criteria of code. The docs/README owns the document classification, the MODULE_REGISTRY owns the work responsibility, and the ARCHITECTURE_CHANGE_METHOD owns the structure change approval. Each list is not copied into another registry with the same content, and is changed only in its own canonical source.

1. Concepts

Concept	Meaning	Authority test
Product capability	observable user/operational result	PRODUCT_REALITY.md
Product package / add-on	customer contract unit and declared business scope	PRODUCT.md, never a source/deployment boundary
Feature	reusable business functionality subject to eligibility and activation	approved feature contract and actual consumers
Entitlement	tenant eligibility from valid assignments or explicit transition grants	authoritative server-resolved assignment state
Permission	authenticated principal's allowed action	identity/access and action contract, not a package purchase
Domain module (historically Product module)	one business vocabulary, state and command/query owner	MODULE_REGISTRY.md
Workspace package	TypeScript import/dependency boundary	package manifest, public API, consumer, tests and ADR
App	independently executable runtime boundary	admitted runtime with real consumers
Profile	tenant-selected presentation/policy defaults	persisted context and typed policy
Cohort	tenant/role/data used to prove a capability	never creates source ownership
Folder	source organization only	never creates ownership by itself

A page, menu, route, adapter, registry or folder is not a capability.

The commercial catalog lives only in PRODUCT.md. Commercial package, domain module and workspace package are separate axes. Offering keys such as pkg.work-operations and addon.field-execution do not authorize new source directories, packages, services or tenant-specific implementations. Existing domain packages remain; SQL stays in the existing db-mysql adapter. Keep small packages flat rather than adding empty contracts/internal scaffolding solely for symmetry.

Workspace Base describes mandatory product support delivered by several existing platform and business-support owners; it is not identical to @ctc/platform-core. Shared weighing, master data and document logic retain their domain responsibilities. A tenant's entitlement changes runtime composition, not import ownership or the historical meaning of its business records.

Reuse existing Admin pages, shared UI, platform-administration contracts and policy resolution for package/tenant management. Do not put product assignment persistence in a React component or treat its checkbox state as server-authorized eligibility. The target is recorded in NS3-122 for basic management; NS5-008 only extends advanced release/onboarding operations. No runtime implementation or new public boundary is admitted by a filesystem glossary change.

2. Top-Level Map

The allowed location and the role must be satisfied together. The existence of a folder below does not mean that every kind of file under it is allowed. When there is no real owner or consumer, or another canonical source is duplicated, it is not created even when the path matches.

The allowed boundary	The responsibility	The creation restriction
apps/web/, apps/ui-catalog/	the existing Web runtime composition and the UI review app	a separate app, worker, daemon or service is not created before a structure change approval
packages/modules/<owner>/	the work responsibility of the MODULE_REGISTRY §2	only a registered work owner is used. A new module per menu, tenant or commercial package is forbidden
packages/integrations/ai/, packages/integrations/files/	the existing AI and file provider adapter	a new provider or device adapter, or a duplicated transport, needs a separate boundary approval
the rest of packages/ listed in §3	a registered platform, DB, UI and support responsibility	other packages/* is not interpreted as an allowed area for a new package
config/	the environment, profile and policy input that matches the existing schema	it is not a work state, a per-tenant implementation, or a new configuration system
catalog/	the machine ID, relationship and source of the existing schema	it is not a code implementation, a copy of a progress state, or a new registry
docs/	the allowed document classification of docs/README	a plan, context or review system that is not classified is not created
scripts/tests/	the existing check layer of §11	it is not product code, a running service, or a new work management system
scripts/{architecture,catalog,context,docs,migration,quality,release,structure,visual}/	the existing tool per purpose	only a repeated task of an approved real consumer. A one-off cleanup or verification is not made a permanent tool
.generated/ or an OS temporary location	the result of an existing generator, a local cache, and a one-off task	it is not a manual canonical source, operating code, or a target of an automatic new commit

The existing scripts/local-web.mjs and the runtime configuration files are the existing entry points that have a current consumer. It is not a general permission to add a new top-level script or config file. scripts/context/ is also limited to the existing features that have a current consumer, and a retired manifest, preflight or Context Gate cannot be created again. A path that currently exists but is not in this map is a remainder to be checked, and it is not approved by its existence nor deleted immediately. For example, scripts/_tmp/ or a past copy of tests/ is not used as the default location for new material.

The default generated artifact location is .generated/** or the OS temporary directory. An already approved runtime generated source keeps the exact output location that the current generator and the runtime consumer define. For example, the User Wiki's development-specifications.generated.ts and development-specifications-index.generated.ts are the output of the existing specification generator, and are not a precedent for a new manual canonical source or for making another generated package. The generated artifact, the original, the generator and the runtime consumer are not confused, and the original or a required output file is not deleted.

2.1 Product Root And Extraction Boundary

The product root is the new-system/ of the current checkout, and it stays ./ after it is separated into its own repository. The folder name new-system is not a permanent premise of the product structure, the document links and the runtime. The tree below and a newly created or modified product document source path are written on the product root basis. A Markdown link is a relative link based on the document location.

Item	The current state	After the repository separation
the Booking HTTP URL	/api/bookings	the same; the old /api/new-system/bookings is compatible through a single internal rewrite
the Booking route file	the new-system/apps/web/app/api/bookings/route.ts of the current checkout	apps/web/app/api/bookings/route.ts
the product document	the new-system/docs/ of the current checkout	docs/
the product internal source notation	on the apps/, packages/, catalog/ and docs/ basis	the same

The /api of a URL is an HTTP namespace, not an instruction for an api/ directory at the repository root. The current Booking handler is already inside the product and delegates to src/transport/semanticBookingRoutes.ts. A new Product API is also placed in the route and transport of the owning app. In the Legacy api/ of the parent checkout, a New-System only implementation or relay file is not added. An existing caller is not broken because of a URL name.

A web screen uses the single location apps/web/src/composition/pages/<area>/. A separate surfaces/product classification is not created again. An API implementation is placed in apps/web/app/api/<resource>/, and the transitional name new-system is not put in an intermediate folder or a new call address. The compatibility of an existing call is handled by one same-origin rewrite in apps/web/next.config.ts, and a duplicated handler is not made. This rewrite can be removed after confirming that the old address is no longer used. The work, DB and authority ownership stays the same.

The product code, document, and a new script, config or context are owned inside the product root. They do not newly depend on the runtime code import, the file path or the absolute workspace path of the parent or sibling checkout. Legacy and reference are only a comparison and specification basis and are not a runtime owner. For external material the source name, the relative material path, the revision and the material time, and the location where it was obtained are recorded, and ../reference is not assumed as if it were a link inside the product. it is only a comparison and specification basis and is not a runtime owner. For external material the source name, the relative material path, the revision and the material time, and the location where it was obtained are recorded, and ../reference is not assumed as if it were a link inside the product. Even at the separation, a necessary basis explanation and an approved contract are left in the documents of this product.

It does not mean it is currently a fully independent repository. An execution path of the existing parent .agents and tools/context that still has a current reader is a dependency of a coexisting environment. A retired Task manifest is not restored as a current execution contract. A historical evidence path is also not replaced in bulk. The real extraction step moves the current consumer together, and in a separate checkout without the parent files it must confirm the install, the types, the build, the current work tools, the document links and generation, and a real API call before it is complete. The current design stage does not execute it or claim a full dependency removal.

In the whole repository the root PHP, api/, app/ and frontend/ are the Legacy owners, and the root docs/ is its operation and reconstruction basis. transition/ is responsible for the cutover and rollback, database/ for the shared migration, and contracts/ for the approved cross-runtime contract. This boundary and each scoped AGENTS are preserved. An existing file of a Legacy or an auxiliary runtime is modified under its current contract, and a new product implementation or a new document system is not placed around the root, Legacy or reference.

2.2 Creation Contract

The order is modify an existing file → a necessary separation inside the existing owner → an approved structure change. The conditions for allowing a new path are that all of the following five are satisfied.

1. It is directly needed for the current user request or an approved Task result.
2. It fits the allowed path and the document classification and code role, and there is one semantic owner.
3. There is a real reader, caller, test, or a consumer of approved original evidence. It is not created for a future possibility alone.
4. There is a cohesive responsibility that cannot be solved by modifying or reusing an existing file, and it leaves no duplicated body, writer or framework.
5. It keeps the existing naming, dependency, public contract, verification and recovery criteria, and it is within that structure budget.

Change	The default handling
a modification of the existing behaviour and body	it is done in the existing owning file
a separation of a cohesive internal file, an owner-local test and a specification detail inside the existing owner	is done in the current approved scope when the conditions above and the budget of §10 are satisfied. An ADR, manifest or approval document is not made for every file
a new top-level folder, document classification, independent owner, app or package, public export, or provider boundary	the exact boundary is first decided by the user or an existing approval procedure, the relevant canonical source is updated, and then it is implemented. A technically significant change follows the existing ADR procedure
a one-off investigation, conversion or inspection	the current tool, conversation, existing Task and temporary directory are used. It is not left as a permanent script, automation or check framework
the classification, owner or consumer cannot be explained	only that new creation is held. A requested task that is possible in the existing owner continues

The basis of the decision records the exact path, the role, the existing owner and consumer in the existing WRITE_BOUNDARY, the work plan or a DIRECT handover, as needed: the reason reuse is not possible and the target to replace. A separate file approval registry or a per-path sidecar is not created. A user request that already approved an exact structure change does not require the same approval again. Conversely, "cleanup", "refactoring" and "continue" are not expanded into an arbitrary new structure approval, and a file is not created first and then added to the standard, the index and the test to approve it by itself.

3. Canonical Current Tree

./                               Product root (current checkout: new-system/)
├── apps/
│   ├── web/
│   │   ├── app/                    Next routes/layouts and application-wide globals only
│   │   ├── src/
│   │   │   ├── bootstrap/
│   │   │   ├── transport/
│   │   │   ├── adapters/
│   │   │   ├── composition/pages/
│   │   │   └── telemetry/
│   │   └── tests/
│   └── ui-catalog/
├── packages/
│   ├── platform-core/
│   ├── runtime-config/
│   ├── identity-access/
│   ├── platform-administration/
│   ├── policy/
│   ├── modules/                    only the owner of the MODULE_REGISTRY §2
│   ├── db-mysql/
│   ├── integrations/{ai,files}/
│   ├── design-tokens/
│   ├── ui/
│   ├── observability/
│   ├── user-wiki/
│   └── test-support/
├── config/
├── catalog/
├── docs/
├── scripts/                        the existing tool area of §2 and the tests of §11
└── .generated/

This is an admitted-source map, not permission to create empty scaffolding. A work module name and responsibility are defined only in the MODULE_REGISTRY. It is not a matter of registering every individual file in this tree, but an implementation inside an allowed role is judged by §2.2. A boundary that is not in the tree is not added for convenience.

4. Architecture Change Admission

A new or changed app, package, public export, module boundary, cross-module transaction, or architecture fitness function follows the Architecture Change Method. It uses the existing procedure of current fact → the problem → three alternatives including a reuse of the existing owner → a needed ADR approval → implementation → independent verification. It does not create a separate approval system or execution ledger in this document.

A production Task cannot change this standard, the module registry, accepted ADRs or architecture/admission validators to approve its own implementation. A governance Task cannot modify Product runtime source. A structure definition task that is directly approved by the user is distinguished from the implementation scope after it. A file separation inside the existing owner and a new boundary exposed to the outside are distinguished by §2.2.

5. Placement

The responsibility of the code	The owning location	What is not put there
a work fact, an invariant, a command and query, and a port	packages/modules/<registered owner>/	HTTP, SQL, React and a provider SDK
SQL, a physical schema mapping, a transaction, a numeric compatibility and a read-back	an existing work adapter in packages/db-mysql/	a new work policy, a screen state, or a separate writer
an AI and file provider transport	packages/integrations/ai/ and packages/integrations/files/	a work approval, a relationship ownership, or an automatic save
a framework entry, a layout and a route	apps/web/app/	a duplicated screen body, SQL, or a work rule
a dependency assembly	apps/web/src/bootstrap/	a work policy or a screen state
an HTTP input, an authority contract application, a dispatch and a response	apps/web/src/transport/	an independent work judgement or SQL
an approved boundary conversion and compatibility	apps/web/src/adapters/	a new tenant-only owner
a real screen, a state and a per-area composition	apps/web/src/composition/pages/<area>/	a separate table or dialog engine, or a direct DB or provider access
a reusable UI and a visual value	packages/ui/ and packages/design-tokens/	a work or tenant conditional
an owner-local test	next to the target code or at the existing app test location	a second runner of the same scenario
a cross-owner test	the existing check layer of scripts/tests/	product runtime code
a document, a machine relationship and a temporary result	the classification of docs/README, the existing catalog/ schema, and .generated/	a new canonical source or a progress ledger

A new provider, workflow, read projection or runtime is not created for a future possibility alone. Making an implementation of the same responsibility under a new name and then leaving the original implementation as a forwarding wrapper is also not a reuse.

6. Package Shape

A small package keeps the current src/public.ts and the real owning files. Empty directories such as domain/application/ports/policies are not created in bulk for every module. A needed internal separation is based on the existing responsibility and caller, and it does not increase the public entry points.

A DB implementation first finds the current per-area owning location in packages/db-mysql/src/. An idealistic modules/<owner>/, repositories/ and services/ tree is not newly created next to the current code. When the physical structure is changed, the existing implementation and consumer must actually be moved and the original responsibility removed. Compatibility code is internal and cannot gain new public consumers.

7. File Responsibility

One file owns one coherent reason to change. Do not mix:

• transport, authorization, use case and SQL;
• domain and provider;
• unrelated pages/panels;
• copied plugin source and business logic;
• Product UI and migration diagnostics;
• multiple module writers under a tenant/customer aggregate.

New app implementation files have a 500-line review ceiling. Existing registered debt may shrink but may not grow. Split by semantic responsibility, not arbitrary fragments or forwarding facades.

7.1 File-Level Work Contract

Apply the following responsibilities to existing files before considering extraction. The selected Task instantiates this map with exact paths and symbols; it is not permission to create the example filenames, empty folders, new packages or a parallel ownership registry.

Existing path or file family	Sole responsibility	Must remain outside
apps/web/app/**/page.tsx, layout.tsx, route.ts	framework entry and delegation	business policy, SQL, duplicated page implementation
apps/web/src/bootstrap/**	construction of concrete runtime dependencies	page state, domain decisions
apps/web/src/transport/**	HTTP parsing, approved authorization contract, command/query dispatch and response mapping	SQL and independent business rules
apps/web/src/adapters/**	server/application boundary conversion and approved compatibility	new tenant-specific domain owners
apps/web/src/composition/workspacePageCatalog.ts	route identity and navigation metadata	record loading, writes, domain policy
apps/web/src/composition/workspacePageRegistry.tsx	route-to-screen composition using existing access contracts	duplicate records, transactions, UI primitive implementation
apps/web/src/composition/collectionPersistence.ts	existing collection persistence mechanics	per-domain columns, validation or business defaults
owner-local *Experience.tsx	composition of one operator screen	unrelated workflows, generic component implementations, transport/SQL internals
owner-local collection hooks and *Table.tsx	query/selection state and domain column projection respectively	another table engine, form draft ownership
owner-local workspace hooks and *Panel.tsx	draft/save/recovery state and field/section composition respectively	client-ID policy, duplicated shared form controls
packages/ui/src/data-display/**	table mechanics, column presentation and keyboard/selection behavior	Booking, inventory or tenant business rules
packages/ui/src/overlays/**	dialog lifecycle, modal nesting, focus, close request and shared drag mechanics	interpreting action labels as business intent
packages/ui/src/operations/**	reusable toolbar, collection and record patterns	page-specific field lists and server access
packages/modules/<owner>/**	the registered business vocabulary, invariant, command/query and port	framework, concrete DB or provider dependencies
packages/db-mysql/src/**	approved mapping, query, transaction and authoritative readback	browser state or new business-policy authority
scripts/structure/{plan,check,ratchet}.mjs	structure planning, invocation and existing debt enforcement respectively	Product behavior or a second Task workflow
scripts/tests/** and owner-local tests	evidence for the declared contract	manufacturing Product requirements or weakening expectations for cleanup

For each changed file record purpose, retained/moved/removed symbols, actual consumers, target owner, contract/source references and the smallest relevant proof. Update an existing package README or contract when its stable boundary changes; keep slice-specific ownership in the Task. Obvious glue and trivial local transforms do not require repetitive file headers or a document per file.

Extraction is complete only after real consumers use the target owner, duplicated source is removed, imports/exports and documentation references agree, and the original owner's responsibilities shrink. An unchanged large component plus forwarding wrappers is not a completed decomposition.

8. Styling Ownership

design-tokens    literal and semantic visual values
ui               reusable component appearance and interaction
app/globals.css  reset, shell and bounded compatibility globals
*.module.css     one owning feature/page composition

Feature CSS under the route tree, unscoped feature globals and app-wide style bags are prohibited.

The exact shared stylesheet responsibilities and cascade migration rules live in UI_FOUNDATION.md. A currently imported mixed stylesheet is migration debt, not unused code. Move selectors to the real feature owner only with its caller and cascade evidence; remove the old declarations in the same bounded replacement.

9. Naming And Tenant Neutrality

• package/directories: kebab-case;
• React components/files: PascalCase;
• app support modules: lowerCamelCase;
• package/tooling support: kebab-case;
• commands: semantic imperative;
• queries: semantic noun/read intent;
• no tenant/customer/cohort name in backend paths, exports, repositories, services or writers;
• no raw numeric tenant branch in Product code;
• no profile inference from menu-name substring;
• no generic directories named common, shared, utils, helpers, misc, managers, features, clients or unscoped repositories.

Customer/cohort-named backend paths, exports and symbols are prohibited current debt, not permanent exceptions. Existing occurrences are removed by the active prerequisite correction before further Phase-3 implementation. Historical route/menu aliases may remain only in an isolated compatibility map; they cannot name an adapter, package boundary, repository, service, writer or policy owner.

10. Complexity Budget

Every structural Task reports before/after:

production files
public exports
packages/apps
dependency edges
tenant-specific backend symbols
architecture exceptions
orphan source
largest owner files

Default new package/public export/Product surface/tenant-specific symbol/exception budget is zero. Cleanup must produce a non-positive net structural delta unless an accepted ADR proves replacement necessity and removal plan. Unrelated responsibilities are not merged only to reduce the file count.

The additions, moves, renames and deletions of the final diff are compared with §2.2, and an unexpected new boundary and a leftover duplicated implementation are removed. The existing checks and a normal Git diff are used. A new validator, hook, CI or registry is not added for this criteria, and it is not reported that a technical automatic block of file creation is implemented by a document rule alone.

11. Tests

Path	Scope
scripts/tests/architecture/	stable import/ownership/repository-shape fitness functions
scripts/tests/contract/	public contracts across owners
scripts/tests/integration/	real adapter/DB boundaries
scripts/tests/e2e/	browser and target-route journeys
scripts/tests/parity/	bounded Legacy/New comparison
scripts/tests/performance/	workload budgets
scripts/tests/profile/	tenant/profile composition
scripts/tests/quality/	source/release/admission gates
scripts/tests/runtime/	reusable runtime scenarios

A Task-specific architecture test may not assert only that a newly introduced artifact exists. It must protect a stable Product/module principle.

12. Removal

A retired system, replaced code and an unnecessary abstraction are actually deleted after the consumers and the unique evidence are transferred. Leaving only a deprecated name, a comment, a new folder and a forwarding is not a completed removal. A normal change history is in Git, and a decision reason and an execution evidence that must be preserved are in the existing evidence owner or an immutable revision. The reintroduction of an already retired system cannot be circumvented by only changing the name, and it follows the same approval procedure as a new boundary.

12.1 Evidence Required Before Removal

Use the existing disposition axis KEEP / FIX / DEFER / RETIRE. Record an operation separately as REUSE / MERGE / MOVE / DELETE; these are operations, not new Task or capability statuses.

• KEEP: an actual consumer or approved compatibility/recovery contract still needs the code.
• FIX: responsibility, duplication or cascade is wrong; name the replacement owner before editing.
• DEFER: caller, generated class, plugin state, route or runtime evidence is incomplete.
• RETIRE: the specific implementation is superseded and removal evidence covers its consumers.

A deletion record names the exact file/symbol/selector and base revision; searches static and dynamic imports, package exports, framework entry conventions, route/menu registries, runtime-generated classes, event registration, document/print output and both Web/UI Catalog consumers where relevant; and identifies replacement and regression evidence. Search zero, line count, an empty dependency report, or a legacy/old/helper filename alone is not proof of non-use.

For CSS, distinguish unused selectors from declarations superseded under the same cascade conditions. Record import order, selector/property, specificity, layer/media/supports conditions, state and theme. Preserve fallbacks, custom properties, keyframes and third-party generated classes until checked. Never remove a visible field, action, route or recovery path merely to obtain caller-zero.

A completed removal goes as far as confirming the replacement owner, preserving the unique content and evidence, switching the real consumer, deleting the existing implementation and the duplicate instruction, and checking the reference consistency. When a compatibility file is left, the real consumer, the exact location and the removal condition are written in the existing Task and owning document, and a new dependency is forbidden. Material that only passed its date or a Legacy that is still operating is not treated as a completed removal. A document move, an unchanged code, or the existence of a column alone does not complete a data transition, and the approved NULL, zero and stale check, the operating DB migration and the read-back requirements stay the same. A work in progress file owned by another author, and a shared contract and HISTORY, are not modified until they are transferred without a conflict with that author.

Record before/after complexity using Section 10 and the existing structure/debt tooling. Do not copy historical baseline metrics as current measurements or raise a debt budget to make cleanup pass.

---

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