Td Architecture Diagram

[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?
3. Did the vscode-ansible crawl find the language server and MCP server?
4. Did the abbenay crawl discover all sub-packages?
5. Did the APME crawl find the Abbenay dependency?

If the crawler missed a known relationship, the agent should note it for manual addition to the generated diagram code before rendering.

Step 3: Generate diagram code

python3 scripts/generate_diagram.py --input .architecture-diagrams/dependencies.json --output-dir .architecture-diagrams --level all

Levels:

• context — L1 System Context (personas, systems, external deps)
• container — L2 Container (individual projects with dependency arrows)
• component — L3 Component (per-repo deep dive)
• all — generate all levels

For a single repo's component diagram:

python3 scripts/generate_diagram.py --level component --component-repo ansible/vscode-ansible

Step 4: Review and refine diagram code

Before rendering, the agent SHOULD review the generated .py files in .architecture-diagrams/ and make refinements:

• Adjust layout by changing Rel to RelDown, RelRight, etc.
• Add missing relationships the crawler could not infer
• Improve labels and descriptions
• Ensure the provenance footer is present

Step 5: Render to PNG

python3 scripts/render.py --input-dir .architecture-diagrams --renderer plantuml

Output: PNG files in .architecture-diagrams/

Step 6: Present results

Show the user the PNG file paths. The user can then paste them into the Miro board or include them in documentation.

Repos Crawled

ADT Primary Projects (10 repos)

ADT Experimental / Testing / Community (5 repos)

AAP Downstream Container Repos (2 repos)

Abbenay — AI Daemon (1 repo)

Abbenay is a TypeScript monorepo producing:

• @abbenay/core — LLM engine abstraction library
• @abbenay/daemon — gRPC server, web dashboard, CLI, VS Code backchannel
• VS Code extension (in packages/vscode/)
• Python gRPC client (in packages/python/)
• Containerized deployment (root Containerfile)

Key relationship: APME depends on Abbenay for AI-assisted remediation.

AAP Portal — External Consumer (not crawled)

The AAP Portal is a custom Backstage instance for AAP self-service. It is NOT a devtools-owned project and is not included in the repo manifest. It appears in diagrams as an external system (SystemExt/ContainerExt) with two key relationships:

• Consumes the ADT web server packaged in the downstream devtools container
• Consumes the ADT Python packages' REST API

APME — Adjacent Consumer (1 repo)

APME is NOT owned by DevTools but is a significant consumer:

• Depends on Abbenay for AI-assisted remediation (Tier 2 escalation)
• Likely depends on ansible-lint (confirm from pyproject.toml)
• Components: CLI, engine, validators, daemon, gateway, Galaxy Proxy, React frontend
• Has own containers, Helm chart, bootc VM deployment

Special Crawling Instructions

vscode-ansible

The VS Code extension is the most architecturally complex single repo. The crawler MUST discover:

1. Python CLI tool dependencies — the extension spawns: ansible-lint, ansible-navigator, ansible-creator, ansible-dev-environment, and potentially others. The crawler searches source code for process spawn calls, command references, and configuration settings.

2. Language Server — the extension contains an integrated Ansible Language Server (previously ansible/ansible-language-server, now merged). Find LanguageClient, createConnection, or LanguageServer references.

3. MCP Server (packages/ansible-mcp-server/) — the extension ships a bundled MCP server (@ansible/ansible-mcp-server) that wraps ADT CLI tools for AI agent consumption. The crawler inspects its src/tools/ directory for spawned Python CLI tools (e.g., ansible-lint, ansible-navigator, ansible-creator, ade, ansible-builder).

4. Package dependencies — package.json deps that map to other ADT projects.

Abbenay

Crawl packages/ monorepo structure for sub-packages. Each directory under packages/ with a package.json is a separate component. Also discover the root Containerfile and proto/ gRPC definitions.

Note: Abbenay does NOT consume the downstream devtools container. That relationship belongs to the AAP Portal (Backstage), which is a separate external system.

APME

Crawl pyproject.toml for Python deps (especially abbenay, ansible-lint). Discover components from the project structure:

• src/apme_engine/ — CLI, engine, validators, daemon, remediation
• src/apme_gateway/ — FastAPI API gateway
• src/galaxy_proxy/ — Galaxy PEP 503 proxy
• frontend/ — React operator UI
• containers/ — container topology
• proto/ — gRPC service definitions

Diagram Provenance

Every generated diagram includes a footer/subtitle:

Generated by architecture-diagram skill — https://github.com/ansible/team-devtools/tree/main/.agents/skills/td-architecture-diagram

This tells anyone viewing the diagram on the Miro board where to find the source for updates or regeneration.

Output Directory

All output goes to .architecture-diagrams/ in the workspace root:

.architecture-diagrams/
├── dependencies.json           # Crawl results (intermediate)
├── l1_system_context.py        # L1 diagram source
├── l1_system_context.png       # L1 rendered
├── l2_container.py             # L2 diagram source
├── l2_container.png            # L2 rendered
├── l3_component_*.py           # L3 diagram sources (per-repo)
└── l3_component_*.png          # L3 rendered

Add .architecture-diagrams/ to .gitignore if not already present.

Scripts