Position: The repository governs meaning; the graph makes its consequences visible.
Executive summary
A traditional architecture diagram shows selected things and relationships at one moment. A connected architecture knowledge graph can answer a different class of question: which parts of an estate depend on a service, why a change is proposed, what evidence supports a decision, and how today's reality differs from a future proposal. These are not merely visualisation problems. They depend on identity, relationship semantics, provenance, context and lifecycle.
Our central position is that the repository is a governed knowledge model; the graph is one of several views of that model. Building a better renderer without addressing the meaning of its edges produces attractive but unreliable answers. Building a sophisticated model without making its connections navigable produces a repository that practitioners may not use. A viable enterprise architecture practice needs both.
This paper develops an information model, a worked fictional change scenario, a directed impact-analysis method and practical visualisation principles. Its lessons are drawn from iterative design work on architecture tooling, but all organisational examples are fictional. Specific recommended approaches are design principles, not claims that every capability is already implemented in a product.
1. Why static diagrams stop being enough
A diagram is useful because it makes a deliberate argument. An integration overview may focus on interface ownership; a deployment diagram may emphasise operational zones; a capability map may be interested in organisational outcomes. The problem arises when a diagram is treated as the system of record.
Consider a service represented on four separate drawings. When its interface changes, who finds and updates all four? Does each drawing agree on what the service is? Are the dependencies actual integrations, planned replacements, implied ownership relationships, or just visual proximity? A picture alone cannot safely answer those questions.
A knowledge graph instead keeps the underlying entities and typed assertions separately from their presentation. A service has one persistent identity, but many possible views. A view may be saved, filtered, rendered or exported without becoming an alternative source of truth. The diagram remains valuable—it is simply no longer the sole owner of the architecture facts.
2. Knowledge graph does not mean one giant diagram
The term knowledge graph refers here to uniquely identified entities, explicitly typed relationships and enough contextual evidence to interpret those assertions. It does not mandate a graph database. A relational repository with well-defined foreign keys and relationship records can provide this model; a dedicated graph engine may be chosen if traversals, scale or operational economics justify it.
A useful conceptual model has four layers:
- Entities: capabilities, applications, services, APIs, data, technology, principles, requirements, projects, decisions and patterns.
- Assertions: explicitly typed, directional links such as Service consumes API, Application realises Service, Technology hosts Application or Decision addresses Requirement.
- Contexts: current accepted state, candidate project overlays, planned retirement and historical revisions.
- Views: dependency graphs, estate maps, capability hierarchies, review screens and document extracts.
Keeping these layers distinct prevents a renderer choice from silently redefining the repository's semantics.
3. Relationships are assertions with consequences
An edge labelled simply “related to” offers very little analytical value. A relationship should state who is related to whom, in which direction, and by what predicate. Direction matters both for impact analysis and graph presentation.
For example, if Ordering Service consumes Customer API, an outage or incompatible contract change to Customer API can affect Ordering Service. Conversely, a change to Ordering Service need not affect the API provider. Traversal therefore requires an explicit rule: are we following dependencies to their providers, or looking backwards for dependants?
Relationships also need safeguards: endpoint type constraints, permitted cardinalities, provenance or author, effective context, and revision history where appropriate. Some connections may be inferred from other facts, but inferred assertions should be distinguishable from confirmed ones.
Composition is not dependency. An application that contains components has a whole–part structure; an application that consumes an API has a runtime or contract dependency. Treating those as interchangeable produces false impact paths and graph clutter.
4. A compact worked model
Consider Alderwick Services, a fictional organisation modernising its bookings capability. Its current estate contains a Booking Portal, Booking Service, Customer Lookup API, Customer Master application and Legacy Notifications Service. A programme proposes an Event Publisher and replacement Notification Consumer.
| Source | Relationship | Target | Context |
|---|---|---|---|
| Booking Portal | invokes | Booking Service | AS-IS |
| Booking Service | consumes | Customer Lookup API | AS-IS |
| Customer Lookup API | is provided by | Customer Master | AS-IS |
| Booking Service | calls | Legacy Notifications Service | AS-IS |
| Event Publisher | publishes | Booking Confirmed Event | Project Northstar |
| Notification Consumer | subscribes to | Booking Confirmed Event | Project Northstar |
| Architecture Decision AD-17 | selects | Event publication pattern | Project Northstar |
The example deliberately mixes operational, contractual, design and governance facts. It would be a mistake to display every edge in a single dependency graph: AD-17 is not a runtime dependency, and the project-only subscriber does not yet exist in the accepted estate. Filtering by relationship family and context is a correctness requirement, not just a UI preference.
5. The AS-IS estate and project overlays
Enterprise architecture changes are rarely serial. Multiple initiatives propose modifications to the same accepted estate, often with competing assumptions. A single status value such as “TO-BE” cannot explain whose proposal is being viewed, what baseline it changed, or whether a change has been accepted.
The stronger model maintains an accepted current view and permits one or more project-scoped overlays. Each proposed alteration references the relevant existing identity or declares a genuinely new element. A view can then compare the accepted Booking Service to Project Northstar's proposed changes without pretending they have already gone live.
When projects overlap, the renderer should not silently merge incompatible proposals. It should show provenance and conflict: two projects may propose to replace the same integration using different mechanisms. Acceptance and activation should be governed lifecycle operations with preserved history, not a cosmetic change of diagram colour.
6. Practical impact analysis uses explicit traversal rules
Suppose the Customer Lookup API is proposed for a breaking change. The useful question is not “show everything in the database” but “which accepted consumers may be affected, and which project proposals introduce additional consumers?”
A reproducible traversal looks like this:
- Start from the stable identity of Customer Lookup API.
- Select allowed relationship predicates: consumes API or calls interface, not described by or belongs to taxonomy.
- Reverse the dependency direction to find dependants.
- Follow permitted transitively related dependencies, subject to cycle detection and a declared depth or scope.
- Return the path, predicate and context that justify each result.
- Overlay candidate project relationships separately and label them as proposed.
The path itself is evidence. “Booking Portal may be affected” is more credible when an architect can inspect Booking Portal → Booking Service → Customer Lookup API than when the tool merely paints the portal orange.
Depth limits are a navigational choice, not a statement that dependencies beyond that limit do not exist. A focused graph might default to a limited number of hops; an estate-wide map may expand that scope or offer a clear “beyond current depth” control. The user should always understand what was omitted.
7. Directional layouts and orthogonal edge routing
An architecture graph can be semantically correct yet impossible to read. A practical left-to-right dependency renderer should assign layers to nodes, place endpoints on explicit ports, route edges in orthogonal horizontal and vertical segments, and preserve legible separation between parallel edges.
A strong default is for outgoing dependency arrows to depart from a node's right side and enter the target's left side. An initial left-to-right topological pass can establish approximate layering for an acyclic projection; a subsequent right-to-left pass can reduce backwards paths and revise placement where dependencies point against the first assignment. Strongly connected components must be condensed or handled explicitly rather than assuming the graph is acyclic.
Layout and routing should avoid occluding node labels, crossing nodes, and compressing service boundaries so tightly that their children become unreadable. Rounded orthogonal corners and consistent arrowhead treatment help, but do not compensate for misleading edges. A service boundary should provide useful scope and grouping rather than force every graph into an unreadable box.
Technology identities are better conveyed by controlled icons and hover details than repeated internal TECH-xxx identifiers across an estate-wide map. Icon-only displays still need accessible text and an inspectable legend or tooltip.
The hard lesson: a graph engine that performs well for a local dependency view should ideally underpin estate-wide projections too. Maintaining unrelated renderers for the same semantics creates visual disagreement, repeated layout defects and loss of user confidence.
8. Progressive disclosure beats maximal density
A complete repository may have thousands of nodes and relationships. Displaying all of them at once is not proof of architectural maturity. The renderer should expose understandable scope: begin with the selected service, expand dependants or providers, show or hide technologies, and optionally reveal project overlays.
Useful interaction requirements include stable node selection, an explicit way to clear selection, fit-to-view and actual-scale controls, predictable preservation of filters when returning from a detail page, and readable hover information that does not obscure important edges. Saved views should retain view configuration, not create a stale copy of authorised architecture data. When reopened, a view should refresh against the current permission-scoped repository rather than silently presenting an old snapshot as truth.
A capability hierarchy is better represented as a clean tree when its primary purpose is classification. A graph earns its complexity only when it exposes additional relationships or answers a question that a list or hierarchy cannot.
9. One source of truth, many consumers
The authoritative relationship model should be available to more than the browser that first authored it. Read-only APIs can support architecture views, governance dashboards, traceability queries, controlled exports and a separate solution-document authoring application.
A document consumer may ask for the solution's accepted baseline, project changes, dependencies and relevant decision evidence. It should receive governed facts and source references, not scrape HTML from a diagram. A document-specific application can own narrative, layout and approvals while the architecture repository retains ownership of canonical objects.
Every consumer needs tenant-scoped and user-scoped authorisation, explicit version/context selection and a distinction between implemented endpoints and illustrative proposals. This is particularly important when an estate contains sensitive architectural metadata.
10. Where this approach can fail
There are real trade-offs. Richer relationship types increase validation and authoring complexity; too few types make traversals ambiguous. Live graph traversal can be computationally expensive; caching can improve responsiveness but creates invalidation and freshness obligations. Cross-project comparison adds complexity around identity reconciliation and competing proposals. Automatic inference can suggest useful connections, but incorrect inferred dependencies can undermine trust.
A graph database is not a universal answer. Query profiles, data size, transaction requirements, audit needs and team skills should determine persistence choices. Similarly, elaborate graph layout should not substitute for a simpler table when the user wants an exact list of affected APIs.
Architectural quality requires measuring false positives and false negatives in impact analysis, not just rendering speed or the number of stored relationships.
11. A pragmatic adoption roadmap
A practical implementation can proceed in increments without sacrificing the target model:
- Identify stable entities. Give core records durable identity, ownership, scope and lifecycle.
- Define precise predicates. Start with the relationships that answer genuine questions; document direction and permitted endpoints.
- Build a focused dependency traversal. Return inspectable paths and support cycle detection.
- Separate accepted and proposed states. Make project context explicit before adding comparisons.
- Add a readable graph renderer. Use explicit ports, orthogonal routing, deliberate layering and selective expansion.
- Make views reusable. Save configuration but refresh the authoritative data on reopen.
- Publish governed APIs. Let assurance, documentation and other consumers reuse the same architectural facts.
At each stage, test with a real architectural question such as: “What would change if this API were retired?” Use the answer's correctness and clarity as the acceptance criterion.
12. Operational assurance and quality checks
A graph that looks attractive in a demonstration may still fail under everyday operations. Assurance should therefore cover three layers. First, data integrity: identities remain stable; each relationship satisfies endpoint and context constraints; and retired or superseded assertions cannot be mistaken for current ones. Second, analysis integrity: traverse known dependency chains in both directions; verify expected inclusions and exclusions; test cyclic paths, orphaned nodes, multiple consumers and parallel project proposals. Third, presentation integrity: no critical label is occluded; selected-node state clears correctly; orthogonal routes do not cut through nodes; and boundary modes reserve enough spacing.
Use a small, versioned reference graph as an executable acceptance case. For example, record a known eleven-node estate with two cycles, one isolated technology component, one project-only API and two service boundaries. Define expected dependency and dependant sets for several selected nodes. A new graph release should reproduce those sets regardless of filtering or layout. Visual snapshots help find regressions, but semantic assertions should be checked independently of pixel differences.
A final production concern is freshness. If a saved view is restored after a new architecture revision has been accepted, its title, filters and viewport may be reusable, but the data must be re-authorised and reloaded. A defensible system can display when the projection was last refreshed, identify unavailable objects and avoid implying that an older state is the current one.
This kind of test suite turns a subjective “the World Map looks right” discussion into a repeatable architectural quality gate. It should complement—not replace—signed-in exploratory usability testing with realistic estates.
Conclusion
Architecture knowledge becomes valuable when people can follow the connections among decisions, capabilities, services, contracts and change. A graph is not a magic picture of the entire enterprise; it is a traceable model that can be projected into several useful views.
The strongest result combines precise meaning, contextual history and legible presentation. Model the relationship once, preserve its source and context, then let an architect explore the estate at the level of detail the decision requires.
References and further reading
- ISO/IEC/IEEE 42010, Architecture description, for the importance of stakeholder concerns, viewpoints and architecture descriptions.
- The Open Group, TOGAF Standard, for architecture governance, content and evolution principles.
- The Open Group, ArchiMate Specification, for disciplined modelling language concepts and relationship semantics.
- MétiArch, Living Architecture: From Diagrams to Governed Evolution.
- MétiArch, Progressive Architecture Traceability.
- MétiArch, Composition Is Not Dependency.
These references inform the discussion; this paper does not claim formal certification or conformity to any named standard.
Continue with Directed Dependencies, Ports and Orthogonal Routing, or the MétiArch reading path.