SwiftUI Series 15｜Build a maintainable SwiftUI project from scratch

If I were asked to build a SwiftUI project from scratch, the first thing I would consider would not be what the directory looks like, nor would I worry about it first:

• Do you need to submit a complete architecture template?
• Do I need to draw a lot of base layers first?

What I want to think about first is these things:

• How the status flows
• How to switch page responsibilities
• When and to what extent are components pumped?
• Will the project become difficult to modify after three months?

Because many SwiftUI projects are quite light at first, the real watershed often occurs after two or three months:

• More and more pages
• The state is getting worse and worse
• Component reuse is becoming more and more random
• Start stacking business logic in View

So what “maintainability” really wants to solve is stability after growth, not development speed in the first week.

1. I will not build a heavy framework from the beginning, but first clarify the responsibilities.

One of the most common misunderstandings when starting a project from scratch is:

• The business has not started yet
• First lay out a complete set of structures that look complete

This is not necessarily wrong, but the risk is:

• abstract too early
• The structure does not match the real business
• The team will keep bypassing it later

So I prefer:

• Make the boundaries of responsibilities clear first
• Gradually add layers as the complexity increases

Rather than “being big and complete on the first day”, I value “being smooth in the first month” more.

2. The first thing I usually understand is the three layers: page layer, status layer, and capability layer.

1. Page layer

Responsible for:

• Structure
• Component combination
• Page status mapping

2. State layer

Responsible for:

• Business status
• Asynchronous processes
• Page semantic state switching

3. Capability layer

Responsible for:

• network
• Storage
• Domain services
• Common components and styling capabilities

These three layers may not necessarily be dismantled very finely from the beginning, but awareness must be there first. Otherwise, SwiftUI projects can easily slip into “write everything directly in the View”.

3. I will be very wary of “giant views”

Writing UI in SwiftUI is very easy, so one of the most common bad smells is:

• The structure is written in View
• Request is written in View
• Status judgment is written in View
• Copywriting assembly is also written in View

Of course it looks very fast in the early stages, but once the project becomes complex, the View will quickly become:

• Difficult to read
• Difficult to change
• Unpredictable

The problem here is that the View takes on too many non-display responsibilities.

4. I will deliberately slow down the reuse of components instead of doing it hard at the beginning.

It’s easy for many teams to pursue a “universal component library” at first. But in real projects, abstracting too early is often more dangerous than abstracting later:

• The interface will be designed to be too wide
• Many options are prepared for possible future scenarios
• Components appear to be reused, but in fact whoever uses them will feel uncomfortable

So I prefer to let the component grow in one or two real pages first, and then extract it after the pattern is stable enough. The components extracted in this way are usually closer to real use than abstract gymnastics.

5. State boundaries are usually more important than directory structure

Many projects spend a lot of time arguing at the beginning:

• Feature-first or Layer-first
• How to divide folders

Of course these are important, but what I care more about is:

• Which status is managed by the page itself?
• Which states are managed by external business objects
• Which status should be shared and which should not be shared

Because what really determines maintenance costs is often whether the status is running around.

6. The core of maintainability is actually to let each layer “clearly explain what it is responsible for”

If a project becomes increasingly difficult to change later on, there are usually these signs:

• The page structure does not show the priority
• Status attribution becomes increasingly blurry
• Component boundaries are becoming more and more abstract
• Once the requirements are changed, logic must be supplemented across many layers

So for a maintainable SwiftUI project, what I value most is usually:

• The page can be read at a glance
• Status can be distinguished at a glance
• Component boundaries are natural -Business logic is not stacked in View

These four things are very simple, but extremely valuable in the long run.

7. Conclusion: When building a SwiftUI project from scratch, what really needs to be set correctly first is the boundary, not the template.

To put it in shorter form, I would say:

To build a maintainable SwiftUI project from scratch, the most important thing is to get the state boundaries, page responsibilities and component abstraction right.

Once these boundaries are established, the project will grow longer and more stable; If the boundaries are not established, no matter how advanced the template is, it can easily be washed away by real business.