Uncia
FR / EN Demo

Glossary

Architecture document

An architecture document describes how an IT solution is built and hosted: components, servers, network, data flows, security and operations. It is written during the project, approved before go-live, and then used as the reference by the people who run, audit or change the solution.

Updated

What is an architecture document?

An architecture document records what was designed for a given solution, where it runs and how its parts talk to each other. Depending on the company it is called a technical architecture document, a solution architecture document or a solution design. French IT departments call it a DAT (dossier d'architecture technique), and you will meet that acronym in any project with a French integrator. The scope is always bounded: one application, or one piece of shared infrastructure such as a virtualization platform, a directory service or a link between two sites.

No standard dictates its outline. Every IT department has a template, inherited from an integrator or grown over successive projects. Its job is more stable than its outline. Before go-live, the document exists to get design choices approved: why two database nodes and not three, why this flow crosses the DMZ. After go-live, it is the memory of the project for people who were not part of it.

That double life explains most of its flaws. It is written to convince a review board, then read years later by an operations engineer or an auditor who expects a description of the current state. In between, the project closed and nobody reopened the file.

What does a technical architecture document contain?

Most architecture document templates follow the same order. The first section sets the context: the need, the scope, the assumptions and the non-functional requirements (expected availability, volumes, recovery time and recovery point objectives). It ages slowly, and the rest of the document is judged against it.

The application section lists the components of the solution, their versions, their dependencies and their exchanges with other applications. The infrastructure section covers servers and virtual machines with their sizing, operating systems, middleware, databases, storage and environments (production, staging, test). For cloud workloads, the same section names the accounts or subscriptions, the regions and the managed services in use.

The network section gives zones, VLANs, addressing, load balancers and the flow matrix: who talks to whom, on which port, in which direction. The security section covers authentication, service accounts, encryption and logging. The last sections deal with resilience (backup, recovery, failover) and with what operations needs to know: monitoring, scheduling, and pointers to the runbook.

A good document also records the options that were rejected and why. No inventory will ever reconstruct that part.

For a detailed outline with a commented example, see how to structure an architecture document. A commented architecture document template in Word format is available to download: twelve sections, guidance under each heading and ten checks to run before sign-off.

HLD vs LLD: what is the difference, and where does the runbook fit?

The high-level design (HLD) sets out the overall architecture: building blocks, zones and principles, with no IP address and no server name. It can be read in half an hour and presented to a review board. The low-level design (LLD) goes down to the level where someone can install: host names, addressing, VLAN numbers, cluster settings, firewall rules.

A document called "architecture document" may be one, the other or both. Some organizations keep a general and a detailed version, which amounts to the HLD and LLD pair. Others have a single document, and installation detail ends up in a build document or stays in tickets. Faced with an unfamiliar document, ask what level of detail it holds and who it was written for. Its title tells you little.

The runbook, or operations manual, answers another question. The architecture document says how the solution is built. The runbook says how to run it: start and stop sequences, backups, monitoring, what to do during an incident, on-call contacts. It is written for the operations team and changes at the pace of operations.

The two should reference each other without copying each other. Keep procedures in the runbook and the description of the architecture in the architecture document, with a pointer from one to the other.

Who writes and who approves an architecture document?

The author is usually the technical architect or solution architect of the project, sometimes the integrator or the vendor when a third party delivers the solution. The author does not write alone. The network team supplies addressing and flows, the systems team supplies sizing, the security officer supplies security requirements, and operations supplies its constraints for monitoring and backup.

Approval goes through an architecture review board, whatever its local name. Enterprise architecture, security and operations sit on it, sometimes with the business owner of the application. Each signs off its own part: security approves flows and exposure, operations confirms the solution can be run. No approved document, no go-live. That gate is why the document exists at all.

Nothing comparable ensures it stays current. The project is closed, the architect has moved to another subject, and the engineer who moves a virtual machine or opens a flow has neither the source file nor the mandate to edit it. Naming an owner for the document after go-live, the same way an application has an owner, costs little and removes a good part of the problem.

Why does an architecture document go stale?

An architecture document is accurate on the day it is approved. After that, the infrastructure moves without it. A virtual machine changes host during maintenance. An operating system upgrade is postponed, and the text keeps announcing a version that was never installed, or one that is no longer supported. A flow is opened on the firewall through an urgent ticket. A satellite application is decommissioned and stays on the diagram.

The document also contradicts itself. The diagram was carried over from an earlier version, the server table was updated, the prose was not. Two pages of the same document then give two different hosts for the same database.

The cost shows up later. A hypervisor migration team builds its waves from the document and finds, midway, dependencies the document does not know about. An auditor notes a gap between the documented flow matrix and the rules in place. Either way, the maintenance that was skipped is paid back in days of checking. The article four checks to know whether an architecture document still tells the truth walks through these drifts on an example.

How do you check an architecture document against reality?

Checking the document means comparing its statements with the sources that describe what runs.

The manual method works and needs no tooling. Extract the list of servers, versions and flows from the document, then compare it with a hypervisor export (RVTools on VMware, for instance), the CMDB extract and the firewall rules. Someone who knows the scope can do it with a spreadsheet. The limits are well known: the work has to be redone at every review, and it depends on one person.

A CMDB helps when it is fed by discovery and when applications are linked to their servers in it. It does not read the document, so the comparison stays manual. An enterprise architecture tool keeps models consistent with each other and versions them, which removes internal contradictions. It describes what architects entered, not what operations changed since.

The remaining approach starts from the sources: read the exports and the cloud environments, read the document, and compare element by element. It requires a tool, and it only judges what the sources contain. A design rationale or a service commitment cannot be checked against any export.

What Uncia brings, and what it does not do

Uncia reads the sources of your IT estate in read-only mode, through connectors (clouds, hypervisors, CMDB, firewalls, scanners) and through files you drop in (exports such as RVTools, flow matrices, architecture documents), and reconciles them in a knowledge base. You drop in an architecture document: its diagrams and tables are read as they are, its prose by a language model that can run on your premises. Each element of the document is then compared with the sources, and the gaps are shown with the source of every value: a host that changed, an operating system version past its date, an application missing from the exports, a diagram and a text that disagree. Uncia can also write the architecture document from the map, following your template, and produce an up-to-date version when the estate changes. The feature is described on the page architecture documents checked against the sources.

The limits are worth knowing. Uncia changes nothing, in your systems or in the document you drop in: the language model proposes, a person decides, one value at a time. It only rules on what your sources describe, and whatever no source confirms is reported as undetermined. The comparison reflects the latest collection: it is updated at each collection, not in between.

Frequently asked questions

Is a solution architecture document the same as a technical architecture document?

Often, yes. Usage varies by company: some use solution architecture document for the application-level design and technical architecture document for infrastructure, others use one name for a single document covering both. Check the level of detail and the intended reader.

Is there a standard architecture document template?

No standard imposes one. Templates circulate between integrators and IT departments, and most follow the same order: context and requirements, application architecture, infrastructure, network and flows, security, resilience, operations. A short template that every project completes beats a complete one nobody finishes.

Do I need both an HLD and an LLD?

It depends on how far your architecture document goes. If it stops at principles and building blocks, it plays the role of the HLD and you need a detailed document to install from. If it goes down to host names and firewall rules, it covers the LLD. What matters is that a reader knows which document holds an IP address.

What is the difference between an architecture document and a runbook?

The architecture document describes how the solution is built and why. The runbook describes how to operate it day to day: start, stop, backups, monitoring, incident handling. The first is written for the review board, the second for the operations team.

How often should an architecture document be reviewed?

At every significant change to the solution, and at least before any project that relies on it: a migration, an audit, a handover to a new team. A document that has not been reviewed since go-live should be treated as an assumption to verify.

Every week, an article to know your IT estate better

Architecture documents, end of support, NIS2, CMDB, migrations: methods you can apply with or without Uncia.

Get a call from our team

Thirty minutes with a member of our team, remote or on site: Uncia on a demonstration instance, then on part of your own estate if you wish. We reply within 48 hours.

Request received

Thank you. A member of our team will reply within 48 hours to set a date.