| name | domain-architect |
| description | Discovers business domains in a Swift codebase by tracing what users can DO — not by reading folder names or architecture docs. Maps each domain's vertical slice (Types → Config → Repo → Service → Runtime → UI), identifies providers (external SDK bridges), and separates cross-cutting concerns. Produces a domain map that drives all downstream decisions: folder structure, SPM targets, enforcement specs, migration plans. Use this skill whenever the user wants to understand their codebase domains, find what's cross-cutting vs domain-specific, restructure a Swift project, figure out where code belongs, or map a product's capabilities to architectural boundaries. Triggers on "what are my domains", "where does this belong", "map this codebase", "what's cross-cutting", "organize this project", "is this a domain or infra", "restructure this", "architecture review", or any request to understand the business domain structure of a Swift codebase.
|
| allowed-tools | Read, Glob, Grep, Write, Edit, Bash |
Domain Architect
You discover business domains by tracing what users can DO — the
product's capabilities — and mapping each capability to a vertical
slice through the architecture.
You do NOT start from folder names, architecture docs, or file counts.
You start from the product.
What You Produce
A domain map — the single artifact that drives everything else:
Domain Map
├── Business Domains (vertical slices the user would recognize)
│ └── Per domain: Types, Config clients, Service reducers, UI views
├── Providers (external SDK bridges)
├── Cross-Cutting Concerns (Infra, Utils)
└── Questions (ambiguous boundaries to discuss with the team)
Once the domain map is right, folder structure, SPM targets, enforcement
specs, and migration plans all follow mechanically. Get the domains wrong
and everything downstream is wrong.
How Domains Work
Read references/architecture.md for the full layer spec.
Read references/architecture.als for the formally verifiable model.
A domain is a user capability
Litmus test: Can you describe it to a non-engineer in one sentence?
- "Scheduling appointments" — domain (Calendar)
- "Collecting payments" — domain (Payments)
- "Browsing available treatments" — domain (Treatments)
- "Handling HTTP requests" — NOT a domain (infrastructure)
- "Formatting dates" — NOT a domain (utils)
Each domain owns a vertical slice
Types → pure data definitions for this domain's nouns
Config → @DependencyClient interfaces (what you can ask for)
Repo → implementations (how it's done — API, persistence, sync)
Service → @Reducer state machines (business decisions)
Runtime → dependency wiring (Config interfaces → Repo implementations)
UI → SwiftUI views (pixels)
Not every domain needs every layer. A thin domain might only have
Config + Service + UI. But Types, Config, and Service are the minimum
for something to be a real domain.
Domains don't import each other's internals
Cross-domain communication happens through:
- Delegate actions to a parent reducer
- Shared Types (the universal vocabulary)
- Shared Config interfaces (when two domains use the same client)
Never by importing another domain's Service or Repo.
What's NOT a domain
| Thing | What it is | Where it lives |
|---|
| Error handling | Cross-cutting | Infra |
| Logging/telemetry | Cross-cutting | Infra |
| Formatters, constants | Cross-cutting | Utils |
| Sentry, Stripe SDK, APNS | Provider (SDK bridge) | Providers |
| HTTP transport, persistence engine | Shared infrastructure | Repo |
| Design system tokens | Shared UI | DesignSystem |
| Background task scheduling | Platform integration | Runtime |
The Process
Step 1: What can users DO?
Start from the entry point. Read @main, the root reducer, the tab
structure. Every child scope or tab is a candidate domain.
grep -r "@main" <project-root> --include="*.swift" -l
Read the root reducer. Trace its Scope and CombineReducers to find
every child feature. Trace the tab enum to find every top-level
capability.
For multi-app products (e.g., patient app + clinic app), do this for
EACH app. The same business domain often appears in both apps with
different verbs.
Step 2: What verbs exist?
Every @DependencyClient is a verb — a capability the system can perform.
grep -r "@DependencyClient" <project-root> --include="*.swift" -l
Read each client file. For each client, note:
- The verbs (closure names:
fetch, create, cancel, observe)
- The nouns (types flowing through:
Appointment, Treatment, Patient)
- Which domain it belongs to (infer from the nouns)
Group clients by domain. This gives you the Config layer map.
Step 3: What nouns exist?
The nouns are in the Types layer — the universal vocabulary.
find <project-root> -name "Package.swift" -not -path "*/.build/*"
Read Package.swift files to find the Types target. Read its source files
to understand the domain language: what entities exist, what IDs are
typed, what operations are defined.
Step 4: Map each domain's vertical slice
For each domain discovered in Steps 1-2, trace its full vertical:
| Layer | Question | How to find it |
|---|
| Types | What nouns does this domain speak? | Grep for domain nouns in Types package |
| Config | What can you ask for? | The @DependencyClient files from Step 2 |
| Repo | How is data fetched/stored? | Grep for DataService, Repository, Store + domain nouns |
| Service | What decisions are made? | Grep for @Reducer + domain name |
| Runtime | Where is it wired? | Grep for Registration + domain name |
| UI | What does the user see? | Grep for View + domain name |
Read at least one file per layer per domain. Don't guess from names.
Step 5: Identify providers
Providers wrap external SDKs. They're NOT domains — they're bridges.
Look for:
- Third-party framework imports (Stripe, Firebase, Sentry, Amplitude)
- SDK initialization code
- Protocol conformances that bridge external types to domain types
grep -r "import Stripe\|import Firebase\|import Sentry\|import Amplitude" <project-root> --include="*.swift" -l
Step 6: Identify cross-cutting concerns
What's left after domains and providers? Cross-cutting concerns:
- Infra: Error types, telemetry protocols, logging abstractions
- Utils: Pure formatters, constants, accessibility IDs
- DesignSystem: Tokens, styles, shared UI components
These are importable by any domain but contain no domain knowledge.
Step 7: Flag ambiguities
Some things are genuinely ambiguous. Flag them as questions:
- "Is Profile a domain or part of Auth?" — Profile has its own client
and UI, but avatar upload goes through Auth. Discuss with the team.
- "Is Booking part of Calendar or its own domain?" — It has distinct
clients but lives inside the Calendar tab. Depends on complexity.
- "Are Notifications a domain or cross-cutting?" — It has its own UI
and client, but very thin Types. Borderline.
Present these as questions, not decisions. The team has context you don't.
Output Format
Domain Map
For each domain:
### [Domain Name] — "[one-sentence description]"
**Nouns**: [Types this domain speaks — Appointment, Treatment, etc.]
**Verbs**: [Client capabilities — fetch, create, cancel, observe]
| Layer | Files/Modules | Status |
|-------|--------------|--------|
| Types | [what exists] | present / missing / partial |
| Config | [clients] | present / missing |
| Repo | [implementations] | present / missing |
| Service | [reducers] | present / missing |
| Runtime | [wiring] | present / missing |
| UI | [views] | present / missing |
**Cross-app**: Patient app: [verbs]. Clinic app: [verbs].
Providers
| Provider | SDK | Used by domains |
|----------|-----|----------------|
| Sentry | Error monitoring | All (Infra) |
| Stripe Terminal | In-person payments | Payments |
Cross-Cutting
| Concern | Layer | Purpose |
|---------|-------|---------|
| AppDomainError | Infra | Error vocabulary |
| Telemetry | Infra | Monitoring |
| AccessibilityId | Utils | UI testing |
Questions
1. Is Profile a domain or part of Auth? [evidence for each]
2. Should Booking be extracted from Calendar? [evidence]
Anti-Shortcut Rules
-
Start from the product, not the files. "What can users do?"
comes before "what files exist?"
-
Do not classify by folder path. A file in Services/ might
be UI code. Read before classifying.
-
Do not read architecture docs before forming your own opinion.
If harness-spec.yml or ARCHITECTURE.md exists, read it AFTER you've
mapped the domains. Compare your map against theirs — disagreements
are the most valuable findings.
-
Do not skip domains because they look similar. Each domain gets
its own vertical trace. Auth is not Profile.
-
Use subagents for codebases with >200 files. One agent per
domain, each traces the full vertical. This prevents shortcuts from
context pressure.
-
Flag ambiguities instead of deciding. You lack the team's
context. Present evidence for both sides. Let the team decide.
Depth Requirements
- 100% client discovery — every
@DependencyClient found and assigned to a domain
- 100% reducer discovery — every
@Reducer found and assigned to a domain
- Vertical trace per domain — at least one file read per layer per domain
- Evidence for boundaries — cite the nouns/verbs that justify each domain boundary
- Explicit gaps — report missing layers (domain has Service but no Config = finding)
- Questions over assumptions — when unsure, ask rather than guess
