The Maintainability and Evolvability pillar averages 61.1 out of 100 across the 21 third-party apps I audited in June and July 2026, and, in my reading, code can be tidy file by file while nobody can say how the app fits together. Software architecture is that fit: the parts, how they connect, and the decisions that are expensive to reverse. A small SaaS needs 4 views of it.
What is software architecture? The meaning in plain terms
Software architecture is the structure of a system and the decisions about it that are expensive to reverse. The international standard names three ingredients: the parts, the relationships between them, and the principles of the system’s design and evolution. By my working rule, if altering something next year would take a rewrite or a data migration, it is architecture.
That 61.1 comes from a selected set: the third-party apps in my June and July 2026 audits, all 21 of them scored on this pillar, which is not a random sample and not a rate for AI-built apps in general. Architecture is also the part of what a developer handoff looks like that cannot be copied across: the repository changes hands with a few clicks, the reasoning behind it does not.
Three sources define software architecture in ways worth reading together. The standard’s wording, in the ISO/IEC/IEEE 42010 definition from its 2011 revision, is “fundamental concepts or properties of a system in its environment embodied in its elements, relationships, and in the principles of its design and evolution.” The Software Engineering Institute is shorter; the SEI’s definition says “The software architecture of a system represents the design decisions related to overall system structure and behavior.” Martin Fowler’s architecture guide credits an email exchange with Ralph Johnson, who described architecture as “the shared understanding that the expert developers have of the system design” and as “the decisions you wish you could get right early in a project.”
Read side by side, those software architecture definitions agree on three things: the parts, the connections between them, and a small set of decisions that cost a lot to undo. In simple terms, that is what software architecture means for the rest of this page.
The test I apply for whether something counts is my working rule, not a standard: would changing it next year take a rewrite, a migration or a data conversion, or would it take an afternoon? The database, the auth provider, how tenants are kept apart, where files live, and whether slow work runs inside the request or on a queue all fall in the first group. A component library or a folder name falls in the second.
Software and system architecture, and where design starts
System architecture and software architecture are two levels of one description. System architecture covers everything that runs: hosting, the database service, queues and third-party APIs. Software architecture is the structure of the code you own inside that. Design sits one level lower, inside a single module.
The difference between system architecture and software architecture is mostly a question of ownership: the system level adds the CDN and the networks between services, while the software level stops at the code your team writes and maintains. The 42010 site draws a similar line, noting that software architecture “has often been focused on software components as elements and their interconnections”, while system architecture “emphasizes sub-system structures and relationships such as allocation.” On design, it contrasts the two: architecture “is outwardly focused on the system in its environment; whereas design is inwardly focused once the system boundaries are set.”
| Level | What it covers | An example decision for a small SaaS |
|---|---|---|
| System architecture | Everything that runs: hosting, database service, CDN, queues, third-party APIs, the networks between them | Run in one region on one managed Postgres database |
| Software architecture | The structure of the code you own | Keep all payment logic behind one module |
| Design | How one module is built inside | How the invoice total is computed |
For an app on managed services, the first two blur. Most of the software system architecture is other companies’ services, wired together by your own code, so I treat the levels as views of one description rather than two documents.
Why it matters for a small SaaS: four people will ask, and the code cannot answer
Sooner or later four people ask about the structure of a small SaaS, and each wants a different answer.
| Who asks | What they actually ask | Which view answers it |
|---|---|---|
| A new developer | Where do I start, and what must I not break? | The code view, then the runtime view |
| A buyer’s or investor’s technical reviewer | What is it built on, and what would it cost to change? | The runtime view and the decision inventory |
| An enterprise customer’s security team | Where does our data go, and who can reach it? | The trust view and the data view |
| The founder, six months later | Why did we do it this way? | The decision inventory |
A reviewer’s own list goes further; the questions a software architecture due diligence asks are set out separately, and the pack a reviewer receives is technical documentation for investors.
An AI-built app is a special case, and not because anyone made a mistake. It was generated feature by feature, so its structure is whatever the prompts added up to. Nobody sat down on a given day and decided it, which means nobody can explain it from memory either.
Every audited app is scored across 12 pillars, all 26 apps in those audits. Across the 21 third-party apps, maintainability ranked 10th of the 12, counting from the weakest, so nine pillars averaged lower. In my reading, a score like that draws no alarm next to weaker pillars, so the gap goes unnoticed until someone asks one of the questions above. As before, that ranking describes the apps I audited, not AI-built apps as a whole.
Without a written architecture, every question in the table is answered by reading code, and only by the one person who can. Where the structure has already decayed into shortcuts that now cost money to change is a separate subject: technical debt in an app you did not write.
How it works: the four views, the common styles, the trust view, and the write-up
Four parts follow: what to describe, how to name the style honestly, the security view, and how to write it all down for an app you did not design.
Software architecture design for a small SaaS: the 4 views
Software architecture design for a small SaaS is four views: the runtime view shows what runs where, the code view shows how the repository is organized, the data view shows what is stored and who owns it, and the trust view shows who can reach what. Each has one reader in mind and fits on a page.
Views are an old idea. The 42010 standard’s conceptual model says a view expresses a system’s architecture “from the perspective of one or more Stakeholders to address specific Concerns.” Philippe Kruchten’s 4+1 view model, published in IEEE Software in 1995, showed that a description can be organized around logical, process, development and physical views, with scenarios as a fifth. I trim that to four views that a team of five can keep current.
| View | The question it answers | What goes in it | Who reads it | Where its format is set |
|---|---|---|---|---|
| Runtime | What runs where, and what talks to what? | Front end, API or server functions, database, storage, auth, payments, email, the AI provider, background jobs, and the arrows between them | Everyone | The architecture diagram how-to |
| Code | How is the repository organized? | Modules, which module may call which, where business rules live, how to trace one feature from route to database | Developers | The documentation set |
| Data | What is stored, and who owns each row? | Entities, row ownership, which fields are personal data, where files live, what is backed up | Developers and reviewers | The documentation set |
| Trust | Who and what can reach each part? | Entry points, identities, boundaries, data classes, evidence | Security reviewers | The trust view section below |
Drawing the runtime view is its own job: how to create an architecture diagram. What each dependency’s record should hold, and the rest of the documentation set, is in how to write technical documentation for a vibe-coded app.
Some things are left out on purpose: deployment topology diagrams for an app that runs in a single region on managed services, UML class diagrams, and enterprise frameworks such as TOGAF and Zachman. The closest public method to the runtime and code views is the C4 model, which its site calls “an easy to learn, developer friendly approach to software architecture diagramming.”
Software architecture in software engineering: the styles, and which one you probably have
Software architecture in software engineering comes in styles rather than three fixed types; Microsoft’s catalog lists six. A small team meets five: layered, monolith or modular monolith, microservices, event-driven and serverless functions. In my reading, most AI-built apps are a three-tier app on managed services, and a modular monolith fits until a named constraint says otherwise.
Microsoft’s catalog of architecture styles defines a style as “a family of architectures that share specific characteristics.” The cost column below uses the catalog’s own words where it covers the style; two of the five are not in it, and those rows are my reading.
| Style | What it looks like | When it fits | The cost |
|---|---|---|---|
| Layered or N-tier | Presentation, business logic and data access layers; “layers manage dependencies by only calling into layers under them" | "Traditional business domain. Frequency of updates is low." | "the horizontal layering can make it difficult to introduce changes without affecting multiple parts of the application” |
| Monolith or modular monolith | One deployable app; the modular form splits it into modules with enforced boundaries | Not in the catalog; my reading: one small team, one deploy | Not in the catalog; my reading: boundaries hold only while someone enforces them |
| Microservices | Small autonomous services, each with its own data, calling each other through APIs | ”Complicated domain. Frequent updates." | "significant complexity in areas such as service discovery, data consistency, and distributed system management” |
| Event-driven | Producers publish events through a broker; consumers react to them | ”Internet of Things (IoT) and real-time systems." | "challenges around guaranteed delivery, event ordering, and eventual consistency” |
| Serverless functions | Individual functions the host runs on demand | Not in the catalog; my reading: occasional or spiky work beside a main app | Not in the catalog; my reading: logic spread across many functions is harder to trace |
I treat MVC and client-server as patterns inside these styles, although Roy Fielding’s REST dissertation calls client-server an architectural style. MVC splits one app’s code into model, view and controller. Client-server is the browser talking to a server, which every web app does. A pattern solves one recurring problem inside the code; a style shapes the whole system.
I’d expect a three-tier app on managed services to carry a few serverless functions as well, for webhooks or scheduled work. The constraint that justifies a split has to be specific, in my judgment: one part that must scale separately, or a team that can no longer share one deploy. Splitting into services early buys operational work the team cannot staff. No style is best in general, and the catalog itself advises: “Be practical. Sometimes it’s better to relax a constraint than to chase architectural purity.”
Cloud security architecture: the trust view a reviewer asks for
Cloud security architecture is the description of how a system on cloud services is protected, and for a small SaaS it has five elements: entry points, identities, trust boundaries, data classes and evidence. It starts from shared responsibility: the provider secures its platform, and you secure what you choose, configure and deploy on it.
Security architecture in cloud computing starts from that split. AWS’s shared responsibility model says “AWS is responsible for protecting the infrastructure that runs all of the services offered in the AWS Cloud”, while “Customer responsibility will be determined by the AWS Cloud services that a customer selects.” The split in detail, service by service, is part of a cloud application security assessment. The trust view is the part that is always yours.
| Element of the trust view | What to write down | The question it answers |
|---|---|---|
| Entry points | Every public URL, webhook and API route | Where can a request from outside get in? |
| Identities | Users, roles, service keys, and which key can bypass row-level rules (on Supabase, the secret keys and the legacy service_role key bypass Row Level Security) | Who or what is acting, and with how much power? |
| Trust boundaries | Browser to server, server to database, server to third parties | Where must a check happen before data crosses? |
| Data classes | What is personal, what is payment data, where each lives, how it is encrypted | What would a leak expose? |
| Evidence | What is logged, where, and for how long | How would you know afterwards what happened? |
The identities row is the one most worth getting right. Supabase’s API keys guide is plain about it: “A secret key bypasses every Row Level Security policy you have. Never put one in a browser, a shipped application, or source control.”
The diagram form is the runtime diagram again, with each trust boundary drawn as a dashed box and each arrow labeled with the identity it uses. That is the cloud security architecture diagram a reviewer can read without a meeting, because it answers who can reach what on one page.
Say an enterprise customer’s security team asks you for a diagram of where its data goes and who can reach it. You draw the runtime view and label each arrow with the identity it uses. One arrow stands out: a server function calls the database with the service role key, which bypasses row-level security, so that arrow reaches every customer’s rows, not only those of the customer the request is about. A trust view is a list of arrows and identities, and the one that crosses every tenant is the one to write down first. The labeled arrow is how you find that path before the reviewer does.
Readers who need the formal version can start with CISA’s cloud security technical reference architecture, Version 2, revision date June 21, 2022, a multi-agency effort with contributions from CISA, the United States Digital Service and FedRAMP, written “to guide agencies in a coordinated and deliberate way as they continue to adopt cloud technology.” CISA now files it as archived content that “may not reflect current policy or programs.” Where the server makes each decision, action by action, belongs in a per-action record: how to map trust boundaries in a vibe-coded app. Layered controls are defense in depth, and finding what can go wrong at each boundary is threat modeling a small web app. A trust view describes the system; it certifies nothing.
How to write yours down when you did not design it: found decisions and made decisions
An inherited small SaaS is written down by describing what is there before changing it: the four views, then the five decisions every app has already made (the database, the auth provider, tenant separation, file storage and background work), each marked found or made, dated, and with what reversing it would take.
My working rule is to describe first and change second. A decision you change before recording it is a decision nobody can review later.
| Decision | Found or made | Date | What reversing it would take |
|---|---|---|---|
| The database, and who hosts it | |||
| The auth provider | |||
| How tenants are separated | |||
| Where files live | |||
| What runs in the background |
Mark a decision “found” when it was already there when you arrived and “made” when you chose it yourself. Date it: the date you found it, or the date you made it. Then write one line on what reversing it would take, using the rewrite-or-afternoon test from the definition above. A found decision with no reason on record is normal in an inherited app; writing “found, reason unknown” is honest and still useful.
Keep this table and the four views in one file at the root of the repository, where the next developer and the next AI assistant will both see it. The decision-record format and the rest of the documentation set live in the documentation article; this table is the step before them, finding which decisions exist and whether they were found or made. Agreed quality targets belong in the same file, including an availability target if one was ever promised to a customer; knowing what SLAs are helps you word it.
Teams that outgrow one file can move to arc42, an open template licensed under CC BY-SA 4.0 whose 12 sections include a runtime view, a deployment view and one for architectural decisions.
How to check your own app
An architecture description is checked six ways: a stranger traces a feature from the README, the runtime view matches the deployed services, the data view matches the schema, every public route appears as an entry point, each of the five decisions is dated, and one decision’s reversal can be explained.
- 01 The stranger test. A developer who has never seen the repository follows the README from a clean checkout and traces one core feature through the documented modules. Pass: done without asking anyone, within the time you agreed beforehand. Fail: they had to ask, or ran out of time. Keep: their notes on where they got stuck.
- 02 Runtime view against the deployed environment. Open the hosting, database, DNS and billing dashboards. Pass: every service there is on the view, and nothing on the view has gone. Fail: a service in a dashboard that the view does not show. Keep: the list of differences.
- 03 Data view against the schema. Compare the entities on the view with the schema and migrations the app actually runs. Pass: every table that holds customer data is on the view with its owner. Fail: a table or bucket the view does not mention. Keep: the migration you compared against.
- 04 Entry points against the code. List every public route and webhook from the code itself. Pass: each one appears as an entry point in the trust view. Fail: a route found in code that the trust view lacks. Keep: the route list and the date it was made.
- 05 The decision inventory. Open the table of five decisions. Pass: each has found or made, a date and a reversal line. Fail: a blank cell. Keep: the file version you checked.
- 06 The change test. Pick one decision and write, in three sentences, what changing it would take. Pass: someone on the team can write it. Fail: nobody can, which means the description is not yet architecture. Keep: the three sentences.
For check 1, my working rule is about half a working day for a small app, agreed before the stranger starts. Evidence to keep across all six: the commit hash of the architecture file, the date of each comparison, and the list of differences found and fixed. Run the checks again after any change of provider.
Where the sprint fits
In the Production Hardening Sprint, deliverable 13.2, the system architecture diagram, shows the deployed components, data flows, authentication boundaries, and third-party integrations, and it is verified by comparing the diagram with the delivered environment and repository. Deliverable 4.13, the data model diagram, delivers a readable diagram of entities, relationships, and ownership boundaries for the data room, verified by comparing the diagram against the delivered schema and migrations. Deliverable 10.4, documented repository structure, organizes the codebase consistently and explains its layout in the README; it is verified by following the README from a clean checkout and tracing a core feature through its documented modules. Support after handover includes 30 calendar days of async questions about the handover and architecture. We refactor or replace components where the production work requires it; your app’s current framework and hosting setup are our starting point. Each deliverable and its verification line is in the published scope.
Common questions about architecture for small teams
What are the five pillars of software architecture?
The five pillars come from a cloud framework: Microsoft’s Azure Well-Architected Framework names reliability, security, cost optimization, operational excellence and performance efficiency. AWS’s Well-Architected Framework has six, adding sustainability. Both are lenses for reviewing a cloud workload rather than a definition of architecture.
What are the four types of cloud architecture?
The four types are the deployment models in NIST SP 800-145, The NIST Definition of Cloud Computing: private cloud, community cloud, public cloud and hybrid cloud. A small SaaS on a managed host runs on public cloud, which NIST describes as infrastructure “provisioned for open use by the general public.”
What does a software architect do?
A software architect makes and records the decisions that are expensive to reverse, keeps the views current, and says no to changes that would break them. In a team of five it is a hat, not a hire, worn by whoever can answer the change test for the app. An architect decides the structure and an engineer builds within it; in a small team, one person often does both.
Can AI replace system architect?
No, not the whole role. An assistant can draft diagrams and propose structures from a prompt, and assistants built many of the apps described here. What it does not hold is the business’s constraints and the accountability for a decision that is expensive to reverse.
Owning an app means being able to run it, change it and recover it without guessing. The sprint below leaves you with the runbooks and documentation to do that.
Built it with AI. Now it has to hold up for real customers.
The Production Hardening Sprint takes the app you already have and builds the production foundation underneath it. Authentication and access rules, payments that stay consistent, error handling, monitoring, backups, automated tests and a documented handover. Our engineers work inside your existing codebase for ten working days. All 123 deliverables are included, and you get the evidence for each one.
See the Production Hardening Sprint → 
$2,500 fixed price · 10 working days · One codebase