archflow

Codebase Visualizer

Analyzes a codebase and produces beautiful, self-contained HTML architecture outputs with animated flow diagrams.

=================================================================== OUTPUT MODES

/archflow → Full architecture report (default) /archflow-diagram → Animated diagram only (legacy, self-contained) /archflow-slides → Slide deck presentation

=================================================================== WORKFLOW — FULL REPORT (default: /archflow)

1. ANALYZE Read references/analysis.md → scan the codebase Read references/layouts.md → decide the diagram layout pattern

2. THINK (commit to a visual direction before coding) Read references/design-system.md → CSS patterns library Read references/libraries.md → fonts, Mermaid, CDN imports Read references/design-qa.md → quality gates

   Pick: → A font pairing that matches the project character → A color palette aesthetic (Blueprint, Terminal Mono, etc.) → A background atmosphere (radial glow, dot grid, mesh)

   Do NOT default to the same choices every time. Each report should feel intentionally designed.

3. STRUCTURE Read references/animation.md → phase engine for the diagram Read references/navigation.md → TOC sidebar (if needed)

   Plan the report sections. Include at minimum: → Header (project name, description, date) → Executive summary → KPI metrics → Animated architecture diagram (MANDATORY — the hero section) → Component directory or data table → Supporting content as the project demands (data flow, benchmarks, external services, insights, etc.) → Code references

   Compose FREELY. Don't follow a rigid 10-section template. Add sections the project needs. Skip sections it doesn't. Create bespoke components (bar charts, comparison panels, distribution bars) when the data calls for them.

4. STYLE Write CUSTOM CSS for this specific report. Don't reuse a generic template — design each report uniquely. Use the patterns from design-system.md as building blocks, but adapt them to this project's needs.

   The animated diagram section uses its own CSS classes (.component, .arrow-line, .vert-line, etc.) — keep those as documented in design-system.md and animation.md.

5. DELIVER → Output to ./architecture-report.html → Single self-contained HTML file → External deps: Google Fonts CDN + optional Mermaid CDN → Present the file → Print a short summary

=================================================================== WORKFLOW — DIAGRAM ONLY (/archflow-diagram)

1. ANALYZE Read references/analysis.md → scan the codebase Read references/layouts.md → decide the diagram layout pattern

2. THINK Read references/design-system.md → CSS patterns + diagram classes Read references/animation.md → phase engine

   Pick: → A color palette aesthetic for the diagram → A background atmosphere → The layout pattern (pipeline, hub, or medallion)

   Use templates/ as REFERENCE EXAMPLES only — don't copy them rigidly. Compose the diagram HTML freely with custom CSS.

3. COMPOSE Write custom CSS + HTML for this specific diagram. Use the diagram component classes from design-system.md (.component, .arrow-line, .vert-line, .storage-pipeline, etc.) and the phase engine from animation.md. Adapt the layout to fit the actual codebase — don't force it into a template if the system has a different shape.

4. DELIVER → Output to ./architecture-diagram.html → Single self-contained HTML file → ZERO external dependencies (no CDN fonts, no Mermaid) → Self-contained fonts: 'JetBrains Mono', 'Fira Code', monospace → Present the file + short summary

Reference examples (for layout patterns, not rigid templates): templates/horizontal-pipeline.html → API / RAG / request-response templates/multi-agent-hub.html → orchestrator + parallel agents templates/medallion-pipeline.html → ETL / Delta Live Tables

=================================================================== WORKFLOW — SLIDE DECK (/archflow-slides)

1. Read references/analysis.md → analyze the codebase
2. Read references/layouts.md → decide the layout
3. Read references/design-system.md → CSS patterns
4. Read references/libraries.md → fonts, CDN imports
5. Read references/animation.md → phase engine
6. Read references/slide-patterns.md → slide system
7. Compose slide deck freely with animated diagram as hero slide
8. Output to ./architecture-slides.html
9. Present + summary

=================================================================== DESIGN PRINCIPLES

Think MAGAZINE, not JIRA. Think PRODUCT PAGE, not ADMIN PANEL.

→ Each report should feel INTENTIONALLY DESIGNED for this specific project. If you swapped the CSS between two reports and nobody would notice, you haven't designed anything. → TYPOGRAPHY IS THE DESIGN. Use at least 2 distinct font families. Mix serif display (Instrument Serif, Playfair Display) with sans-serif body. Add a third voice for quotes/callouts. Never use one font family for everything. → The design-system.md provides BUILDING BLOCKS, not templates. Compose unique CSS per project. Don't copy class definitions — design each component fresh, guided by the principles. → BACKGROUNDS CREATE ATMOSPHERE. Each section is a different room. Every section MUST have its own unique background treatment (radial gradient, linear sweep, texture). No uniform flat backgrounds across all sections. → Keep the palette TIGHT — 2 accent colors + neutrals. Don't use 6+. → Use GENEROUS whitespace — 40-80px section padding. Let it breathe. → Every section has a UNIQUE layout AND component shape. Don't repeat card grids. Mix: full-bleed, split panels, stat bars, entity lists, editorial quotes, terminal mockups, SVG charts. → The ANIMATED DIAGRAM is the hero section — maximum visual weight. → SINGLE-PAGE DIAGRAMS: prefer compact layouts where the full architecture is visible in 1-2 viewport scrolls. Use horizontal flow-rows for linear 4-7 layer systems; vertical stacks only when layers have nested sub-components. → ALL diagrams on the page highlight in SYNC during phase animation. → Apply the SQUINT TEST: sections must be distinct when blurred. → Apply the SWAP TEST: hierarchy must work without color alone. → If it looks like a Bootstrap dashboard, redesign it.

=================================================================== OUTPUT RULES

ALL MODES: → Single self-contained HTML file → Use real class/function/module names — never generic placeholders → Use real external service names (Azure Cosmos DB, not "Database") → Phase count: 4-8 phases (sweet spot for animation readability) → Max 8 components per row before layout gets crowded → After writing, call present_files

REPORT MODE: → File: ./architecture-report.html → External deps: Google Fonts CDN + optional Mermaid CDN → Dark/light theme toggle with localStorage persistence → Responsive layout (works on mobile) → prefers-reduced-motion support

DIAGRAM-ONLY MODE: → File: ./architecture-diagram.html → Fully self-contained — zero external dependencies

SLIDE MODE: → File: ./architecture-slides.html → External deps: Google Fonts CDN

=================================================================== ANALYSIS DEPTH

For diagram-only: components, data flows (4-8 phases), external services, 3-4 insights.

For report/slides: ALSO extract component counts, file paths, layer classifications, detailed data flow descriptions, 4-6 insights, and list of key files analyzed. Create bespoke visualizations when the data supports it (benchmarks, metrics, comparison panels, distribution charts).