Context
Manually created architecture diagrams immediately began becoming stale as code and integrations changed.
Challenge
The organization needed architecture documentation that could be refreshed efficiently without allowing automatic tooling to misrepresent system intent.
My role
Design an architecture-documentation approach that derives structural information from source code and routes the result through architect review.
Approach
- Identify architecture facts that can be derived from code.
- Generate diagrams or diagram source from repository changes.
- Separate discovered structure from human-authored intent.
- Create review and approval steps for architects.
- Standardize visual style and notation.
- Make architecture updates part of the engineering lifecycle.
- Preserve the ability to override or annotate generated views.
Outcome
- Reduced current organizational architecture and high-level-design refresh effort from annual manual work to approximately four hours.
- Created the direction for code-derived diagrams that remain closer to the current system state.
- Preserved human approval for correctness, style, and intent.
- Improved the potential usefulness of architecture documentation for onboarding, design review, and modernization planning.
The broader code-derived architecture system is a current initiative. Completed improvements (refresh-cycle reduction) are distinct from planned or in-progress capabilities.
What I learned
- Separate discoverable structure from human intent.
- Automation without review risks false precision.
Architecture diagram
Open questions for refinement
- Which parts of the code-derived pipeline are in production vs. pilot?