Transform GitHub repos into evidence-based architecture blueprints with Claude

Description

Requirements: GitHub API token (repo scope), Anthropic API key (Claude Sonnet 4.5), Slack Bot Token (optional)

This workflow analyzes any public GitHub repository and generates an evidence-based architecture blueprint — with Mermaid.js diagrams, technical stack analysis, and risk assessment — then pushes it as README_ARCH.md directly to the repo.

What makes it different: A strict anti-hallucination prompt ensures Claude only describes technologies that actually exist in the code. No Dockerfile? Docker is never mentioned. No .tf files? Terraform doesn't appear. Every claim traces back to real file evidence.

How it works

A GitHub URL is submitted via the web form or webhook API
The workflow fetches repo metadata, the full file tree, and contents of key files (package.json, requirements.txt, Dockerfiles, entry points, etc.)
Claude Sonnet 4.5 (temperature 0.1) analyzes only the evidence — strict rules prevent inventing technologies not found in the code
A Markdown blueprint with architecture diagrams and risk analysis is assembled, auto-fixed, and pushed to the repo's default branch
A Slack notification is sent and the form user receives a styled success page

Example output

The generated README_ARCH.md includes:

Project Purpose** — What the project does, based on code evidence
Technical Stack** — Languages, frameworks, and dependencies from actual dependency files
Architecture Blueprint** — Mermaid.js flowchart with dark-theme styling, grouped by layer
Request Flow** — Sequence diagram showing a typical path through the system
Evidence-Based Risks** — Three risks traceable to specific files or patterns

Use cases

Open-source maintainers** — Auto-generate architecture docs for contributors
Engineering teams** — Quick onboarding docs for new team members
Code reviewers** — Understand unfamiliar repositories at a glance
Technical due diligence** — Rapid architecture assessment of vendor codebases
Portfolio projects** — Add professional documentation to showcase repos

Setup

See the Setup & Overview sticky note in the workflow for step-by-step credential configuration.