# Package Architecture How to decompose Tiledown into focused SPM targets within its single package. Tiledown is a monorepo from day one: one `Package.swift` under `Packages/`, many single-responsibility targets in it. The `TileKit` library and the `tile-down` executable are already two such targets, so the decomposition rules below apply now and guide every target that joins the manifest. The pattern: single-responsibility SPM targets with explicit, unidirectional dependencies, all in one package. Each target has one cohesive job and declares exactly what it depends on. This buys isolated compilation, parallel builds, a clear dependency graph, and targets you can test (and lift out) in isolation. ## What this covers Tiledown already has more than one target (the `TileKit` library and the `tile-down` CLI). Add a new target to the single package when one of these is true: - A part of TileKit has become a clearly separable responsibility (a parser, a transport, a renderer) used in more than one place. - Compilation is slow and a large stable chunk would benefit from being its own target. - A second front-door appears (an app target, a server, a second CLI verb set). ## Core rules ### Rule 1: Single responsibility per package Create packages with one clear purpose: - One well-defined responsibility per package. - Do not mix concerns (UI plus networking, models plus API client). - The name communicates the purpose. - Independently buildable and testable. ### Rule 2: Explicit dependency declaration Declare dependencies explicitly in `Package.swift`: - List every dependency in the manifest. - No reliance on implicit or transitive dependencies. - Minimize cross-package dependencies. - Prefer unidirectional dependency flow. ### Rule 3: Package granularity Prefer smaller, focused packages over larger ones: - Single-file packages are fine when the unit is genuinely standalone (a color foundation, a single protocol, a single transport). - Separate by role, not by topical bundling: foundation primitives, infrastructure, protocols, middleware, services, per-feature or per-verb operation packages, front-door binaries. - Each cohesive responsibility (a feature, a CLI verb, a middleware, a transport, a service) gets its own package. ### Rule 4: Naming conventions Use a consistent scheme. Patterns that travel across project shapes: - **Shared foundation:** `Shared*` for cross-target value types, models, utilities, configuration (for example `SharedModels`, `SharedProtocols`). - **Core infrastructure:** `Core*` or a descriptive single-purpose name for the foundation domain (protocols, parsers, transports). - **Per-feature or per-verb operation packages:** one package per user-facing flow (in a UI app) or one per CLI verb (in a CLI). Name after the responsibility, not after a role suffix. - **Service packages:** `*Service`, or a `Services` aggregator for cross-layer read/write services consumed by multiple front-doors. - **Aggregators:** umbrella packages only when the umbrella adds real value (a preview host, an all-features aggregator for app composition). Do not add one by default. For Tiledown specifically, keep the `TileKit` library name as the public anchor and grow new packages around it (for example `TileCore`, `TileParser`) rather than renaming it. ### Rule 5: Layer architecture (unidirectional) Organize packages into layers with dependency flow strictly bottom to top. The exact number of layers varies per project; the constants are: - **Foundation** (bottom): shared value types, models, primitive utilities, logging. - **Infrastructure:** protocols, persistence, networking, file I/O, parsers, transports. - **Domain:** services, business logic, per-feature or per-verb operation packages. - **Presentation** (UI projects only): component packages, design-system packages, screens. - **Front-door** (top): binary targets, apps, CLIs, preview hosts, test harnesses. Every dependency edge points upward. No back-edges. The active layer instantiation lives in the project's own `Package.swift`. ## When to create a new package ### Decision tree ``` Need to add new code? ├─ Is it a reusable domain model or value type? │ └─ YES → add to the shared foundation package (e.g. SharedModels) │ ├─ Is it a cross-target protocol seam? │ └─ YES → add to SharedProtocols (see shared-protocols.md) │ ├─ Is it a complete user-facing feature or a distinct CLI verb? │ └─ YES → create a new feature / verb package │ ├─ Is it infrastructure (transport, parser, persistence, middleware)? │ └─ YES → create or extend the matching infrastructure package │ └─ Still unsure? └─ Ask: "Could this be reused or tested in isolation?" ├─ YES → create a new package └─ NO → add to the most specific existing package ``` ### Create a new package when 1. **It is a complete feature or distinct verb** (a self-contained user-facing flow, or one CLI command's logic). 2. **It is reusable infrastructure** that can be tested in isolation and used by more than one consumer (a caching middleware, a transport). 3. **It wraps a third-party integration**, isolating that external dependency behind a seam. 4. **It is platform-specific** code that is cleaner separated (iOS-only vs macOS-only). 5. **It is a build-optimization win**: large, stable, or expensive-to-compile code (for example generated code) that rarely changes. ### Do NOT create a new package when 1. **It is single use**, only used by one feature and tightly coupled to it. Add it to that feature's package. 2. **It is a trivial helper** of one or two functions with no external dependencies. Add it to an existing utility package. 3. **It is temporary** (a spike or proof of concept). Keep it in the feature until it proves stable. ## Decision checklist Before creating a new package: - [ ] One clear responsibility - [ ] Name follows the conventions above - [ ] Dependencies are minimal and explicit - [ ] No circular dependency introduced - [ ] Can be built and tested in isolation - [ ] Fits a single architectural layer - [ ] Test target created alongside the source target - [ ] Product registered in the `Package.swift` products array - [ ] Dependencies only flow upward Before adding to an existing package: - [ ] The new code shares a responsibility with what is there - [ ] No better-suited package exists - [ ] You are not creating a "god package" with mixed concerns - [ ] You are not introducing unwanted dependencies onto the package's consumers Before modifying `Package.swift`: - [ ] Used a closure-with-local-variables pattern for the `deps`, `allProducts`, and `targets` arrays rather than one giant inline array - [ ] Grouped dependencies by purpose, products by platform, targets by layer, with comment headers - [ ] Separated platform-specific code with `#if os(iOS) || os(macOS)` in the manifest - [ ] Did NOT use `#if canImport(UIKit)` in `Package.swift` (the manifest evaluates it lazily and it breaks Linux builds; `#if os()` is parse-time and safe). In regular Swift source files, `#if canImport(UIKit)` / `#if canImport(AppKit)` is the correct idiom. - [ ] Each target/product/dependency has a descriptive variable name - [ ] Trailing commas in all arrays - [ ] `.when(platforms:)` applied for platform-specific dependencies within targets If you add a font or resource package: - [ ] Used `.process()` for resources, never `.copy()` - [ ] Accessed resources via `Bundle.module`, never `Bundle.main` - [ ] Used `#if canImport(UIKit)` / `#if canImport(AppKit)` for platform imports - [ ] The package has zero dependencies (resources are a foundation-layer concern) ## Example layout (illustrative, not normative) As Tiledown grows targets within its single package, the layout might look like this. Your actual target list will differ. ``` Packages/Sources/ ├── Foundation Layer (0 internal dependencies) │ ├── TileCore # core value types, no dependencies │ └── SharedProtocols # cross-target protocol seams │ ├── Infrastructure Layer │ ├── TileParser # depends: TileCore │ └── TileTransport # depends: SharedProtocols │ ├── Domain Layer │ └── TileKit # the main library; depends: TileCore, TileParser │ └── Front-door (not under Sources/) └── tile-down # the CLI executable; wires the concretes ``` ## Related rules - [package-structure.md](package-structure.md): repository layout and the `Package.swift` manifest shape - [package-import-contract.md](package-import-contract.md): what each target may import - [shared-protocols.md](shared-protocols.md): the cross-target protocol-seam package - [dependency-injection.md](dependency-injection.md): the DI principles these layers serve