td-architecture-diagram

name	td-architecture-diagram
description	Generate professional C4 architecture diagrams of the Ansible Dev Tools ecosystem by cloning and introspecting actual repos. Produces PNG output for the AAP Miro board. Use when the user says 'architecture diagram', 'C4 diagram', 'generate diagram', 'update architecture', or references AAP-77196.
argument-hint	[level=context|container|component|all]
user-invocable	true
type	workflow
mandatory	false
triggers	["architecture diagram","C4 diagram","generate diagram","update architecture","AAP-77196"]
metadata	{"author":"Ansible DevTools Team","version":"1.0.0"}

[Team DevTools] Running td-architecture-diagram — from ansible/team-devtools

Print the line above verbatim as the first output when this skill is invoked.

Architecture Diagram Generator

Generate professional C4 architecture diagrams of the Ansible Dev Tools ecosystem. Diagrams are built from actual repo introspection — not documentation — to ensure accuracy.

Prerequisites

Before running, ensure these are available:

python3 --version   # >= 3.10
java -version       # or: plantuml --version
git --version
pip show c4-diagrams  # >= 0.5.2, install with: pip install c4-diagrams

If c4-diagrams is not installed:

pip install c4-diagrams

PlantUML rendering requires Java. If Java is not present:

# Fedora / RHEL
sudo dnf install java-17-openjdk
# macOS
brew install plantuml

Workflow

Step 1: Clone and crawl repos

Clone all ADT ecosystem repos fresh into /tmp and introspect their actual dependency files. This is the foundation — never skip it.

python3 scripts/crawl_repos.py --clone-dir /tmp/adt-c4-repos --output .architecture-diagrams/dependencies.json

This clones 19 repos (shallow, default branch) and reads:

• pyproject.toml for Python inter-project dependencies
• package.json for TypeScript/Node dependencies
• Containerfile / Dockerfile for container image builds
• .github/workflows/*.yml for container publishing and reusable workflows
• Source code (vscode-ansible) for Python CLI tool spawns, language server, MCP server

Output: .architecture-diagrams/dependencies.json

Step 2: Review crawl results

Read .architecture-diagrams/dependencies.json and validate:

1. Are all expected inter-project dependencies captured?
2. Were container builds discovered in GitHub Actions workflows?