Article

<Apple sample title>

At a glance

Item	Summary
Purpose	<What the sample demonstrates>
App architecture	<High-level composition>
Main patterns	<Only source-supported patterns>
Project style	<Folder and target organization>
Execution model	<Source-visible actor, task, queue, run-loop, or callback boundary; do not infer a thread>
State/event model	<Observation, Combine, callback, notification, or direct mutation mechanism>
Key frameworks/packages	<Cited source imports and manifest declarations only>

Project structure

Show only architecturally meaningful folders and files.

<Pruned source tree>

Structure observations

<Boundary, grouping, and file-to-type observations>

Overall architecture

Keep the primary diagram high-level, normally between 6 and 12 nodes.

flowchart LR
    Entry["App entry"] --> UI["UI"]
    UI --> State["State owner"]
    State --> Service["Framework service"]

Reference code

<relative/source/path.swift>:<line> — <Symbol>

<Short exact or explicitly abbreviated excerpt>

Interpretation

Ownership and state

classDiagram
    App *-- StateOwner : creates and owns
    StateOwner *-- Service : owns
    View --> StateOwner : observes

Use *-- for lifecycle ownership, o-- for shared or externally supplied objects, and --> for use, observation, or delegation.

Ownership evidence

<relative/source/path.swift>:<line> — <Symbol>

<Short ownership or initialization excerpt>

Owner	Object or state	Relationship	Mutation authority
`<Type>`	`<Dependency or state>`	<Creates, retains, injects, observes, delegates>	`<Type>`

Concurrency, scheduling, and thread safety

Evidence limit: actor isolation, async/await, or Task creation does not by itself prove background-thread execution; Sendable conformance alone does not prove thread-safe mutation.

Distinguish isolation from scheduling. @MainActor and MainActor.run are main-actor contracts; DispatchQueue.main submits work to the main serial queue; RunLoop.main identifies the main thread’s event loop. None is interchangeable without source evidence.

Concern	Source mechanism	Verified placement or handoff	Evidence
Main-actor isolation	`@MainActor` or `MainActor.run`	<What declaration, state, or operation is isolated>	`<file>:<line>`
Main-queue scheduling	`DispatchQueue.main`	<What work or callback is submitted>	`<file>:<line>`
Task or worker execution	Actor executor, `Task`, `Task.detached`, global/custom queue	<What work is created or scheduled; say when the destination executor is not established>	`<file>:<line>`
Shared-state safety	Actor isolation, lock, serial queue, or another synchronization primitive	<The exact protected state and mutation boundary>	`<file>:<line>`
Scheduling/liveness	`RunLoop`, timer, operation queue, or callback	<What is scheduled or kept alive>	`<file>:<line>`

Treat a plain Task {} as task creation whose surrounding context determines actor inheritance. Treat Task.detached separately. Do not describe an actor, async function, or suspension point as a background thread unless the cited source establishes an executor or queue handoff.

Reference code

<relative/source/path.swift>:<line> — <Execution or synchronization boundary>

<Short structurally complete excerpt>

State propagation, frameworks, and dependencies

Evidence limit: an import proves a source-level compilation dependency at the cited line; it does not prove runtime use, architectural adoption, or whether a Swift package is a direct application dependency.

Category	Mechanism or module	Verified role	Evidence
State propagation	Observation, SwiftUI state, callback, notification, or Combine publisher	<How values reach an observer or consumer>	`<file>:<line>`
Combine scheduling	`receive(on:)` or `subscribe(on:)`	<Downstream delivery versus upstream subscription/request/cancel scheduling>	`<file>:<line>`
Framework import	`<Module>`	<Compilation dependency only; add runtime role only when cited separately>	`<file>:<line>`
Package declaration	Remote/local manifest entry	<Manifest-declared dependency; classify direct/local/transitive only when target evidence proves it>	`<Package.swift>:<line>`

An import Combine does not establish a Redux-style store, reducer architecture, or even publisher scheduling. Likewise, an imported framework or a vendored Package.swift does not by itself establish the app’s dependency direction.

Class and protocol design

Include a class diagram only when it clarifies meaningful type or protocol boundaries.

classDiagram
    class Capability {
        <<protocol>>
    }
    Concrete ..|> Capability
    Consumer --> Capability

Reference code

<relative/source/path.swift>:<line> — <Protocol or type>

<Short protocol, conformance, or dependency excerpt>

Type	Responsibility	Depends on
`<Type>`	<Single primary responsibility>	`<Dependency>`

Access control

Document only access modifiers that affect a boundary, invariant, or collaboration.

Symbol	Access	Verified effect	Likely rationale
`<Symbol>`	`private`	<What code can access or mutate it>	<Clearly labeled inference>

Reference code

<relative/source/path.swift>:<line> — <Symbol>

<Short private, fileprivate, private(set), internal, public, or open excerpt>

Logic ownership and placement

Logic	Owning type or file	Placement rationale
<UI, coordination, state, framework, persistence, transformation>	`<Type>`	<Observed effect and concise interpretation>

Design patterns

Do not force a named pattern when the source doesn’t support one. Separate a bounded design pattern (Delegate, Observer, Adapter, Strategy, Factory) from a whole-app architecture. Publish a named architecture only when the downloaded source establishes its collaborating roles and dependency direction; omit unsupported and zero-evidence comparisons.

Pattern	Source evidence	Purpose or tradeoff
<Pattern>	`<file>:<line>` and `<symbol>`	<Why the structure matters>

Main application flow

Add this section only when one asynchronous or multi-stage flow materially improves understanding. Pair every diagram with a short source excerpt.

Use a sequence diagram only when all of these checks pass:

At least three participants have distinct responsibilities.
The flow contains at least four ordered messages or state transitions.
The code uses an async task or stream, callback, delegate, loop, or notification.
Source excerpts prove the order rather than merely suggesting collaboration.
The diagram is scoped to one clear user action or system event.

sequenceDiagram
    actor User
    participant UI
    participant Owner
    participant Service
    User->>UI: Action
    UI->>Owner: Intent
    Owner->>Service: Operation
    Service-->>Owner: Result
    Owner-->>UI: State update

Reference code

<relative/source/path.swift>:<line> — <Method>

<Short flow excerpt>

Naming conventions

Types: <Role, feature, or capability naming>
Protocols: <Capability or collaborator naming>
Methods: <Command, factory, loading, and Boolean conventions>
Files and extensions: <Primary-type and conformance organization>

Architecture takeaways

<Three to five reusable, evidence-backed observations>

Source map

Source file	Relevant symbols
`<relative/source/path>`	`<Symbols>`

Official Apple documentation