cmux-architecture

Source excerpt starting at line 1.

1# Package Boundaries2 3Expands the package extraction and layering rules in [../SKILL.md](../SKILL.md).4 5## Domain names vs slice names6 7Good (a domain): `CmuxSettings`, `CmuxSettingsUI`, `CmuxAppearance`, `CmuxWorkspaces`, `CmuxBrowser`, `CmuxControlSocket`.8 9Weak (a slice): `CmuxAppearanceMath`, `CmuxWorkspaceModel`, `CmuxFooFormatting`, `CmuxFooLogic`, `CmuxFooState`. Slices force callers to depend on several sibling packages any time they touch the real domain.10 11## Extract leaf-first12 13Extracting the package with no internal dependencies first keeps the migration incremental: fewer dependency edges, fewer project-file entries, simpler tests, a clearer rollback path. It also avoids needing several downstream packages to exist before one package compiles.14 15## Composition root16 17The executable app target names concrete services and repositories and injects them. No global containers, no runtime-state singletons, no `static let shared`, no service lookups from package internals. SwiftUI `Environment` carries already-constructed observable models down a view tree, never service wiring.18 19## Executable target boundary20 21A lower package cannot extend a higher-owned type without inverting the dependency direction, so `AppDelegate+*` / `cmuxApp+*` extensions do not move down. Extract the behavior into a Coordinator/Service/Repository, inject it into the god object or composition root, and reduce the original extension to a one-line forward.22 23## pbxproj wiring24 25`cmux.xcodeproj` lists package dependencies explicitly. Adding `Packages/CmuxFoo` means mirroring an existing package's entries:26 27- one `XCLocalSwiftPackageReference` in the project's `packageReferences`28- one `XCSwiftPackageProductDependency`29- one `PBXBuildFile` linked in the Frameworks phase of every target that imports it30 31App-target packages link into **both** `cmux` and `cmux-unit` so tests can import and inject them. A package linked by the app but not `cmux-unit` compiles the app and fails the test target. Copy a recent leaf package for the exact shape, then run:32 33```bash34scripts/normalize-pbxproj.py35scripts/check-pbxproj.sh36```37