A new open-source project called Cocoa Way has surfaced on GitHub with an ambitious thesis: most Apple platform developers are doing architecture wrong — not because they lack skill, but because the dominant patterns imported from other platforms don’t fit the grain of Apple’s frameworks. The project, authored by a developer known as J-x-Z, lays out a philosophy and set of practices that push back hard against years of accepted wisdom in the Swift and Objective-C community. It’s a provocation dressed up as a style guide.
And it’s arriving at a moment when the Apple developer community is already in the middle of a quiet identity crisis.
The Cocoa Way repository on GitHub doesn’t ship a framework or a library. There’s no CocoaPod to install, no Swift Package to import. Instead, it offers a structured set of principles for building macOS and iOS applications that work with Apple’s own tooling rather than against it. The core argument is deceptively simple: Cocoa and its modern descendant, SwiftUI, already contain strong architectural opinions. Developers who layer on external patterns — MVVM borrowed from Microsoft’s WPF, VIPER imported from enterprise Java thinking, or Redux-style unidirectional data flow lifted from the React world — are often fighting the platform rather than building on it.
That’s a controversial position. For the better part of a decade, the iOS development community has treated architectural patterns as a mark of professionalism. “Massive View Controller” became a pejorative. Entire conference talks, blog posts, and Twitter threads have been devoted to escaping what many saw as Apple’s naive default architecture. The Cocoa Way project says this was a wrong turn.
The repository’s documentation argues that Apple’s frameworks were designed with specific assumptions about how data flows through an application, how views are composed, and how state is managed. When developers bolt on patterns from other traditions, they create friction. Boilerplate multiplies. Simple features require touching five or six files. New team members spend more time learning the architecture than learning the domain. The project’s position is that this complexity is self-inflicted.
This isn’t entirely new thinking. Voices in the Apple developer community have periodically pushed back against architecture astronautics. But the Cocoa Way project attempts to codify that pushback into something coherent and teachable. It addresses view controller composition, data passing, notification patterns, and the relationship between model objects and views — all while staying within the idioms that Apple’s own sample code and WWDC sessions have promoted for years.
The timing matters. SwiftUI, now in its sixth year, has forced a reckoning. Developers who spent years building elaborate MVVM or coordinator-pattern infrastructures for UIKit found that SwiftUI’s declarative model and built-in state management tools — @State, @Binding, @Observable — rendered much of that machinery unnecessary. Or worse, actively counterproductive. SwiftUI wants to own the view lifecycle. It wants to manage state diffing. It wants to handle navigation. Developers who try to wrest control away from these systems often end up with brittle, hard-to-debug code.
The Cocoa Way project reads like a direct response to this pain.
J-x-Z’s repository organizes its guidance around several themes. First, trust the frameworks. Apple engineers designed Cocoa Touch and SwiftUI with specific architectural assumptions baked in. Working within those assumptions — rather than abstracting them away behind protocol-heavy indirection layers — leads to code that’s easier to read, easier to maintain, and easier for new developers to pick up. Second, prefer composition over inheritance, but do so using the composition tools the platform provides: child view controllers in UIKit, smaller views in SwiftUI, and the responder chain for event handling. Third, keep the model layer simple. Not everything needs a repository pattern, a service layer, and a mapper. Sometimes a struct and a function are enough.
There’s a pragmatism here that will resonate with experienced Apple developers who’ve watched projects drown in abstraction. But it will also irritate those who believe that platform-agnostic architecture is a prerequisite for testable, maintainable code.
The testability question is, in fact, the sharpest critique likely to be leveled at the Cocoa Way approach. The entire reason patterns like MVVM gained traction in the iOS world was to separate business logic from UIKit, making it possible to write unit tests without spinning up view controllers or mocking Apple’s frameworks. If you embrace Apple’s architecture more fully, are you giving up testability? The Cocoa Way project argues no — that Apple’s own tools, including Xcode’s XCTest framework and the newer Swift Testing package introduced at WWDC 2024, are sufficient when code is properly structured. But the repository acknowledges this is an area where reasonable developers disagree.
The broader context here is a generational shift in the Apple developer community. The cohort that came up building apps in the early iPhone era — 2008 through 2015 or so — learned Objective-C, UIKit, and MVC as Apple taught it. Many then adopted increasingly complex architectural patterns as apps grew larger and teams expanded. A newer generation, entering through SwiftUI and Swift, often finds those patterns bewildering and unnecessary. The Cocoa Way project is, in a sense, a bridge document: it validates the instincts of newer developers while giving experienced ones permission to simplify.
Open-source architectural guides aren’t new on GitHub. Projects like Point-Free’s libraries have offered opinionated approaches to Swift architecture for years, particularly through The Composable Architecture (TCA), which applies Redux-like principles to SwiftUI. TCA has gained a significant following, but it has also drawn criticism for its learning curve and the amount of boilerplate it introduces. The Cocoa Way sits at the opposite end of this spectrum — less framework, more philosophy.
Whether the project gains traction will depend on several factors. Community adoption of architectural philosophies on Apple platforms has historically been driven by conference talks, popular blog posts, and endorsement by well-known developers. The Cocoa Way repository is still young, with limited stars and forks as of this writing. But its core message — stop overengineering, trust the platform — taps into a growing sentiment.
Apple itself has been sending similar signals. Recent WWDC sessions have emphasized using SwiftUI’s built-in tools for state management and navigation rather than building custom solutions. The introduction of the @Observable macro in Swift 5.9 and its refinement in subsequent releases have made it easier to build reactive interfaces without external dependencies. Apple’s own sample code has grown more opinionated, showing complete apps built with minimal architectural scaffolding. The message from Cupertino, whether intentional or not, aligns with what the Cocoa Way project advocates.
So what does this mean for teams shipping production apps today?
For small teams and solo developers, the Cocoa Way’s advice is straightforward: don’t adopt complexity you don’t need. Start with Apple’s defaults. Add abstraction only when you hit a specific, concrete problem that demands it. For larger teams with established codebases built on MVVM, VIPER, or TCA, the calculus is different. Rearchitecting a working app to conform to a new philosophy is almost never worth the cost. But for new features or new projects, the Cocoa Way’s principles offer a useful counterweight to the instinct to reach for the most sophisticated pattern available.
The project also raises questions about how the Apple developer community evaluates technical maturity. For years, the complexity of your architecture was treated as a proxy for the seriousness of your engineering. Simple code was amateur code. The Cocoa Way pushes back on this directly: simplicity, it argues, is the harder discipline. Knowing when not to abstract is a skill that takes longer to develop than knowing how to build a coordinator pattern.
That’s a message the industry needs to hear more often. Not just on Apple platforms, but everywhere software is built.
The Cocoa Way project is available on GitHub under an open-source license. It remains a work in progress, with the author inviting contributions and discussion. Whether it becomes a reference point for a new generation of Apple developers or remains a niche manifesto will depend on whether its ideas survive contact with the messy realities of production software development. Early signs suggest the conversation it’s starting is one many developers have been waiting to have.
WebProNews is an iEntry Publication