Module Boundaries

How Max’s packages relate to each other, what each one owns, and where new code should go.

Package Overview

@max/core              Types and foundations. No I/O, no services.
    ^
@max/connector         Connector SDK. What connector authors import.
@max/execution         Sync orchestration interfaces.
    ^
@max/federation        Business logic. Orchestration, registries, protocols.
    ^
@max/platform-bun      Bun-specific implementations. FS, SQLite, daemon.
    ^
@max/cli               Presentation + daemon hosting. Owns all terminal I/O.

Each layer depends only on layers below it. Nothing depends on @max/cli.

`@max/core`

The vocabulary of Max. Entity types, Ref, Schema, Fields, brands, Engine (the data access interface), Loader/Resolver/Seeder contracts, and foundational utilities like StaticTypeCompanion, makeLazy, and MaxError.

No services, no I/O, no file system access. Pure types and data structures.

`@max/connector`

The connector SDK. Contains ConnectorDef, ConnectorModule, Installation, OnboardingFlow, Credential, and ConnectorRegistry. This is what connector authors use to define integrations.

OnboardingFlow describes what to collect from a user during setup (fields, credentials, validation steps, selections). It never describes how to render those steps - that’s a platform concern.

`@max/execution`

Abstract sync orchestration interfaces: TaskStore, TaskRunner, SyncHandle, SyncExecutor, SyncQueryEngine, SyncObserver. Defines what sync execution looks like without choosing how.

Two implementation packages sit alongside it:

@max/execution-local - In-process implementations (InMemoryTaskStore, DefaultTaskRunner, LocalSyncQueryEngine)
@max/execution-sqlite - SQLite-backed implementations (SqliteTaskStore, SqliteSyncMeta, SqliteSyncQueryEngine)

`@max/federation`

The orchestration and business logic layer. Defines three federated scopes:

GlobalMax - operations that don’t require a workspace:

Workspace provisioning
Collection management
Global configuration

WorkspaceMax - operations scoped to a workspace (a .max/ directory):

Installation provisioning and registry
Connector management
Schema inspection

InstallationMax - operations scoped to a single connector installation:

Sync orchestration
Data querying
Health checks

Each scope has typed registries, clients, and protocols. Parent scopes provision children - a workspace provisions installations, global provisions workspaces.

Structured Data Only

Everything in @max/federation returns structured data. No formatted strings, no ANSI codes, no terminal assumptions. A Schema object, not a pretty-printed schema string. This is the reuse boundary.

RPC-Ready

Federation defines protocols for remote communication between scopes. An installation can run in-process, in a daemon, or in a container - the client interface is the same.

`@max/platform-bun`

Bun-specific implementations of federation’s abstract interfaces:

Filesystem services - FsWorkspaceRegistry, FsInstallationRegistry, FsInstallationProvisioner, FsWorkspaceProvisioner, FsCredentialStore
Storage - Wires up SqliteEngine, SqliteTaskStore, SqliteSyncMeta
Deployers - InProcessDeployer, DaemonDeployer, DockerDeployer, RemoteDeployer
Connector registry - NaiveBunConnectorRegistry (scans collections, lazy-loads modules)
RPC transport - BunDaemonTransport, RpcSocketServer
Config - GlobalConfig, ProjectConfig
DI - Three ResolverGraph instances (global, workspace, installation) for typed dependency injection

@max/platform-bun is the composition root - it wires abstract interfaces to concrete implementations.

`@max/cli`

The terminal presentation layer. Everything that touches the user’s terminal:

Argv parsing - Optique parsers, help text, shell completions
Output formatting - ANSI colours, tables, --json flags
Interactive I/O - readline, prompts, onboarding step rendering
Daemon hosting - socket server, PID management, process lifecycle

Daemon is a Deployment Mode

The daemon is not a separate domain. It’s the federation layer hosted in a persistent process, reachable over a Unix socket. The CLI has two execution modes:

Direct: construct platform -> run operation -> format output -> exit
Daemon: construct platform -> keep alive -> accept socket requests -> run operation -> format output -> respond

The federation layer is identical in both modes. The socket protocol and process lifecycle are purely CLI concerns.

Formatting is a CLI Concern

Structured data from @max/federation is formatted by CLI-side printer functions. No formatting logic in the federation layer. If a DTO doesn’t expose enough data for the formatter, the fix is to enrich the DTO’s public surface, not to move formatting upstream.

Onboarding Rendering

OnboardingFlow (defined in @max/connector) describes steps declaratively. The CLI interprets those steps as terminal prompts: readline for input steps, numbered menus for select steps, spinners for validation steps. A web layer would interpret the same steps as form wizards. The flow definition is shared; the rendering is platform-specific.

Supporting Packages

Package	Role
`@max/storage-sqlite`	`SqliteEngine` - the SQLite implementation of the Engine interface
`@max/query-parser`	Parses query strings into ASTs
`@max/plan-parser`	Parses sync plan expressions

Where New Code Goes

I’m adding…	Package
A new entity type, brand, or data structure	`@max/core`
A new connector	A connector collection, using `@max/connector`
A field type, loader variant, or sync primitive	`@max/core`
A new business operation or registry	`@max/federation`
A Bun-specific service implementation	`@max/platform-bun`
A new CLI command	`@max/cli` (parser + routing + formatter)
Output formatting or display logic	`@max/cli`
A new onboarding step type	`@max/connector` (step definition) + `@max/cli` (step renderer)
A new deployer (Docker, remote, etc.)	`@max/platform-bun`

Replication Boundary

If a second platform (web UI, REST API) were added, it would implement @max/federation’s abstract interfaces (like @max/platform-bun does) and replace @max/cli entirely. The shared kernel is everything at and below the federation layer. The replicated surface is platform implementations, input parsing, output formatting, and interactive flow rendering.