Skip to content
Software Architecture Guide

Joining a project without architecture documentation

Ordered steps to recover missing information in an existing project

Section titled “Ordered steps to recover missing information in an existing project”

Every system has an architecture, even if nobody planned or wrote it down. The code shows what the system does, but not why it was built that way (Motivation for Architecture Documentation, Implicit Architecture). Old documents may be wrong too. When you review a legacy system, recover its real architecture first and do not simply trust the existing documents (ATAM Application Phases).

The steps below go from cheap and useful to expensive and detailed. Write down only what a named reader will use, and describe each thing once (Guidelines for Documentation). The template is arc42, which gives each kind of information a fixed place.

Running example. ClinicBook is an online booking system for 40 small medical practices. Patients book, move and cancel appointments on the web and in a mobile app. Practice staff manage calendars. ClinicBook integrates with each practice’s own practice-management software, sends reminders by SMS and e-mail, and protects health data. The team is small and the launch date is fixed.

Step 1: Write down the purpose, the top quality goals and the stakeholders

Section titled “Step 1: Write down the purpose, the top quality goals and the stakeholders”

Write first: a short statement of what the system must achieve, the three to five most important quality goals, and a table of stakeholders. A quality goal is a quality, such as speed or security, that matters most to the main stakeholders.

Goes into: arc42 section 1, Introduction and Goals (arc42 Introduction and Goals).

  • Keep the requirements overview short. Link to existing requirements documents instead of copying them.
  • List at most five quality goals, and give each a brief scenario, not just a keyword (Quality Attribute Prioritization).
  • Put roles, names and expectations in the stakeholder table. Ask who gains or loses, who decides and who controls resources (Stakeholder Identification).
  • If you want a quick one-page start, an Architecture Canvas captures the essentials, including the top three quality goals.
  • Leave detailed quality requirements for arc42 section 10 (arc42 Quality Requirements).

ClinicBook: The top goals could be:

  1. Confidentiality of health data.
  2. Availability during morning peaks.
  3. Interoperability with the practices’ existing software.

A scenario for goal 2 could read: “On a weekday morning at peak load, a patient books an appointment and gets a confirmation within X seconds.” Confirm the value X with stakeholders. Do not invent it. The small team and the fixed launch date are not quality goals. They belong in step 2.

Step 2: Write down the constraints

Section titled “Step 2: Write down the constraints”

Write first: every requirement that limits how you may design and build the system. Note for each one who wants it, why, and whether it can be negotiated.

Goes into: arc42 section 2, Constraints (arc42 Constraints, Architectural Constraint).

  • Keep all constraints in one place. This shows where the team is free to choose and where it must comply.
  • Group a long list into technical, organizational and conventions. Budget, time and processes are organizational constraints.
  • Write down the consequences of each constraint, such as extra cost or effort.
  • Separate constraints, which you must deal with, from forces, which you weigh against each other (Architectural Force).

ClinicBook: The fixed launch date is an organizational constraint. The need to work with several vendors’ software is a technical constraint. Ask who set each one and whether anyone can negotiate it.

Step 3: Draw the system as a black box with its neighbors

Section titled “Step 3: Draw the system as a black box with its neighbors”

Write first: a context diagram with the system as one box, plus a table of its communication partners. A black box shows what a part does and hides how it works inside.

Goes into: arc42 section 3, Context and Scope (arc42 Context and Scope, Context View).

ClinicBook: The partners are patients, practice staff, the practice-management systems of the different vendors, and the services that send SMS and e-mail. Each gets one row in the table. For example, the reminder flow goes from ClinicBook to the SMS channel, and a delivery status may come back. If the status does come back, draw that arrow too.

Step 4: Recover the top level of the building blocks

Section titled “Step 4: Recover the top level of the building blocks”

Write first: level 1 of the building block view. This is a white box of the whole system with its main parts as black boxes. A white box shows what is inside a part.

Goes into: arc42 section 5, Building Block View (Component View).

ClinicBook: Level 1 might show a web app, a mobile app, a booking part, a calendar part, a reminder part, one adapter per vendor, and a database. Refine the vendor adapters first. They are the most volatile and risky part of the system.

Step 5: Write down the important decisions and their reasons

Section titled “Step 5: Write down the important decisions and their reasons”

Write first: the few decisions that are important, expensive, large-scale or risky. For each, record the choice, the alternatives and the reason.

Goes into: arc42 section 9, Architecture Decisions (arc42 Architecture Decisions). The most fundamental decisions are short entries in section 4. Section 9 points back to them and does not repeat them.

ClinicBook: Start with how ClinicBook exchanges data with each vendor’s software. Name the style in use: file transfer, shared database, remote procedure call or messaging. Then record the alternatives and the reason for the choice (Integration Style).

Step 6: Write down the risks and the technical debt

Section titled “Step 6: Write down the risks and the technical debt”

Write first: a list of known problems, ordered by priority, with a suggested mitigation for each. Technical debt means shortcuts in design or code that make later change more costly (Technical Debt).

Goes into: arc42 section 11, Risks and Technical Debts.

  • Record gaps between the intended and the implemented architecture as risks or technical debt (Implicit Architecture).
  • Rate each risk by probability and impact, and plan the mitigation for the high ones (Risk Storming).
  • Cover debt in architecture and design, not only in code.
  • Mark each deliberate debt as knowingly accepted, with a repayment plan.

ClinicBook: Possible entries are slow or failing calls to a vendor’s system during the morning peak (Connectors and Distribution), and unclear ownership of an adapter. Rate each one and assign a mitigation.

After the first pass

Section titled “After the first pass”

Do not try to finish everything at once. Add detail only where readers ask for it. Keep the text under version control next to the code (Documentation as Code), and name one person responsible for its quality (Guidelines for Documentation). If you later want to test whether the recovered architecture meets its goals, a review such as Lightweight ATAM can use these sections as input.