# exp/: ExtremePackaging Architecture (Swift)

This folder is the canonical Swift package-architecture rule, formerly the single file `exp.md` (~1700 lines). Split into focused sub-files so the always-loaded set is small and the reference content is loaded on demand.

Follow the "ExtremePackaging" architecture pattern: maximum granular modularization into distinct SwiftPM targets inside the repository's active package. In a package repo the manifest is at the root; in a project monorepo it is under `Packages/`. Each target represents a single cohesive responsibility with explicit dependencies. This enables isolated compilation, parallel builds, clear dependency graphs, and superior testability.

## Always-load core

These two files are loaded in every Swift session. Together they cover the rule statements and the new-package decision flow:

| File | Purpose |
|---|---|
| `critical-rules.md` | Rule 1 to 5: single responsibility, explicit deps, granularity, naming, layer architecture |
| `when-to-create.md` | Decision tree, DO/DON'T new-package list, decision checklist |

## Reference (load on demand)

| File | When to load |
|---|---|
| `implementation-patterns.md` | Adding a foundation/feature/middleware/API/component/font package; building an aggregator |
| `dependency-management.md` | Adding a cross-target or external-package dependency; platform-conditional code (`#if os()`); circular-dep concerns |
| `package-swift.md` | Editing `Package.swift` (`deps`, `allProducts`, `targets` arrays) |
| `common-mistakes.md` | Code review or self-review of `Package.swift` changes |
| `app-target.md` | Adding or modifying an app target (SwiftUI, UIKit, AppKit entry points) |
| `testing.md` | Wiring or restructuring a package's test target (architecture angle; full testing rules in top-level `testing.md`) |
| `migration.md` | Extracting code into a new target or splitting a large one |
| `build-performance.md` | Rationale; read once for context, not normally needed during work |
| `verification.md` | Final checklist before considering an ExtremePackaging change done |

## Concrete example

The canonical Swift monorepo this rule was derived from has the following target layout. Treat as illustrative, not normative; your target list will differ. Package repos use the same tree under root `Sources/`; project monorepos use it under `Packages/Sources/`.

```
Sources/                         # or Packages/Sources/ in a project monorepo
├── Foundation Layer (0 dependencies)
│   ├── SharedModels          # Domain models, no dependencies
│   ├── AppColors             # Color system (HSV, semantic colors)
│   └── AppFont               # Typography, font loading
│
├── Design System Layer
│   └── AppTheme              # Combines AppColors + AppFont
│
├── Infrastructure Layer
│   ├── ApiShared             # OpenAPI spec + generated DTOs
│   ├── ApiClient             # Client-side networking (depends: ApiShared, SharedModels)
│   ├── ApiServer             # Vapor backend (depends: ApiShared, SharedModels)
│   ├── ApiServerApp          # Server executable (depends: ApiServer)
│   └── OpenAPICachingMiddleware  # Caching layer (depends: OpenAPIRuntime)
│
├── Component Layer
│   ├── Components            # CORE component system (AnyComponent, ComponentRegistry, ComponentFactory, etc.)
│   ├── SharedComponents      # Hot reload infrastructure (depends: Inject, KZFileWatchers)
│   ├── AppComponents         # Production app components (depends: Components, AppColors, AppFont)
│   └── AllComponents         # Umbrella package (depends: Components, AppComponents)
│
├── Feature Layer
│   ├── SharedViews           # Reusable views (depends: AppColors, AppFont)
│   ├── AuthFeature           # Authentication (depends: SharedModels, SharedViews)
│   ├── AppFeature            # Main app (depends: SharedModels, SharedViews, AuthFeature)
│   ├── BetaSettingsFeature   # Beta settings (depends: SharedModels, ApiClient)
│   ├── DemoAppFeature        # Demo mode (depends: SharedModels, ApiClient)
│   └── PlaybookFeature       # Component gallery (depends: Components, AppComponents)
│
└── Apps/ (not in Packages/Sources)
    ├── iosApp                # iOS target
    ├── macApp                # macOS target
    ├── ComponentsPreview     # Component preview app
    └── Demo                  # Demo app
```