pproenca/dot-skills/domain-architect

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

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:

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

1. Start from the product, not the files. "What can users do?"

comes before "what files exist?"

1. Do not classify by folder path. A file in Services/ might

be UI code. Read before classifying.

1. 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.

1. Do not skip domains because they look similar. Each domain gets

its own vertical trace. Auth is not Profile.

1. Use subagents for codebases with >200 files. One agent per

domain, each traces the full vertical. This prevents shortcuts from context pressure.

1. Flag ambiguities instead of deciding. You lack the team's

context. Present evidence for both sides. Let the team decide.

Depth Requirements

1. 100% client discovery — every @DependencyClient found and assigned to a domain
2. 100% reducer discovery — every @Reducer found and assigned to a domain
3. Vertical trace per domain — at least one file read per layer per domain
4. Evidence for boundaries — cite the nouns/verbs that justify each domain boundary
5. Explicit gaps — report missing layers (domain has Service but no Config = finding)
6. Questions over assumptions — when unsure, ask rather than guess