The Airframe Guide

Build on the Airframe.

Swift Airframe is a layered architecture for native macOS apps — AppKit as the skeleton, SwiftUI hosted inside it as a rendering layer. Every native app has an airframe underneath its interface — the structure everything else is riveted to. Ten chapters: how the layers fit together, how the app comes off the ground, where state lives, how a user's intent becomes a change in that state, and how the interface, menus, navigation, and test suite all follow from the same handful of rules.

G01

Getting Started

Airframe is an opinionated layered architecture for native Swift apps — AppKit and SwiftUI working together under one rule for where state lives and who is allowed to change it. This chapter lays out the four layers, the two paths data takes through them, and the single synchronization model that makes the whole thing hold together.

G02

The App Environment

Before the first window appears, an app has already made its most consequential wiring decisions: who receives the platform's lifecycle events, what gets configured in which order, where user preferences live, and how objects find their collaborators. This chapter covers that environment as a whole, then five subchapters take one piece each.

G03

The Controller Layer

Controller is one of this guide's most overloaded words — Action Controllers, Background Controllers, view state controllers, view controllers, menu controllers. This chapter names the paradigm they all share: an object that bridges two layers and coordinates work across that boundary, knowing who and when, never how.

G04

Background Controllers

Not every write in this guide happens because a user asked for it. This chapter covers the background controller — the long-lived, Foundation-only object that keeps the app current with no gesture behind it at all: periodic refreshes, reactions to system events, state derived continuously from the Model.

G05

The Model Layer

The Model is the source of truth, and it stays trustworthy because of one rule applied without exception: every mutation, from every source, funnels through a single manager. This chapter explains why that funnel matters, where the main thread fits, and how to pick the right shape for a given piece of state.

G06

Actions and Controllers

Not every write deserves ceremony. This chapter introduces the coordination layer that sits between a user's gesture and the Model layer's write funnel — the Action and the Action Controller — and lays out how the two relate before three subchapters go deeper on each.

G07

Concurrency

Build manager operations with background jobs, declare which work can overlap, and report progress without moving application state off the main actor.

G08

The View Layer

Views read from the Model. This chapter introduces the read/render side of the architecture — how a SwiftUI view hosted inside AppKit stays reactive, how a view controller assembles and scopes that hierarchy, the activation lifecycle that drives it, and the menus that are themselves just another view component — and lays out how the four relate before four subchapters go deeper on each.

G09

Navigation

Every chapter so far has been about one screen. This one is about the seam between screens — and why that seam is a state object owned by a parent, never a view holding a reference to another view.

G10

Testing

Not everything earns a test. This closing chapter is about testing at the altitude where regressions actually happen, skipping the layers that structurally can't fail on their own, and reaching for real collaborators instead of mocks almost everywhere.