Architecture debt is technical debt in the structure of a system: boundaries drawn in the wrong place, components that can't change independently, and data that several systems share without anyone owning it. It slows every change that crosses those lines. A code scanner's technical debt figure is built from code smells inside files, and architecture debt mostly sits between them.
At AICO we call the unrecorded part hidden architectural debt, and finding it is the core of our review. This post defines architecture debt, separates it from code-level debt, gives eight examples, and shows how to find and record it. For everyday debt of every kind, see our technical debt examples.
- Architecture debt is technical debt in a system's structure: its boundaries, dependencies and data ownership, not the code inside any one file.
- A scanner's technical debt figure is built from code smells. Architecture debt sits between components, so it rarely shows up there.
- The business sees symptoms: small changes that need three teams, releases that must ship together, systems that disagree.
- Find it in dependency maps, change history and incidents, and record it in a register with an owner so it can be weighed against features.
What is architecture debt?
Architecture debt is the extra cost every future change pays because of how a system is divided and connected. The code inside each part can be clean and well tested, and the system can still be slow to change, because the parts are cut along the wrong lines or tied together where they should be separate.
Our definition of hidden architectural debt is architecture debt nobody has recorded. It isn't in the backlog, the diagram doesn't show it, and the team has learned to work around it, so the people closest to the system are often the last to name it.
Technical debt vs architecture debt
Technical debt is the broad term: anything that makes the next change slower or riskier than it should be. Architecture debt is the part that lives in structure rather than in lines of code.
The difference shows in how each is measured. SonarQube's metric definitions describe its technical debt figure as "A measure of effort to fix all code smells." How to measure technical debt explains how it's calculated. By design, it counts problems inside the code.
SonarQube Server 2026.5 also has an architecture feature that compares code with an intended architecture, for "C#, Java, JavaScript, Python, and TypeScript." Its documentation names the problem "architecture erosion, also called structural technical debt," and adds: "Without action from tech leads, no SonarQube issues are raised." A tool can check code against a design someone has defined. Deciding what that design should be, and finding debt where the tool doesn't read, such as stored procedures, batch scripts and a database three applications share, is still work for people.
What is hidden technical debt?
Hidden technical debt is debt that builds up where nobody looks, usually because it sits at the level of the whole system. The phrase is the title of a paper by D. Sculley and nine co-authors, Hidden Technical Debt in Machine Learning Systems, in the NeurIPS proceedings for 2015. Two of its lines apply well beyond machine learning: "Hidden debt is dangerous because it compounds silently," and this debt "may be difficult to detect because it exists at the system level rather than the code level."
Hidden technical debt in machine learning systems
The paper argues that machine learning systems "have all of the maintenance problems of traditional code plus an additional set of ML-specific issues." Its examples include glue code, pipeline jungles in data preparation, and undeclared consumers of a model's output, which "are referred to as visibility debt" in classical software engineering. Its Figure 1 caption makes the structural point: "Only a small fraction of real-world ML systems is composed of the ML code." Older systems work the same way: the jobs, scripts and shared tables around the reviewed code are where the debt collects.
Architecture debt examples
Each example starts with what the business notices.
| Symptom the business sees | Structural cause |
|---|---|
| A small change needs work from three teams | Wrong boundaries: one capability, such as pricing, split across several components |
| Every schema change becomes an investigation | A shared database used as the integration layer, with several applications writing the same tables |
| A change in one module breaks another that looked unrelated | Cyclic dependencies: modules that depend on each other, directly or through a chain |
| Every project queues for the same component | A god module holding most of the business logic and many unrelated jobs |
| Screens are slow, and one system's outage spreads to others | Chatty integrations: many small synchronous calls between systems for each user action |
| Two systems give different answers to the same question | Business rules duplicated across systems, each copy changed at a different time |
| Nothing can ship alone | Deployment coupling: components built, versioned or released as one unit |
| Testing anything means standing up everything | Missing seams: no interface where a part could be tested, replaced or wrapped alone |
How do you find architecture debt?
Start from evidence the system already keeps, not from the diagram.
- Dependency maps. Draw what calls what, and which applications write each important table, from the code and database permissions rather than the wiki. Cycles and tables with many writers stand out.
- Change coupling in version control. Files that always change together, across components meant to be separate, mark a boundary that isn't real.
git log --name-onlylists the files in each commit; count the pairs that keep appearing together. - Incident history. For each recent outage or rollback, ask which structural fact made it possible.
- The approvals test. Take a routine change, such as adding a field to an order, and count how many teams must agree or release before it's live. More than one points to a boundary in the wrong place.
Our software architecture review checklist covers the wider review these steps fit into.
An architecture debt register template
Architecture debt gets paid down once someone can weigh it against features. A register makes that possible: one row per item, written so a budget holder can read it. The rows below are illustrative.
| Item | Where | Symptom | Business impact | Fix options | Owner |
|---|---|---|---|---|---|
| Orders table written by three applications | Order database | Every schema change needs three teams | Ordering changes wait for the slowest team | Route writes through one order service | Head of engineering |
| Discount rule in two systems | Pricing service and invoicing batch job | Quotes and invoices disagree | Finance reconciles by hand at month-end | Make pricing the owner; invoicing calls it | Pricing product owner |
| Customer and billing modules depend on each other | Core application | A change in either breaks the other | Every billing change needs wide retesting | Extract the shared piece, or break the cycle with an interface | Lead developer |
| Five components release together | Build and release pipeline | Nothing ships alone | One delayed fix holds up every change | Separate the builds and version each interface | Platform lead |
Keep the register beside the scanner's findings and review both each quarter. How to reduce technical debt covers paying items down alongside feature work.
Finding hidden architectural debt in 30 days
Your team can run these steps. What's hard from the inside is seeing the debt everyone has learned to work around. That's the job of the 30-day assessment. It's fixed in scope, at a price agreed before we start. Over 30 days we read the codebase and the architecture around it, map how the system fits together, including the tables, jobs and integrations outside the main repository, find the hidden architectural debt, and flag the security and compliance gaps.
The report says in plain language what is broken and what it would take to fix it, item by item, ready for an architecture debt register. Your own team can pay it down, or we can do the work as a separate project with its own scope and price. The report stands on its own.
Ask us whether it's worth assessing before the next small change turns into a project. If a narrower check would answer your question, we'll say so.