Two well-trodden roads in the developer-portal world. Both fail at scale, for opposite reasons. The way out isn't picking one — it's noticing the architecture is already in your code.
Road one: the manual catalogue
You write YAML. Every service gets a catalog-info.yaml. Owners, dependencies, on-call. It's tidy, declarative, machine-readable. For about six weeks.
Then someone renames a service. Someone splits a service. A team rewrites a producer in a different language. The YAML doesn't move with the code, because nothing forces it to. Within a quarter, half the entries are wrong and nobody trusts the catalogue enough to read it.
!
The drift problem is structuralAnything that asks humans to keep two sources of truth in sync will diverge. The only question is how fast.
Road two: runtime tracing
OK, so let's derive the catalogue from running services. OpenTelemetry, sidecars, headers everywhere. The graph is now self-updating — but only for paths that actually fire. Cold endpoints, fallback handlers, that nightly batch — invisible. And you've added cross-cutting infrastructure to every service in your fleet.
Road three: read the source
The third path is to ask: where does the architecture actually live? It lives in the code. Function calls, message publish sites, queue declarations. They're all there, in the AST, every commit. You don't need humans to tell you. You don't need the program to run. You just need to read carefully.
That's what ArchMellon does. We extract the topology from source, on every push, and surface drift as the code itself drifts. The catalogue is a derivative, not a primary artifact.