Skip to content

Dependency And Public API Standard

1. Dependency Principle

Source dependencies point inward toward stable semantic contracts.

transport/UI/provider/DB
-> application
-> domain/platform primitives

Frameworks and infrastructure are plugins, not application authority.

2. Package Classes

Pure core

platform-core and domain/application core:

  • no React/Next;
  • no MySQL/provider SDK;
  • no concrete crypto/password/UUID library;
  • no process.env;
  • no filesystem/network;
  • deterministic except explicit Clock/ID ports;
  • may own branded UUID value types and generator ports.

Application modules

identity-access, platform-administration, business modules:

  • typed UUID commands/queries/policies/ports;
  • no infrastructure implementation;
  • no transport types;
  • no numeric Legacy identity;
  • may depend on platform-core/policy/declared module public contracts.

Projection/orchestration

read-models, workflows, documents:

  • consume public UUID facts/query/command contracts;
  • no child internals/repositories;
  • no hidden mutation.

Adapters

db-mysql, integrations and bootstrap adapters:

  • implement ports;
  • translate concrete errors/data;
  • own temporary UUID-binary and numeric-alias mapping;
  • never become cross-module business authority.

UI

ui owns shared React-native components and does not own business state. Copied KJ runtime packages and adapters are prohibited in New-System. Canonical UI selection/cache/entity keys are UUID.

3. Public Export

Every package exposes explicit exports and src/public.ts.

Allowed subpaths are deliberate, such as:

@ctc/identity-access
@ctc/identity-access/server-contracts

Do not expose internal folders through wildcard exports.

4. Public Contract Required Fields

contract ID/version
owner/consumers
purpose
UUID input/result/error
tenant UUID/actor UUID/access
state/transaction/effect
idempotency/concurrency
timeout/retry/recovery
authoritative UUID readback
compatibility/deprecation
related Process/page/data/source

TSDoc and catalog entry are required for public commands/queries/ports/provider effects.

5. UUID Public Identity

Canonical fields use explicit names:

uuid
tenantUuid
userUuid
bookingUuid
companyUuid

Rules:

  • entity and tenant UUIDs are lowercase canonical strings;
  • numeric IDs never cross the DB compatibility boundary;
  • a route parameter or payload may not expose both UUID and numeric aliases;
  • the client may not supply a numeric alias that the server compares with UUID;
  • Logistics Workspace-only records use UUID persistence from their first migration;
  • public cursors use opaque/UUID-based state, not auto-increment IDs.

An explicit Legacy transport adapter may receive a numeric value only to resolve it immediately to UUID before invoking application code.

6. Forbidden Public Shapes

  • RowDataPacket, ResultSetHeader, Pool, provider SDK types;
  • raw database column bag;
  • broad Record<string, unknown> business input/result;
  • any;
  • wildcard event/payload bags;
  • raw CLIENT_ID or numeric entity identity;
  • simultaneous uuid plus numeric id;
  • unbounded collection;
  • generic execute(type, action, payload) mutation API.

Transport parsing may temporarily use unknown; it must produce a typed application input before use-case invocation.

7. Cross-Module Rules

  • import only another module’s public API;
  • request UUID facts/commands, never another module’s repository;
  • one module cannot update another module’s tables;
  • a composite workflow invokes child commands;
  • cross-module read projection belongs to read-models;
  • no circular semantic dependency.

8. Server/Browser Boundary

Package exports mark server-only paths. Browser/client source cannot import:

  • DB/config/secret/session repository;
  • numeric Legacy alias types;
  • Node crypto/filesystem;
  • provider adapters;
  • server composition roots.

Use automated conditional/export/import checks.

9. SQL, Identity And Environment Fitness Functions

Architecture tooling must detect:

  • SQL keywords/template literals outside admitted DB/migration paths;
  • mysql2 imports outside DB/bootstrap;
  • UUID binary conversion outside DB adapters;
  • numeric entity/tenant IDs in canonical public contracts;
  • LegacyNumericId outside @ctc/db-mysql/approved bridge code;
  • process.env outside runtime-config/bootstrap;
  • bcrypt/crypto implementation outside admitted adapters;
  • Next/React in core/application;
  • direct root Legacy asset/global references in canonical routes;
  • public Record/DB-row leakage.

Exceptions require an expiring waiver. Tenant leakage, UUID/numeric mismatch and numeric public identity cannot receive a permanent waiver.

10. Composition Root

Only bootstrap imports both contracts and concrete implementations.

Application handlers receive explicit dependencies and remain constructible in tests.

Typical identity wiring:

createUuidV7Generator
createUuidCodec
createLegacyIdentityBridge
createTenantContextResolver
createRepository
createCommandHandler

No global service locator, reflection DI or magic auto-registration without an accepted measured need.

11. Versioning

Public contract change classification:

PATCH
= behavior-compatible correction

MINOR
= additive optional field/capability

MAJOR
= breaking input/result/error/semantic/identity change

Numeric-to-UUID conversion is a major contract change. During coexistence it uses parallel Legacy adapters and UUID-native routes/contracts until callers migrate. Page route, writer cutover and physical numeric-key retirement remain separate.

---

Source: new-system/docs/architecture/DEPENDENCY_AND_PUBLIC_API_STANDARD.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.