Library Layers

Problem

The graph has no import cycles. It has no layering either. Domain libraries import each other sideways, for example media → requests → chats → user → phone → comms.

This is a cost in build time, test scope and review risk. It is not a memory cost once servers are merged. See Server Footprint Plan.

Layers

A library may import from any lower layer. Within its own layer it may import only libraries of its own domain.

An import that the compiler erases is always allowed. import type and type-only uses do not create a runtime dependency.

Violations

146 of 1,529 runtime dependencies break the rules. That is 10%.

The largest groups: website → gbp (8), website → content (5), website → scheduling (5), scheduling → website (5), scheduling → clients (5), command-center → frontdesk (5), identity → comms (4).

Fixes

Each violating edge was classified by what crosses it. An edge can need more than one fix.

A contracts library alone clears 3 edges. Almost every edge that imports a constant also injects a service. Ports are the main work.

Contracts

Move the symbols to <domain>-contracts. The owning library re-exports them, so its other importers do not change.

Done: scheduling → booking-agent. The recommendation engine is three pure files. They moved to libs/booking-agent-contracts. 17 new unit tests cover them.

Port

A port is an interface and an injection token in a contracts library. The owning library binds the token to its service in a global <Domain>PortsModule. The application root imports that module. The consumer injects the token and stops importing the owner.

Done: gateway → scheduling. The chat gateway read one boolean from SchedulingService.

libs/scheduling-contracts/src/lib/ports/scheduling-status.port.tstsexport const SCHEDULING_STATUS_PORT = Symbol('SchedulingStatusPort');

export interface SchedulingStatusPort {
  isSchedulingActive(entityId: string): Promise<boolean>;
}

libs/scheduling/src/lib/scheduling-ports.module.tsts@Global()
@Module({
  imports: [SchedulingModule],
  providers: [{ provide: SCHEDULING_STATUS_PORT, useExisting: SchedulingService }],
  exports: [SCHEDULING_STATUS_PORT],
})
export class SchedulingPortsModule {}

libs/gateway/src/lib/chat.gateway.tsts@Inject(SCHEDULING_STATUS_PORT) private readonly schedulingStatus: SchedulingStatusPort,

A server that mounts a consumer without the ports module fails at boot with a dependency error. That is intended.

Queue

The producer depends on @mononest/bull and a job contract: a queue name and a payload type in the owner's contracts library. The processor lives in the owning library. Not done yet. The six edges that need only a queue are employees → chats, fireflies → cx, fireflies → pipedrive, frontdesk-agent → integrated-platforms, website → gbp-media and website → reviews.

Verification of the two fixes

api-server was rebuilt and booted. All 372 parameterless GET routes return the same status and response shape as before the change. The new specs pass. gateway and the changed scheduling files type-check clean.

Expected effect

The gain arrives late. Most of it needs the ports.

Libraries carried by the servers that import few directly:

Work list

The order of work, owners and exits are in Codebase Organization Plan. This section is the procedure for each kind of fix and every edge by name. Waves 1 to 3 are Phase 3 of the plan. Waves 4 and 5 are Phase 4.

Wave 1 — Contracts only

Three edges import only constants, enums or pure functions. For each, create <owner>-contracts, move the symbols, and re-export them from the owning library so its other importers do not change. The pattern is in Contracts.

A symbol qualifies only if the file that declares it imports nothing above the contracts layer. Check that before moving it. Pure functions get unit tests in the new library.

Exit: baseline at 143.

Wave 2 — Queue only

Six edges call another library only for a side effect. For each:

Each conversion changes delivery from inline to eventual. Confirm with the domain owner that the caller does not rely on the effect having happened. website → gbp-media and website → reviews write to Google and should be checked first.

Exit: baseline at 137.

Wave 3 — One-method ports

42 edges inject one service and read one method. Each is the change shown in Port:

Several of these methods write, for example LocationService.createOrUpdateEntityLink and FollowupLifecycleService.createManualFollowup. A port can carry a write. Where the caller does not need the result, prefer a queue.

Several owners appear more than once. Group the work by owner: services and links serve four of these edges each, and win and gbp-location three each, with one ports module per owner.

Exit: baseline at 95.

Wave 4 — Multi-method ports

83 edges across 40 owning libraries read several methods, or mix reads with side effects and constants. Work one owning library at a time:

Order by number of violating importers: media and gbp-location (10 each), then win, entity and auth-entity (7 each), then website, services, links and booking-enquiries (6 each).

Exit: baseline at 12.

Wave 5 — Manual

Twelve edges the analysis could not classify. Three patterns:

• A service is injected but never called through a typed property. Read the file.
• A symbol crosses that is neither portable nor injected, such as a decorator (Public, Auth) or a helper object (DestinationObj). mcp → auth and mcp → agents are foundation importing upward. Either the symbols move down or mcp moves up a layer.
• An integration library holds domain logic. frontdesk-agent-tools → win reads 17 methods. That is a split, not a port.

Exit: baseline at 0.

Full work list

Port surface

The services other layers call are each library's real public interface. These libraries need the most port methods.

win and gbp-location are read through more than 20 methods each. A library read that widely is doing several jobs. They are the first candidates to split.

Ratchet

tools/lib-layers/baseline.json records the 146 violations with the symbols each one imports. The check fails on a new violating edge, on a new symbol added to a recorded edge, and on a fixed edge left in the baseline. The file can only get shorter.

$ pnpm check:layers $ pnpm layers:report $ pnpm layers:plan $ node tools/lib-layers/check.js --update

.github/workflows/lib-layers.yml runs the check on pull requests that touch libs/. It reports the status libs/layers. It blocks merges only after it is added to branch protection.

Method and limits