workflow-generator

Scan the current project and produce a complete visual system workflow with concurrency capacity analysis.

Steps

1. Locate the project root — use the current working directory unless the user specified a path.

2. Run the analyzer:

   python3 ~/.claude/skills/workflow-generator/scripts/analyze.py <project_root> <project_root>/WORKFLOW.html --enrich-labels

   Optional flags, appended after the two positional args:

   • --access-log <path> — overlay real request counts (from a combined/common log file) onto the codebase dependency graph's HTTP-entry edges, instead of import-direction only.
   • --graph-detail auto|files|dirs — force file-level or directory-level graph nodes. Default auto aggregates to directories once a project exceeds ~350 source files.
   • --enrich-labels — always pass this when running via this skill (you're already an authenticated claude session, so the cost is already accepted). It relabels Architecture Map service nodes by having a local claude -p call actually read each file, instead of the mechanical stem-dictionary label (see Architecture Map below). It's a no-op everywhere else if claude isn't on PATH — never fails the scan.
3. Open the output:

   xdg-open <project_root>/WORKFLOW.html 2>/dev/null || open <project_root>/WORKFLOW.html 2>/dev/null || true

4. Report to the user — include:
   • Framework and worker count
   • Concurrent request capacity (total I/O + practical throughput)
   • Primary bottleneck
   • Detected storage and external sources
   • Clickable link to WORKFLOW.html

Output sections

The generated WORKFLOW.html always contains all of the following:

1. Stat row — 4–6 large-number tiles:
   • API Worker Processes (replicas × uvicorn/gunicorn workers)
   • Max Concurrent Async I/O (~100 per asyncio worker)
   • Max Parallel CPU Tasks (asyncio.Semaphore limit, if detected)
   • Rate Limit (nginx / slowapi / express-rate-limit, if detected)
   • Practical Throughput (what the real ceiling is after all limits)
   • LLM Timeout (if an LLM provider is detected)
2. System Architecture diagram — adaptive layered CSS flow:
   • EXTERNAL SOURCES & CLIENTS — webhook sources (Jira, Slack, ADO, GitHub, Stripe), users
   • GATEWAY / REVERSE PROXY — nginx, Caddy, Traefik (with rate limits + worker_connections)
   • APPLICATION LAYER — API framework + frontend (Streamlit, React, Next.js, etc.)
   • PROCESSING & QUEUE LAYER — Semaphore-guarded CPU tasks, Celery/Bull/Kafka workers
   • AI / INTELLIGENCE LAYER — LLM providers, embedding, evaluation framework
   • STORAGE & PERSISTENCE — vector DB, relational DB, NoSQL, Redis, S3

3. Data Flow Paths — step-by-step cards per detected flow:

   • Write Path (webhook route + signature-check evidence, if any)
   • Read Path (LLM + vector store presence)
   • Queue/Background Jobs
   • Generic HTTP flow (if nothing else detected)

   These cards combine genuinely detected facts (provider names, models, timeouts, specific routes, real HMAC-verification evidence) with the typical shape of that kind of component. They are not a trace of an actual request path through the code — the tool never confirms that a detected webhook source and a detected route are the same request. Card titles say "(inferred, not traced)" or "(typical pattern)" for exactly this reason, and individual steps say "not confirmed" wherever the claim isn't backed by direct evidence.

4. Concurrency Model table — every layer with model / ceiling / limiting factor (a category label, not a file:line pointer into the user's code)
5. Bottleneck Analysis — ranked bar cards (CRITICAL → LOW). Severities are derived from the same min() comparison used for the "Practical Throughput" stat, so this section and that stat can never disagree with each other.
6. Architecture Map — a curated, high-level view of how the system works, distinct from the raw dependency graph below it: one node per entry point (grouped by router/controller file, not by URL prefix), internal service, datastore, external integration, scheduled job, and — when detected — AI agent/model/tool. Built entirely from already-detected facts plus a few light, deterministic file-pattern checks (composition-root file, crud/service/repository-named modules, tool-binding/agent-framework signatures); by default no LLM judgment is involved, so the node/edge set is identical across the CLI, MCP server, Copilot extension, and this skill. Service-node labels are the one part of this that stays mechanical by default (a fixed stem→label dictionary, so a generically-named file gets no node at all) — pass --enrich-labels (always on when invoked via this skill; opt-in flag/param on CLI, MCP's generate_workflow tool, and the Copilot extension's enrichLabels request field) to have a local claude -p call read each service file and relabel it with what the code actually does. It only ever renames existing nodes — never invents new ones — and silently no-ops if claude isn't installed, so the deterministic output is always the floor. Entry→service edges are only drawn when the entry file actually references the service module's name — never a blanket fan-out. Click any node for a detail panel (what it is, its source file); click Show import details to jump to the Codebase Dependency Graph below with that component's exact files isolated and highlighted. Nodes sharing a feature (inferred from router/service naming) cluster together with a matching accent color and group label.
7. Codebase Dependency Graph — a force-directed graph of every source file (Python, JS/TS, Go, Java, Rust, Ruby) as a node and every real, parser-resolved import as an edge; files that match an already-detected component (an LLM call, a database client, a queue) also get an edge to that component. Click a node to isolate its neighbors; hover for file details. Large projects (350+ files) are aggregated to directory-level nodes automatically. Edges are import-direction only (static, honest) unless --access-log was supplied, in which case HTTP-entry edges are weighted with real observed request counts — the graph is explicit about which kind of edge is which so it's never mistaken for a traced request path. Test files are split into a separate Test Graph section (tests plus the modules/services they import or call), so they don't clutter the main graph. Each has a Flow | Graph toggle over the same nodes/edges: Flow is a layered left-to-right diagram (depth columns, every service its own node in the last column, cycles dashed), Graph the force-directed view. Dots animate data both ways (filled = call, hollow = return); past 60 edges only the clicked/hovered node's paths animate. The Full System Architecture section is collapsed by default.
8. Guided tour — a spotlight walkthrough that dims the page and steps through each section in turn (Back/Next/Skip), shown automatically the first time a generated report is opened. Steps for sections that don't apply to a given project (e.g. no detected routes, no graph) are skipped automatically. Replayable anytime via the ? button next to the theme toggle.

What the analyzer detects

Workers & replicas

Async concurrency model

Rate limits

External sources

Jira · Azure DevOps · Slack · GitHub · Stripe · Salesforce · Twilio · S3 · Users/clients · Cron/Scheduler

LLM providers

OpenAI (ChatOpenAI / gpt-*) · Anthropic (Claude) · Cohere · AWS Bedrock

Vector stores

Qdrant · Pinecone · Weaviate · ChromaDB · pgvector · FAISS · Milvus

Databases

PostgreSQL · MySQL · MongoDB · SQLite · Redis

Queues

Celery · BullMQ · Kafka · RabbitMQ · RQ · AWS SQS

Evaluation frameworks

TruLens · RAGAS · LangSmith

Concurrency calculation

total_workers       = (uvicorn_workers + gunicorn_workers) × replicas
per_worker_io       = 100 if asyncio else 1
total_io_concurrent = total_workers × per_worker_io
concurrency_ceiling = min(total_io_concurrent, semaphore × total_workers)   # whichever is present

practical_limit is a genuine min() across every throughput-shaped constraint that was actually detected — not a priority-ordered guess that stops at the first match:

candidates = []
if nginx/Caddy rate limit detected:      candidates += gateway_rate (r/m, parsed from config)
if slowapi/express rate limit detected:  candidates += app_rate (r/m)
if an LLM provider was detected:         candidates += concurrency_ceiling × (60 / timeout)
practical_limit = min(candidates) if candidates else concurrency_ceiling

The LLM term ties the throughput estimate to this project's actually-detected worker count and async model — it no longer produces the same number regardless of whether the app runs one sync worker or sixteen async ones. Whichever candidate is tightest is reported as the bottleneck, and the "Bottleneck Analysis" section ranks the same candidate list, so the two sections of the page cannot disagree with each other.

This is still a static-analysis heuristic, not a load test — it has no visibility into CPU/memory limits, downstream database latency, or GC pauses. Treat it as a fast sanity check on where to look first, not a capacity-planning number to put in an SLA.

Design tokens (dark mode — same as TECH_STACK.html)

Accent colors (consistent with WORKFLOW.html reference output):

• Orange #f97316 — write/ingestion path, external sources
• Blue #3b82f6 — API layer, relational DBs
• Green #22c55e — read/query path, user-facing components
• Purple #a855f7 — processing, Slack, queues
• Pink #ec4899 — LLM / inference
• Indigo #818cf8 — vector stores
• Yellow #eab308 — evaluation, schedulers
• Red #ef4444 — Redis, bottlenecks
• Cyan #06b6d4 — embedding, I/O stats

Fallback (script not found)

If ~/.claude/skills/workflow-generator/scripts/analyze.py cannot be found, perform the analysis manually using your Read and Bash tools, then write WORKFLOW.html directly.

Manual analysis steps:

1. Detect framework — grep for fastapi, flask, django, express, gin, @SpringBoot
2. Detect workers — grep --workers, replicas:, pm2 instances in docker-compose / Procfiles
3. Detect gateway — look for nginx.conf, Caddyfile, traefik.yml
4. Extract rate limits — limit_req_zone, @limiter.limit, express-rate-limit
5. Extract async primitives — asyncio.Semaphore, run_in_executor, asyncio.gather
6. Detect LLM — ChatOpenAI, ChatAnthropic, request_timeout=, max_retries=
7. Detect storage — scan docker-compose, .env for postgres://, redis://, qdrant, pinecone
8. Detect queues — celery, bullmq, kafka, rabbitmq
9. Detect external sources — jira, slack, ado, github, stripe in source + env

Then write WORKFLOW.html using the exact design tokens above and the section structure: stat-row → architecture diagram → flow cards → concurrency table → bottleneck bars → footer.

Notes

• Always overwrite an existing WORKFLOW.html — never ask for confirmation
• Works on Python, Node.js, Go, Rust, Java, Ruby projects
• Architecture diagram adapts to what is detected: layers with no components are omitted
• Stat cards show only metrics that could be computed (skip if data unavailable)
• Never scan vendored or generated directories (node_modules, venv, .venv, site-packages, dist, build, .git, …) — only the project's own source
• Capacity figures are static-analysis heuristics (e.g. ~100 concurrent tasks per async worker), not load-test results — present them as estimates