Clean Architecture for Native macOS Apps - Modular Frameworks and Actor-Based Sync
Clean Architecture for Native macOS Apps
Building a native macOS app with real complexity - like file syncing, background services, and deep OS integration - demands clean architecture from day one. The pattern that works best is splitting your codebase into modular frameworks with actor-based concurrency handling the sync engine.
Why Modular Frameworks Matter
A monolithic macOS app becomes unmaintainable fast. When you have six separate frameworks - say, Models, Networking, SyncEngine, FileProvider, UI, and Utilities - each one compiles independently. AI agents can modify one framework without accidentally breaking others. Tests run in isolation. Build times stay reasonable.
Actor-based sync is the key to getting concurrency right. Swift actors serialize access to mutable state, which means your sync engine handles edge cases like conflicting writes, partial downloads, and interrupted uploads without race conditions.
The File Provider Challenge
Apple's File Provider framework is notoriously under-documented. The official docs cover the basics but skip the edge cases that matter most - handling eviction, dealing with enumeration invalidation, and managing the coordination between your sync engine and the system's file provider daemon.
The best approach is treating the File Provider extension as a thin adapter. It translates between the system's expectations and your sync engine, which lives in its own framework with full test coverage. This way you can test sync logic without involving the File Provider at all.
Sync Engine Edge Cases
The hardest problems in sync are not the happy path. They are conflict resolution when two machines edit the same file, handling network drops mid-upload, and recovering gracefully from corrupted local state. Building these as isolated, testable units inside an actor makes them manageable instead of terrifying.
If you are building a macOS app that needs to sync data reliably, invest in the architecture before writing features. The time spent on clean module boundaries pays back immediately.
Fazm is an open source macOS AI agent. Open source on GitHub.