# What Is Software Architecture? Decisions and a Worked Example

> This is the Markdown version of this article, built for AI assistants and agents. The human page is at https://www.spaceoffice.ai/blog/software-architecture.

By the Space Office team · Published 2026-11-09 · Updated 2026-11-09 · 16 min read · Category: Guide

Software architecture is the set of consequential decisions about how a software system is structured, how its parts interact, and how it meets requirements such as reliability and security. A useful first design identifies the system boundary, names a few measurable outcomes, and records why the team chose a particular structure. For a scoped Space Office review, Lithium can map the implementation, Carbon can draft acceptance tests, and Hydrogen reviews the trade-offs before a human maintainer decides.

![A Space Office robot and human hand arranging a booking application, reservation layer, and data store to illustrate software architecture](https://www.spaceoffice.ai/blog/software-architecture/cover-v1.webp)

_The arrangement makes application responsibilities and the connection to the data store visible before implementation._

## Key takeaways

- Start with a user action, a system boundary, and the business rules a design must protect.
- Make qualities like reliability measurable by describing a specific failure and the expected response.
- Compare designs that the team could actually build and operate. Consider their costs across releases and incidents.
- Use a context diagram to align on who uses the system and what it depends on. Record significant choices separately.
- Keep a named owner, test evidence, and a trigger for revisiting each architectural decision.

## What decisions belong to software architecture?

Architecture deals with choices that affect multiple parts of the system or shape how it behaves under change and failure. A decision about which component owns reservation state determines where the system enforces the rule against overlapping bookings. A decision about who may read an approval changes the user interface, API authorization, and tests together. The Software Engineering Institute describes architecture in terms of overall structure, behavior, and qualities that matter to stakeholders. [Carnegie Mellon Software Engineering Institute on software architecture](https://www.sei.cmu.edu/software-architecture/)

A useful boundary has an owner, responsibility, and interface. In a room-booking application, a module might decide whether a booking request is valid while another handles staff-facing reports. The staff report should use a supported query or view. Letting reports write directly to the booking table makes the boundary harder to enforce. If a report needs a new field, change the interface deliberately and update the test that defines what it returns.

System behavior deserves as much attention as the component list. Two designs can show the same boxes on a diagram and respond very differently to an unavailable email provider. In one design the user receives an error and may try again. In another, the reservation persists and the website shows its confirmation while delivery waits. Write down the expected behavior for the successful path and at least one failure. It will give reviewers something concrete to check.

Technology choices sometimes have architectural consequences. A new color token typically affects presentation. Replacing a transactional data store can change concurrency, recovery, and the rules the application can enforce. Document choices that change how several parts work together, affect a critical quality, or are expensive to reverse. Keep ordinary implementation details close to the code.

## Turn requirements into observable outcomes

Begin with one critical journey. In this fictional community center, a visitor asks to book one room for one hourly slot. A staff member can cancel a booking. Email is a courtesy, and the website or an authorized staff lookup remains the record of whether the booking exists. The worked example uses fixed slots to make the concurrency rule easy to inspect. A system with arbitrary start and end times would need to detect overlapping intervals rather than merely matching start times.

| Quality | Scenario and expected response | Evidence to request |
| --- | --- | --- |
| Correctness | Two visitors request the same room and slot at the same time. One gets the reservation and the other sees the slot is taken. | A concurrent test checks both responses and the committed records. |
| Availability | The email provider times out after a successful booking. The confirmation still appears on the site. | The booking page shows the saved reference and the email work remains visible to staff with appropriate access. |
| Authorization | A visitor requests another person’s booking reference. Protected details remain inaccessible. | An approved test account tries allowed and denied requests at the API boundary. |
| Recoverability | A staging database is unavailable and must be restored from a backup. The owner can verify the expected data and estimate any loss. | A restore drill records elapsed time, the recovery point, and unresolved issues. |
| Changeability | Staff needs a new booking status. Reservation rules and tests can change in one named module. | A reviewer checks dependent interfaces and confirms the change stays inside the agreed boundary where possible. |

Give each important quality an observable result, a verification method, and an owner.

Separate a target from a measured result. For example, the team could propose restoring the staging database within 60 minutes, with at most 15 minutes of data loss. The first number is the acceptable restoration time. The second describes how far back the available recovery point can be. Before accepting these targets, determine whether the backup configuration supports them and run a timed restore with representative data. An untested setting is an assumption to keep visible.

Suppose a drill begins with an outage at 10:00 and staff can verify the restored application at 10:42. The recovery time is 42 minutes. If the restored state contains records only through 09:40, the 20-minute recovery point misses the 15-minute target. Record each outcome separately and check that bookings and cancellations agree in the restored data before declaring the application usable.

Record constraints that affect the design. The center has one small development team and a limited maintenance window. Room schedules are sensitive enough to restrict staff views by role. There is no need to launch with different teams deploying individual features independently. When two goals conflict, ask the person accountable for the outcome to set the priority. For example, a slower booking response can be acceptable if it protects the reservation invariant under peak contention.

![A robot places a visitor token, staff badge, and envelope provider around the booking portal](https://www.spaceoffice.ai/blog/software-architecture/context-workbench-v1.webp)

_A context sketch gives the visitor, staff member, and external email provider distinct relationships to the portal._

## Draw the boundary and pick a useful level of detail

Start with a context view. Put the booking portal inside a single boundary. Outside it, show the visitor, the staff member, and the external email provider. Label each arrow with a purpose. The visitor requests a slot and reads a confirmation. Staff reviews or cancels reservations. The portal requests email delivery. This view helps a nontechnical reviewer spot a missing participant or an inaccurate claim of ownership. [C4 system context diagrams](https://c4model.com/diagrams/system-context)

Then draw a container view if the team needs to understand how the responsibilities run. In the C4 vocabulary, a container is a running application or a data store. The term can describe a web application, a worker, or a database regardless of the packaging tool. A module inside a single application is a different level of detail. Add a separate note or a closer component view if someone needs to see that module’s dependency rules. [C4 container diagrams](https://c4model.com/diagrams/container)

![Four cards show system context, running applications and stores, the module rule, and a failure scenario](https://www.spaceoffice.ai/blog/software-architecture/boundary-views-v1.webp)
Phone layout: ![Four cards show system context, running applications and stores, the module rule, and a failure scenario](https://www.spaceoffice.ai/blog/software-architecture/boundary-views-mobile-v1.webp)

_Each view answers a different question. Include the view your reviewer can use to make a decision._

Label diagrams as current or proposed and name the version that the sketch describes. Keep secrets, production hostnames, and identifiable booking data out of shareable diagrams. For a sequence with a timing risk, a short numbered interaction list can work better than another static picture. Walk through the reservation commit, response to the browser, and subsequent notification. Ask a reviewer to point to the step at which the user first has a confirmed reservation.

## Compare designs the team can operate

| Style or choice | Good starting condition | Trade-off to check |
| --- | --- | --- |
| Layered modular monolith | One team deploys a web application and needs transactional booking rules. | Enforce dependency boundaries so an internal feature cannot change shared state from anywhere. |
| Web app with a worker | Follow-up jobs are slow or retry independently of the visitor’s request. | Watch queue age and define what happens to pending work when a worker is replaced. |
| Event-driven interaction | Several consumers can react to business facts with some delay. | Handle duplicate and delayed events, and identify the source of truth. |
| Independently deployed services | A stable business boundary has an owner and a measured need for separate releases or scaling. | Budget for network failure, contracts, monitoring, and service recovery. |

These choices can be combined. Compare the specific structure that each candidate would introduce.

The community center can begin with a modular web application and one transactional data store. The reservation module owns availability and conflicts. A uniqueness constraint for each active room and slot, or a separate active-occupancy record with that key, makes concurrent requests compete at the data layer. A cancellation releases occupancy in the same transaction that records the canceled state. Keeping an audit record is a separate requirement from keeping an active slot claimed.

The notification worker reads committed work and handles provider retries. That worker can run from the same application release with a separate process, while reservations remain the only owner of slot occupancy. This adds an operational responsibility without requiring a collection of independently deployed business services. The design remains open to a future [microservices extraction](/blog/microservices) if a specific capability needs a different release or support boundary.

To compare the alternatives, make a small implementation spike around the riskiest assumption. In this case, run two concurrent requests for one slot using a disposable test database. Inspect the result of both requests and the saved state. Add a simulated email timeout and check that the browser still shows the reference. A test that always submits requests sequentially will miss the contention the design was meant to handle.

![Human maintainer and robot compare grouped components with separately deployed compartments](https://www.spaceoffice.ai/blog/software-architecture/decision-review-v1.webp)

_The review compares how each candidate handles the same reservation rule and how much it asks the team to operate._

## Write and review an architecture decision record

An architecture decision record, or ADR, captures a consequential choice, the context that led to it, and its effects. Keep the record with the design so a maintainer can find it when code or constraints change. Use a status such as proposed, accepted, or superseded. When the team revises an accepted decision, link the old record to its replacement so a reader can follow the reasoning over time. [AWS guidance on architectural decision records](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/faq.html)

| Field | Illustrative room-booking ADR |
| --- | --- |
| Status and owner | Proposed. The human maintainer owns acceptance and records the decision date after review. |
| Context | The team must prevent two active reservations for one room and hour. A slow provider must leave the website usable. |
| Decision | Use one modular web application and transactional data store for booking. Handle email asynchronously through a worker. |
| Alternatives | Compare sending email on the request path and deploying reservation and delivery as separate services. |
| Consequences | The team keeps one reservation writer and takes on a worker queue, retry policy, and an alert for delayed work. |
| Evidence required | Concurrent booking test, slow-provider drill, role checks, and a timed staging restore with the result attached. |
| Revisit trigger | Review if the release history shows notification-only changes repeatedly delaying booking releases, or if the queue misses its agreed target after worker tuning. |

Use the record as a decision someone else can verify and revisit.

![Four cards show evidence, choice, consequences, and the condition for revisiting an architecture decision](https://www.spaceoffice.ai/blog/software-architecture/decision-record-map-v1.webp)
Phone layout: ![Four cards show evidence, choice, consequences, and the condition for revisiting an architecture decision](https://www.spaceoffice.ai/blog/software-architecture/decision-record-map-mobile-v1.webp)

_A short record is useful when the next maintainer can see what would change the decision._

Ask a reviewer to challenge the most fragile assumption. For example, a proposal may assume that the reporting user can read only aggregate room occupancy, while a prototype exposes individual booking names. Record that gap as a required fix with an owner. If the review has incomplete evidence, keep the record proposed and specify the missing test. A diagram and a signed decision can explain intent. The observed behavior still needs verification.

## Run a scoped design review with Space Office

Fill the [software architecture decision worksheet](/blog/software-architecture/decision-worksheet.txt) with the user journey, code area, data ownership, alternatives, and acceptance evidence. Supply a sanitized context sketch, approved interface samples, and any constraints the team has already agreed to. A bounded first task is a proposed ADR, a dependency sketch, and a staging test plan for one decision. Keep customer records and unrelated repository areas out of the brief.

In the [Space Office workflow](/how-it-works), Hydrogen can route the scoped work to Lithium, the Full Stack Developer, and Carbon, the Senior QA Engineer and Test Strategist. Lithium can map how the API and data layer enforce the booking rule and identify feasible design options. Carbon can turn the quality scenarios into reproducible tests and record failures from an authorized environment. Hydrogen reviews the artifacts together and calls out assumptions that still need evidence.

The human maintainer controls the scope, supplies any necessary repository or staging access, and decides whether to accept the ADR or request a different design. A staging result applies to the environment and data tested. Release and migration approvals remain separate human decisions. For role responsibilities, see the [Space Office specialist roster](/agents).

## Choose a design you can explain and test

Good software architecture starts with the outcome a person depends on and the rule the system must enforce. Draw enough of the system to name the owner, compare a small number of options, and write a test that could reveal a bad assumption. Record the choice and what would justify revisiting it. In the community center example, the useful result is a dependable booking with visible confirmation, even when follow-up email is delayed. Keep that outcome in view when the design evolves.

## Sources and review notes

Reviewed against the linked primary sources on the checked dates. Search features and citations are selected by their respective platforms; no placement is guaranteed.

- [Carnegie Mellon Software Engineering Institute on software architecture](https://www.sei.cmu.edu/software-architecture/) — checked 2026-11-09
- [C4 system context diagrams](https://c4model.com/diagrams/system-context) — checked 2026-11-09
- [C4 container diagrams](https://c4model.com/diagrams/container) — checked 2026-11-09
- [AWS guidance on architectural decision records](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/faq.html) — checked 2026-11-09

## Frequently asked questions

### What is software architecture?

Software architecture is the set of significant decisions that shape a system’s structure, interactions, and behavior. It includes component boundaries, data ownership, important interfaces, and how the design addresses qualities such as security and recovery. A useful description explains the reasons for those decisions and points to evidence.

### What is an example of software architecture?

A room-booking application might use one deployable web application with separate internal reservation and staff modules, a transactional data store, and a worker for notifications. The reservation module owns the booking rule, the database resolves competing writes, and email delivery can recover separately after the visitor receives a confirmation.

### How does architecture relate to software design?

Software design covers decisions at many levels, from a system boundary to an individual function. Architecture is the subset of choices whose effects reach across the system or are expensive to reverse. A new form layout is usually local. Changing which component owns all reservation writes affects several interfaces and failure paths.

### What should a software architecture diagram show?

Choose one audience and one view. A context diagram shows the system, its users, and external dependencies. A container diagram shows the applications and data stores that make up the system. Label arrows with their purpose and use a short sequence or scenario when timing and failure behavior matter.

### When should a team update an architecture decision record?

Revisit a record when evidence changes, a constraint no longer holds, or the documented review trigger occurs. Record which observations changed the decision and keep a link to the superseded record. Small implementation adjustments can stay in the code unless they materially affect the decision or its consequences.

---

Related: [Plan one independently deployed service](https://www.spaceoffice.ai/blog/microservices) · [Define the contract between components](https://www.spaceoffice.ai/blog/api) · [Understand hosting and operating responsibilities](https://www.spaceoffice.ai/blog/cloud-computing) · [Scope an engineering handoff for a small team](https://www.spaceoffice.ai/blog/ai-dev-team-for-solo-founders)

---

Space Office — hire 24 live AI specialists coordinated by Hydrogen, an always-on AI project manager that reviews every output before delivery. The $60/month base includes Hydrogen and two specialists; additional specialists, dedicated compute, and AI usage cost extra. Learn more: https://www.spaceoffice.ai
