How do I get a reliable list of everything my system is made of?

#What it is

Component registry

A record of the distinct parts of a system, each with a canonical type (service, module, database, queue, scheduled job, external system and so on), a name, a description written for a non-programmer, and a stable identifier that survives being renamed.

In plain terms The inventory: every distinct thing your software is made of, with what it is for and where it lives.

It is the flattest and least glamorous of the things a technical picture contains, and it is usually the first one somebody actually needs. "How many moving parts does this thing have" is the opening question of every handover, every technical due diligence and every new engineer's first week.

#Why nobody has one

Not because it is difficult to write down. Because of what happens after it is written down.

• It is obsolete before it is finished. A list compiled over two weeks is describing a system that moved during those two weeks.
• The boundaries are arguable. Is that a service or a module? Is the queue a component or an implementation detail? Two people produce two different lists from the same system, and both are defensible.
• The interesting entries are the ones nobody remembers. The scheduled job somebody added in 2023. The small internal API another team depends on. The report that emails a spreadsheet every Monday.
• Nothing forces it to be updated. Adding a component to a system does not require adding it to a list, so the list is only ever as current as somebody's discipline.

The first three are helped by deriving the list from an analysis instead of from memory. The fourth is only solved by deriving it again.

#What a good entry contains

#Identity is the whole problem

A registry that cannot recognise a component across two analyses is not a registry. It is two unrelated lists.

Consider what has to be true for the sentence "the billing service now also writes to the audit database" to be produceable. The system must recognise that the billing service in September's analysis is the same billing service as in May's — even though the class was renamed, the file moved, and the description was written differently by a different agent.

Names cannot carry that. A path alone cannot carry it either. So every component is asked to carry something stable:

• a repository path, where the thing is a file or directory;
• a fully qualified name, where the language provides one;
• an external identifier — a label chosen and kept — for anything with neither, such as a database, a queue, a cloud resource or a deployment target.

Getting this right was the hardest part of building 1ADK, and an early version did get it wrong: a second analysis of an unchanged system created duplicate entries for things it should have recognised. It was fixed by making identity explicit rather than inferred. Worth knowing as a buyer, because any tool claiming to track architecture over time has this problem, and most of them solve it by not mentioning it.

#What one looks like

SERVICE            Billing service
                   Creates invoices and records payment attempts.
                   app/Services/Billing/          ·  confidence HIGH

SERVICE            Subscription service
                   Holds what each customer is subscribed to and
                   when it renews.
                   app/Services/Subscriptions/    ·  confidence HIGH

DATABASE           Main database
                   Orders, payments, invoices, subscriptions.
                   external id: db.main           ·  confidence HIGH

QUEUE              Payment queue
                   Work waiting to be settled with the provider.
                   external id: queue.payments    ·  confidence MEDIUM

SCHEDULED JOB      Nightly export
                   Writes a CSV of the previous day's payments.
                   app/Console/Commands/          ·  confidence HIGH
                   ⚠ destination not established

EXTERNAL SYSTEM    Payment provider
                   Takes card payments.
                   external id: ext.payments      ·  confidence HIGH

#What it is used for

• Sizing a handover. "Twenty-three components, four of which nobody can name an owner for" is a scope. "It's a Laravel app" is not.
• Finding the forgotten parts. Scheduled jobs and small internal interfaces are what a registry surfaces and a conversation does not.
• Technical due diligence. A buyer's first question is what they are buying. This is the shortest honest answer.
• Onboarding. A new engineer with a typed list of parts and their purposes starts a week ahead.
• Change detection. The registry is what change history compares.

#What it does not include