170 lines
8.7 KiB
Markdown
170 lines
8.7 KiB
Markdown
# 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
|