Structure intake
Identify relevant entities and relationships in the source material.
- Receives
- Files, symbols and their structural relationships.
- Produces
- A representation of the system’s structure.
Work architected at Fifth9
GraFOSa: understanding the relationships around a change
GraFOSa represents code structure as related entities rather than isolated files. Questions about a change can then follow those relationships. An isolated graph alternative offers a place to examine a proposal while keeping structural analysis distinct from executing and testing software.
Structural analysis tooling This is structural analysis. It does not certify the behaviour of a running application.
Download this guide ↗Return to the story ↗
GraFOSa system, composition and analysis architecture ↗ · Original GraFOSa diagrams and sources ↗
The detailed graphical reconstruction and the original text diagrams remain distinct views.
The design question
What could a change affect beyond the code directly in view?
Help people and agents investigate what a proposed change may affect before deciding how to proceed.
A relationship graph provides structural context that is difficult to hold in one conversation. It can connect a proposed change to callers, dependencies and related components, helping an engineer decide where to investigate rather than assuming the edited file is the whole scope.
A view of the responsibilities
Follow relationships around a proposed change
- 01Represent the structureSource relationships
- 02Frame the changeA bounded question
- 03Trace the consequencesPotential impact
- 04Compare an alternativeBaseline comparison
- 05Verify in engineeringEngineering validation
Across the flow
Keep context, responsibility and the boundary between a proposal and an accepted result visible.
What each part is responsible for
The building blocks
Relationship graph
Organise the structure so connected parts can be examined together.
- Receives
- Entities, dependencies and references.
- Produces
- A queryable map of relationships.
Investigation tools
Answer focused structural questions.
- Receives
- Questions about dependencies, reachability or proposed changes.
- Produces
- Potentially affected areas and relationships worth examining.
Isolated alternatives
Support examination of proposed structural changes.
- Receives
- A candidate change and a separate graph view.
- Produces
- A comparison that can be retained or discarded.
Engineering handoff
Make findings usable in implementation and review.
- Receives
- Structural findings and their context.
- Produces
- Focused follow-up questions, review scope and test-planning input.
Following one piece of work
How the flow fits together
01Represent the structure
Build an account of files, symbols and relationships from the source being investigated. Its usefulness depends on both what it can represent and what the available source leaves out.
02Frame the change
Identify the proposed change to an entity or relationship and the assumptions around it. A bounded question, such as which callers may be affected, is more useful than treating every connection as a likely defect.
03Trace the consequences
Follow relevant relationships to identify places that merit review. Keep a distinction between a possible structural consequence and an effect demonstrated by executing the application.
04Compare an alternative
Where appropriate, examine proposed structure separately from the current baseline. This allows an engineer to ask what relationships would change while preserving a reference for comparison.
05Verify in engineering
Use the findings to direct code review and runtime testing. Dynamic behaviour, configuration and external interactions may require evidence that a structural graph cannot supply.
Illustrative example · not a benchmark result
Investigate a change to a shared function
An engineer wants to change a shared function.
- The relationship graph reveals its callers and connected components. Those findings help the team decide where to review behaviour and which tests to run.
- If a dynamic relationship is absent from the graph, the investigation needs other evidence. An empty structural path is not proof that no runtime effect is possible.
The useful result: A better-founded scope for review and testing of the proposed change.
A plausible structural impact is an investigation lead, not proof of a runtime defect.
Why these responsibilities are separate
An alternative graph should not silently replace the baseline used by other investigations. Separating proposed structure from the current view makes comparisons possible. Neither view removes the need to execute relevant behaviour when dynamic effects or environment differences matter.
Reading the architecture accurately
Scope and status
What the work covers
- Code relationship graphs, query tools and structural impact analysis.
- Separate graph alternatives for examining proposed changes.
What still needs to be established
- Which graph findings help people make better changes?
- How should structural alternatives be checked against execution?
- What context makes an impact explanation useful to a reviewer?
Where the design must hold up
Boundaries and evaluation
| Boundary | Why it matters | How to examine it |
|---|---|---|
| Structure versus runtime | A static relationship graph cannot establish all runtime behaviour. | Compare structural findings with executed behaviour where dynamic effects matter. |
| Source freshness | Missing or stale source relationships can weaken an investigation. | Confirm that the graph corresponds to the source version being investigated and identify missing relationships. |
| Interpreting impact | A structural score or finding needs interpretation in the context of the change. | Use a proposed impact to guide review or testing, then evaluate what actually happens. |