Guide

What Is Software Architecture? Decisions and a Worked Example

Use software architecture to choose system boundaries, test a design against real constraints, and explain why your team made the choice.

By the Space Office team · Published · Updated · 16 min read

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
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

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.

Give each important quality an observable result, a verification method, and an owner.
QualityScenario and expected responseEvidence to request
CorrectnessTwo 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.
AvailabilityThe 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.
AuthorizationA visitor requests another person’s booking reference. Protected details remain inaccessible.An approved test account tries allowed and denied requests at the API boundary.
RecoverabilityA 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.
ChangeabilityStaff 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.

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
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

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

Four cards show system context, running applications and stores, the module rule, and a failure scenario
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

These choices can be combined. Compare the specific structure that each candidate would introduce.
Style or choiceGood starting conditionTrade-off to check
Layered modular monolithOne 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 workerFollow-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 interactionSeveral consumers can react to business facts with some delay.Handle duplicate and delayed events, and identify the source of truth.
Independently deployed servicesA stable business boundary has an owner and a measured need for separate releases or scaling.Budget for network failure, contracts, monitoring, and service recovery.

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 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
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

Use the record as a decision someone else can verify and revisit.
FieldIllustrative room-booking ADR
Status and ownerProposed. The human maintainer owns acceptance and records the decision date after review.
ContextThe team must prevent two active reservations for one room and hour. A slow provider must leave the website usable.
DecisionUse one modular web application and transactional data store for booking. Handle email asynchronously through a worker.
AlternativesCompare sending email on the request path and deploying reservation and delivery as separate services.
ConsequencesThe team keeps one reservation writer and takes on a worker queue, retry policy, and an alert for delayed work.
Evidence requiredConcurrent booking test, slow-provider drill, role checks, and a timed staging restore with the result attached.
Revisit triggerReview if the release history shows notification-only changes repeatedly delaying booking releases, or if the queue misses its agreed target after worker tuning.
Four cards show evidence, choice, consequences, and the condition for revisiting an architecture decision
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 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, 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.

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.

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.