🚀 EPIC: Rebuild GitHub Pages Federation with Incremental Architecture #2
Description
🚀 EPIC: Rebuild GitHub Pages Federation with Incremental Architecture
📋 Overview
This epic addresses critical issues in the current GitHub Pages federation and implements a new incremental build architecture that supports independent updates of corporate site and product documentation.
🚨 Current Problems Identified
Technical Issues
- ❌ Wrong content deployment: Web Terminal docs appear in root instead of corporate site
- ❌ Missing documentation: All /docs/{product}/ URLs return 404 errors
- ❌ CSS/styling broken: Sites display as "bare HTML" without styles
- ❌ Overwrite architecture: Each product build overwrites entire site instead of adding incrementally
Workflow Issues
- ❌ Hugo Templates Framework limitation: Does not support incremental builds (creates full site each time)
- ❌ Federation workflow logic: Sequential builds overwrite previous results
- ❌ No separation of concerns: Corporate and docs updates interfere with each other
🎯 Success Criteria
Technical Requirements
- ✅ Corporate site correctly displays in root (/)
- ✅ All product documentation accessible via /docs/{product}/
- ✅ Proper CSS styling and static assets loading
- ✅ Independent updates (corporate changes don't affect docs and vice versa)
Operational Requirements
- ✅ Automated deployment from repository changes
- ✅ Build time < 3 minutes for each component
- ✅ Reliable error handling and rollback capabilities
- ✅ Clear monitoring and debugging capabilities
🏗️ Architecture Overview
New Incremental Build Strategy
Corporate Workflow:
├── Download existing GitHub Pages
├── Build corporate site → temp/
├── Merge temp/ → existing/ (preserve /docs/)
└── Deploy merged result
Documentation Workflow:
├── Download existing GitHub Pages
├── Build all docs → temp/docs/
├── Merge temp/docs/ → existing/docs/ (preserve root)
└── Deploy merged result
Hugo Templates Adaptations
- Configure proper destination paths for federated deployment
- Implement merge logic for incremental updates
- Fix CSS/static asset paths for sub-directory deployment
📊 Child Issues Breakdown
This epic is divided into 6 sequential phases:
- 🔍 Investigation & Design - Deep analysis and architecture planning
- ⚙️ Hugo Templates Enhancement - Framework improvements for federation
- 🏢 Corporate Site Workflow - Independent corporate site deployment
- 📚 Documentation Workflow - Federated documentation deployment
- 🧪 Integration Testing - End-to-end testing and validation
- 🚀 Production Deployment - Go-live and monitoring setup
🔗 Dependencies
- Hugo Templates Framework (info-tech-io/hugo-templates)
- Corporate content (info-tech-io/info-tech)
- Product documentation (quiz, hugo-templates, web-terminal, info-tech-cli repos)
- GitHub Actions infrastructure
- GitHub Pages hosting
📈 Success Metrics
- Deployment Success Rate: 100% for both corporate and docs workflows
- Build Performance: < 3 minutes per workflow
- Site Availability: 99.9% uptime for all federation components
- Content Accuracy: 100% correct content deployment in designated paths
🏁 Definition of Done
- All child issues completed and verified
- Both corporate and documentation workflows functional
- Full federation accessible and styled correctly
- Automated testing pipeline established
- Documentation updated with new architecture
- Legacy workflows safely removed
Epic Owner: AI Assistant
Priority: High
Timeline: 1-2 weeks
Status: Planning Phase