docs-blackroad-io/.github/workflows/visual-docs-bot.yml

name: 🎨 Visual Docs Bot

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  workflow_dispatch:

jobs:
  generate-visual-docs:
    runs-on: ubuntu-latest
    name: Generate Visual Documentation

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: |
          npm install -g @canva/cli
          pip3 install pyyaml requests

      - name: Generate architecture diagrams
        run: |
          echo "🎨 Generating visual documentation..."

          # Create docs directory
          mkdir -p docs/visual

          # Generate diagrams from codebase structure
          python3 << 'PYTHON'
import os
import json
import yaml
from pathlib import Path

def analyze_repo_structure():
    """Analyze repository structure for visualization"""
    structure = {
        "name": os.path.basename(os.getcwd()),
        "components": [],
        "workflows": [],
        "configs": []
    }

    # Find key files
    for root, dirs, files in os.walk('.', topdown=True):
        dirs[:] = [d for d in dirs if not d.startswith('.') and d != 'node_modules']

        for file in files:
            if file.endswith(('.yml', '.yaml')):
                structure["workflows"].append(os.path.join(root, file))
            elif file in ['package.json', 'requirements.txt', 'Dockerfile']:
                structure["configs"].append(os.path.join(root, file))

    return structure

def generate_diagram_spec(structure):
    """Generate Canva-compatible diagram specification"""
    return {
        "type": "architecture_diagram",
        "title": f"{structure['name']} Architecture",
        "components": structure["components"],
        "connections": [],
        "metadata": {
            "workflows": len(structure["workflows"]),
            "configs": len(structure["configs"])
        }
    }

if __name__ == "__main__":
    structure = analyze_repo_structure()
    diagram_spec = generate_diagram_spec(structure)

    with open('docs/visual/architecture-spec.json', 'w') as f:
        json.dump(diagram_spec, f, indent=2)

    print(f"✅ Generated architecture spec for {structure['name']}")
PYTHON

      - name: Create visual documentation index
        run: |
          cat > docs/visual/README.md << 'DOCS'
# 🎨 Visual Documentation

This directory contains automatically generated visual documentation.

## Generated Diagrams

- **Architecture Diagram**: System component overview
- **Workflow Diagrams**: CI/CD and automation flows
- **Dependency Graph**: Package and module relationships

## Automation

Visual docs are automatically updated on:
- Push to main/master branch
- Pull request creation
- Manual workflow dispatch

Generated by: Visual Docs Bot 🤖
DOCS

      - name: Commit visual docs
        if: github.event_name == 'push'
        run: |
          git config --local user.email "blackroad-bot@users.noreply.github.com"
          git config --local user.name "BlackRoad Visual Docs Bot"

          git add docs/visual/ || true
          git diff --staged --quiet || git commit -m "🎨 Update visual documentation [skip ci]"
          git push || echo "No changes to push"

      - name: Comment on PR
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '🎨 **Visual Documentation Generated**\n\nArchitecture diagrams have been created for this change. Check `docs/visual/` for details.'
            });

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: visual-docs
          path: docs/visual/
          retention-days: 30