Skip to content

Organization–Artifact Topology Overlay

Diagnostic overlay tool — instantiates Organization–Artifact Topology Alignment

Lays the artifact's dependency map over the collective's communication map on a single frame, so the seams that should coincide but don't — and the ones that needlessly do — stand out.

Separately, a dependency map shows how the artifact's parts couple and a communication map shows who on the team actually talks to whom; neither, on its own, tells you whether the two agree. Organization–Artifact Topology Overlay is the mechanism that puts both portraits of the mirror in one picture. It co-registers the two graphs — same nodes, same layout — and scores each boundary for congruence: does a tight technical dependency run across a thin communication channel (a starved seam that will keep breaking at integration), or does a heavy communication channel sit over a clean, thin interface (an over-coupled team relationship worth decoupling)? Its whole contribution is the comparison surface itself — the single frame on which mismatch becomes visible rather than merely suspected.

Example

A consumer bank is forever firefighting bugs where its mobile app's payments module meets its accounts module. The overlay makes the cause legible. On the artifact layer, payments has a dense dependency on accounts — shared balance logic, tightly coupled. On the social layer, drawn from six months of pull-request reviewers, chat bridges, and meeting invites, the Payments squad and the Accounts squad sit in different divisions and coordinate only through a monthly architecture sync. Superimposed, the picture is stark: a thick technical edge crossing a hair-thin communication edge — an under-communicating seam. The same overlay also flags the opposite: two front-end squads that talk constantly yet own modules joined by a clean, stable API — an over-communicating seam that is a candidate to decouple and free both teams. What was "integration keeps breaking somewhere around payments" becomes a named, located, two-sided finding.

How it works

The distinctive move is co-registration and congruence scoring, not the deep analysis of either side:

  • Align the nodes. Place artifact components and the teams/individuals that own them on the same canvas so each boundary can be read as both a technical seam and a social seam at once.
  • Overlay the edges. Draw dependency edges and communication edges together, weighted, so a heavy-thin or thin-heavy crossing is visible at a glance.
  • Classify each seam. Score every boundary as congruent (coupling and channel roughly match), under-communicating (tight coupling, thin channel), or over-communicating (thin coupling, heavy channel). The classification is the output the rest of the appraisal acts on.

Tuning parameters

  • Node granularity — module vs. service vs. file; team vs. individual. Finer resolution surfaces more seams but adds noise and false mismatches.
  • Communication signal source — the reporting chart versus observed traces (reviews, chat, incident bridges, ticket reassignments). Observed data reveals the real network but raises privacy stakes.
  • Edge-weight thresholds — what counts as "tight" coupling and "heavy" channel. Sets the tool's sensitivity and how many seams it flags.
  • Congruence scoring — a binary match/mismatch tag versus a graded mismatch score that ranks seams by severity.
  • Snapshot vs. time-lapse — one frame versus an animation across releases that shows a seam drifting from congruent to mismatched.

When it helps, and when it misleads

Its strength is that it converts vague, recurring integration pain into a located seam that both engineers and managers can look at on neutral ground — the map is about boundaries, not blame. It is the fastest way to see the mirror Conway's law predicts instead of arguing about whether it exists.[1]

It misleads when the social layer is drawn from the org chart rather than from real behaviour: "fix" a phantom channel and the mismatch stays. A single snapshot also hides direction — whether the team split caused the module split or the reverse — so the overlay can suggest a boundary is wrong when it is merely young. Its classic misuse is running it after a reorganization is already decided, to produce a picture that ratifies the choice. The discipline that keeps it honest is to feed it observed communication data, treat every mismatch as a hypothesis to investigate rather than a verdict, and pass confirmed seams to the mechanisms that log and act on them.

How it implements the components

The overlay realizes the mapping-and-comparison face of the archetype — the co-registered picture and the congruence read, not the single-side deep dives:

  • artifact_topology_map — co-registers the artifact layer (components and their dependencies) onto the shared frame.
  • collective_communication_topology_map — co-registers the social layer (teams and their real channels) onto the same frame.
  • seam_congruence_assessment — its signature output: the per-seam classification of where technical and social boundaries agree or clash.

It does not profile coordination load in depth or infer the informal network — the rich single-side analyses are Architecture Dependency Graph Review and Communication Pattern Review — nor does it log confirmed mismatches as tracked debt; that is Silo Imprint Audit.

Notes

The overlay diagnoses; it does not prescribe. A mismatched seam is a question — "why does this tight dependency cross such a thin channel?" — and the answer may be to add a channel (a Liaison or Architecture Forum), to move a boundary (a refactor), or to accept it as an unavoidable cost. Reading the overlay as an instruction rather than a prompt is the surest way to over-refactor.

References

[1] Conway's law — an organization that designs a system produces a design whose structure mirrors the organization's own communication structure (Melvin Conway, 1968). The overlay is a way to see that mirror directly instead of inferring it after the fact. ↩