{"canonical_url":"https://engineer.company/glossary/architecture/","content_markdown":"# architecture\n\n## What it is\n\nArchitecture, in software often called software architecture or system architecture, is the set of\nfundamental concepts and properties a system has in its environment, carried by its elements, the\nrelationships between them and the principles that govern how it is designed and how it changes.\nThat wording follows the definition in NIST SP 800-160 Volume 1 Revision 1, Engineering Trustworthy\nSecure Systems, published in November 2022.\n\nEach part of the definition does work. The elements are the pieces: services, databases, queues, the\nfrontend, the modules inside them. The relationships are how those pieces depend on one another and\nwhat passes between them. The principles are the rules that decide where new work goes, and they\nkeep the elements and relationships from drifting as the system grows. “In its environment” makes\nthe users, the neighbouring systems and the constraints part of the architecture, and “evolution”\nmeans a description that is true only on the day it was drawn is incomplete.\n\nNot every design choice is architectural. The group that maintains the Architectural Decision Record\n(ADR) format calls an architectural decision “a justified design choice that addresses a functional\nor non-functional requirement that is architecturally significant”, and a requirement is significant\nwhen its effect on the system's architecture and quality can be measured. The arc42 template is\nblunter: its decisions section is for “important, expensive, risky or contentious decisions”.\n\nBecause no single drawing shows all of it, architecture is described in views. The C4 model, created\nby Simon Brown, offers diagrams that work like maps you zoom in and out of: a system context diagram\nshowing how the system sits among its users and the systems around it, a container diagram showing\nthe applications and data stores inside it, a component diagram for one container and, where it\nhelps, a code diagram. arc42 arranges the written description in twelve sections, from goals and\nconstraints to decisions, risks and technical debt.\n\n## Why it matters\n\nThe decision architecture puts in front of a team is less which structure to choose than which\nchoices to make now, deliberately and on the record, and which to leave open.\n\nSettle a structural question early and you pay before you know much: the choice is made with the\nleast information the project will ever have, and it slows the first weeks. Leave it open and the\nstructure gets settled anyway, one convenient change at a time, by whoever touched the code last.\nThe way out is to separate two kinds of choice. A few are expensive to change once code depends on\nthem: how the system divides into parts, which part owns the business rules, how data is reached,\nwhat bar every change must clear. Those deserve to be made early and on purpose. Most of the rest\nare cheap to revisit and can wait until the code shows what it needs.\n\nRecording is the second half of the decision, and it is where the reasoning survives. An ADR\ncaptures one decision with its rationale, its trade-offs and its consequences, and the collection of\na project's ADRs forms its decision log. The ADR site credits Michael Nygard's 2011 post\n“Documenting Architecture Decisions” with popularising the idea. The cost is a page of writing per\ndecision. The return is that a later reader can tell a deliberate trade from an accident, and can\ncheck whether the reason still holds.\n\nQuality goals decide between structures that would all work. arc42 asks for the top three, at most\nfive, quality goals for the architecture, the ones the major stakeholders care about most, and warns\nthat they are distinct from the project's goals. Two designs with the same features can differ\ncompletely in how they fail, scale or change, and only the quality goals say which difference\ncounts.\n\n## What it looks like in practice\n\nThe platform's repository opened on 25 November 2025 with nothing in it, and the page on its\n[founding decisions](/portfolio/set-the-platforms-founding-technical-decisions/) argues\nthat such choices are “cheap to make on day three and close to impossible to reverse by month six”.\nTwo of the three made then shaped the structure. The stack was layered so that each part has one\njob: a Next.js frontend, a Go API that validates and forwards, and a PostgreSQL function layer that\nowns the business rules. Data access went behind stored functions from the start, because\nretrofitting it later “would have meant rewriting every handler”. Nine months and several thousand\ncommits later, the page reports, the layers have not blurred and no handler talks to a table\ndirectly. Its test for a founding decision is not whether it sounded right but whether it survived\nthe volume of work that came after.\n\nStructure left to chance gets set by accident, as the page on\n[GIS map development](/portfolio/directed-full-stack-gis-map-development/)\nshows. The map had grown up in pieces: spatial data in PostgreSQL, drawing in Mapbox, ReactJS on the\nfront and NodeJS behind. Each part worked on its own; they “just hadn't been built to fit together”.\nThe role covered the full-stack development and the technical direction, and the architecture was\nset first. After that, responsibilities “kept getting moved back to the layer they belonged in\nwhenever one started leaking into the next”, and much of the work was “catching the small\ninconsistencies before they hardened into architecture”.\n\nThe page on the [container plane](/portfolio/ran-containers-on-podman-and-quadlet/)\ntreats the written reason as the real result. The industry-default container engine publishes\ncontainer ports above the host firewall's rules, so the plane is a daemonless engine driving units\ngenerated by the operating system's own supervisor, with no published ports at all. One trade is\nrecorded as such: units run at the system level rather than rootless, which keeps the automation\nsimple at the cost of the stricter isolation rootless would give, and the note says which way to\nmove if container escape ever matters more. That is what an ADR holds: a decision with its\nrationale, its trade-offs and its consequences. The page rates writing the choice down with its\nreason above the choice itself, since “the next person will be told to use the default by every\narticle they read”.\n\n## Where it goes wrong\n\n**A careful newcomer reverses a decision that was deliberate.** The reason lived only in someone's\nhead, so the choice looks like a mistake, and the default every tutorial recommends looks like the\nfix. Write an ADR for each decision that is expensive to reverse: the context, the options weighed,\nthe one chosen, its consequences and what would make it worth revisiting. Keep the records beside\nthe code, so a change to one is reviewed with the other.\n\n**Business rules show up in three layers at once.** Each change put its logic wherever it was\nconvenient that afternoon, until the same rule was checked in the frontend, the API and the\ndatabase, a little differently in each. Name what each layer owns, write it down, and move a\nresponsibility back as soon as it leaks, while the stray copy is still small. Where the platform\nallows, enforce the boundary too, for example by letting the API call database functions while\nwithholding rights on the tables.\n\n**A rule introduced in month six turns into a cleanup project.** The decision everything depends on\nwas left open, and every commit since assumed whatever happened to be true. Decide the few expensive\nthings first and leave the rest open on purpose. Say so in the decision log, so an open question is\nvisibly open rather than quietly answered by the next change.\n\n**The architecture diagram explains nothing to anyone.** One drawing mixes users, services, classes\nand tables, and the lines between the boxes carry either no label or the word “uses”. Draw one\ndiagram per level of zoom, as C4 does, and label every line with the direction and intent of the\nrelationship; between containers, name the technology or protocol too. C4's notation guidance asks\nfor exactly that, and advises against single-word labels such as “Uses”.\n\n## Further reading\n\n- [architecture, NIST CSRC Glossary](https://csrc.nist.gov/glossary/term/architecture) — the\n  definition used above, beside the FIPS and security-architecture definitions that share the entry.\n- [NIST SP 800-160 Vol. 1 Rev. 1](https://csrc.nist.gov/pubs/sp/800/160/v1/r1/final) — Engineering\n  Trustworthy Secure Systems, the publication the definition comes from.\n- [Architectural Decision Records](https://adr.github.io/) — what makes a decision architectural,\n  templates for recording one, and tools that help.\n- [The C4 model](https://c4model.com/) — four levels of diagram, from system context down to code,\n  with notation advice and a review checklist.\n- [arc42](https://docs.arc42.org/home/) — practical tips and examples for each of the twelve\n  sections of the arc42 template.\n\n\u003chttps://engineer.company/glossary/architecture/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"What software architecture is, which design decisions deserve to be made early and written down, and how a structure drifts when its rules stay unwritten.","formats":{"gemtext":"https://engineer.company/glossary/architecture/index.gmi","gopher":"https://engineer.company/glossary/architecture/gophermap","html":"https://engineer.company/glossary/architecture/","json":"https://engineer.company/glossary/architecture/index.json","markdown":"https://engineer.company/glossary/architecture/index.md","pdf":"https://engineer.company/glossary/architecture/index.pdf"},"kind":"page","language":"en","title":"What is architecture?","url":"https://engineer.company/glossary/architecture/","version":1}