Submodule Dashboard HTML Generator - Architecture
System Overview
┌─────────────────────────────────────────────────────────────────┐
│ submodule-dashboard-html.py │
└─────────────────────────────────────────────────────────────────┘
│
│ imports functions
▼
┌─────────────────────────────────────────────────────────────────┐
│ submodule-health-check.py │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ find_rollout_master_root() │ │
│ │ - Locate rollout-master directory │ │
│ │ - Support running from any subdirectory │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ check_git_status(path) │ │
│ │ - Uncommitted changes │ │
│ │ - Unpushed commits │ │
│ │ - Branch name │ │
│ │ - Behind/ahead counts │ │
│ │ - Last commit timestamp │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ check_symlinks(path) │ │
│ │ - .coditect exists │ │
│ │ - .coditect accessible │ │
│ │ - .claude exists │ │
│ │ - Framework accessible │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ calculate_health_score(git_status, symlink_status) │ │
│ │ - Start at 100 │ │
│ │ - Deduct for issues │ │
│ │ - Return score + issues + warnings │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ check_submodule_health(path) → HealthStatus │ │
│ │ - Orchestrate all checks │ │
│ │ - Return comprehensive status │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Data Flow
START
│
├─→ Find rollout-master root
│
├─→ Scan submodules/ directory
│ └─→ For each category (cloud, core, dev, etc.)
│ └─→ For each submodule
│
├─→ For each submodule path:
│ ├─→ check_git_status()
│ ├─→ check_symlinks()
│ ├─→ calculate_health_score()
│ └─→ Create HealthStatus object
│
├─→ Collect all HealthStatus objects
│
├─→ generate_html_dashboard()
│ ├─→ Calculate summary stats
│ ├─→ Build HTML structure
│ ├─→ Inline CSS (dark theme, responsive)
│ ├─→ Inline JavaScript (sorting, filtering)
│ └─→ Return complete HTML string
│
└─→ Output to file or stdout
HTML Dashboard Structure
┌───────────────────────────────────────────────────────────────┐
│ HEADER │
│ CODITECT Submodule Health Dashboard │
│ Generated: 2026-02-02 14:30:00 │
└───────────────────────────────────────────────────────────────┘
┌──────────┬──────────┬──────────┬──────────┬──────────┬────────┐
│ Total │ Clean │ Dirty │ Stale │ Unpushed │ Avg │
│ Repos │ (✓) │ (⚠) │ (↓) │ (↑) │ Score │
│ 74 │ 45 │ 12 │ 8 │ 15 │ 82.5 │
└──────────┴──────────┴──────────┴──────────┴──────────┴────────┘
┌───────────────────────────────────────────────────────────────┐
│ CONTROLS (sticky) │
│ │
│ [Search: ___________________________] │
│ │
│ [All] [Cloud] [Core] [Dev] [Docs] [GTM] [Integrations] ... │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ TABLE (sortable columns) │
│ │
│ Name ▲ | Category | Branch | Status | ... | Health | Symlinks│
│ ──────────────────────────────────────────────────────────── │
│ repo-1 | Cloud | main | Clean | ... | ████ 95 | ✓✓ │
│ repo-2 | Core | dev | Dirty | ... | ███▒ 72 | ✓✗ │
│ repo-3 | Dev | main | Clean | ... | █████ 100 | ✓✓ │
│ ... │
└───────────────────────────────────────────────────────────────┘
Component Interaction
┌─────────────────────────────────────────────────────────────┐
│ Browser (Client) │
│ │
│ ┌────────────────────┐ ┌────────────────────┐ │
│ │ Search Input │ │ Category Tabs │ │
│ │ (keyup event) │ │ (click event) │ │
│ └────────┬───────────┘ └────────┬───────────┘ │
│ │ │ │
│ └───────┬───────────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Filter Function │ │
│ │ - Match search │ │
│ │ - Match category│ │
│ │ - Show/hide rows│ │
│ └──────────────────┘ │
│ │
│ ┌────────────────────────────────────────┐ │
│ │ Table Headers (sortable) │ │
│ │ (click event) │ │
│ └────────┬───────────────────────────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Sort Function │ │
│ │ - Get column │ │
│ │ - Toggle asc/desc│ │
│ │ - Sort rows │ │
│ │ - Re-render │ │
│ └──────────────────┘ │
│ │
│ ┌────────────────────────────────────────┐ │
│ │ Health Bars │ │
│ │ (CSS animation on page load) │ │
│ └────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Health Score Calculation
Start: 100 points
│
├─→ Uncommitted changes? → -5 per change (max -20)
├─→ Unpushed commits? → -5 per commit (max -20)
├─→ Behind remote? → -10
├─→ Detached HEAD? → -15
├─→ Not on main? → -5
├─→ .coditect missing? → -20
├─→ .coditect broken? → -20
└─→ Framework broken? → -10
↓
Final Score: 0-100
│
├─→ >= 80 → Green (healthy)
├─→ 50-79 → Yellow (warning)
└─→ < 50 → Red (critical)
CSS Architecture
Global Styles
├─→ Dark Theme
│ ├─→ Background: #1a1a1a
│ ├─→ Text: #e0e0e0
│ └─→ Accents: #667eea
│
├─→ Typography
│ ├─→ Font: Segoe UI
│ └─→ Sizes: responsive
│
├─→ Layout
│ ├─→ Grid (summary cards)
│ ├─→ Flex (tabs, controls)
│ └─→ Sticky (header, controls)
│
├─→ Components
│ ├─→ Cards (summary)
│ ├─→ Badges (status)
│ ├─→ Bars (health score)
│ ├─→ Table (data)
│ └─→ Tabs (categories)
│
└─→ Responsive
├─→ Desktop: full layout
├─→ Tablet: 2-column cards
└─→ Mobile: single column
JavaScript State Management
State
├─→ currentSort
│ ├─→ column: string
│ └─→ direction: 'asc' | 'desc'
│
├─→ currentCategory: string
│ └─→ 'all' | 'cloud' | 'core' | ...
│
└─→ searchTerm: string
└─→ Updated on keyup
Event Handlers
├─→ searchBox.input
│ └─→ Filter rows by name + category
│
├─→ tabButton.click
│ └─→ Set category + filter rows
│
├─→ tableHeader.click
│ ├─→ Update sort state
│ ├─→ Sort rows
│ └─→ Re-render table
│
└─→ window.load
└─→ Animate health bars
File Generation Flow
Python Process
│
├─→ Import health check module
├─→ Parse command line args
├─→ Find rollout-master root
├─→ Scan for submodules
├─→ Check each submodule (parallel possible)
├─→ Collect HealthStatus objects
│
├─→ Generate HTML string
│ ├─→ Calculate stats
│ ├─→ Format timestamp
│ ├─→ Build summary cards
│ ├─→ Build category tabs
│ ├─→ Build table rows
│ ├─→ Embed CSS
│ └─→ Embed JavaScript
│
└─→ Write to output
├─→ If --output: write file
├─→ If --open: open browser
└─→ Else: print stdout
Performance Characteristics
Time Complexity
├─→ Submodule scanning: O(n) where n = # submodules
├─→ Health checking: O(n * m) where m = # git commands
├─→ HTML generation: O(n)
├─→ Browser rendering: O(n)
└─→ Table sorting: O(n log n)
Space Complexity
├─→ Health status storage: O(n)
├─→ HTML string: O(n)
└─→ DOM elements: O(n)
Optimization Points
├─→ Parallel health checks (future)
├─→ Cached git status (future)
├─→ Incremental rendering (future)
└─→ Virtual scrolling (future)
Security Considerations
Input Validation
├─→ Output path sanitization
├─→ No user input in HTML (XSS safe)
└─→ No remote data fetching
File System Access
├─→ Read-only git operations
├─→ No file modifications
└─→ No destructive operations
Browser Security
├─→ No external scripts
├─→ No external styles
├─→ No network requests
└─→ Self-contained HTML
Integration Points
CI/CD Pipeline
├─→ Generate dashboard
├─→ Upload as artifact
└─→ Publish to web server
Monitoring Systems
├─→ Parse health scores
├─→ Alert on low scores
└─→ Track trends
Git Hooks
├─→ Pre-commit: check health
├─→ Post-commit: regenerate
└─→ Pre-push: validate
Web Deployment
├─→ Static file hosting
├─→ S3/GCS upload
└─→ CDN distribution
Future Architecture Enhancements
Planned Features
├─→ Historical data tracking
│ └─→ Store health scores over time
│
├─→ Trend graphs
│ └─→ Chart.js integration
│
├─→ GitHub API integration
│ ├─→ PR counts
│ ├─→ Issue counts
│ └─→ CI status
│
├─→ Export formats
│ ├─→ CSV export
│ ├─→ JSON export
│ └─→ PDF report
│
└─→ Real-time updates
├─→ WebSocket support
└─→ Auto-refresh
Author: Claude (Sonnet 4.5) Date: 2026-02-02 Version: 1.0.0