This document outlines the complete modernization strategy for the Vulcan application, covering backend, middleware, and frontend components. It establishes a phased approach with clear milestones, decision points, and success criteria to keep the migration focused and manageable.
- Incremental Progress: Prefer smaller, focused changes over sweeping rewrites
- Measured Outcomes: Define clear success criteria for each phase
- Backward Compatibility: Maintain functionality throughout the migration
- Testing First: Establish comprehensive tests before making significant changes
- Ruthless Prioritization: Defer non-essential improvements to future phases
- Continuous Integration: Keep the application deployable at all times
- Technical Debt Reduction: Address existing issues before adding new complexity
- Evidence-Based Decisions: Use metrics and benchmarks to guide architectural choices
- ✅ Complete Rails 8.0.2.1 upgrade
- ✅ Complete the migration from Webpacker to jsbundling-rails
- ✅ Upgrade Ruby to 3.3.9 and Node.js to 22 LTS
- ✅ Fix all security vulnerabilities and pass SonarCloud quality gate
- ✅ Establish OIDC auto-discovery for simplified authentication
- Progressive Rails upgrade: 7.0.8.7 → 7.1.5.2 → 7.2.2.2 → 8.0.2.1
- Ruby upgrade: 3.1.6 → 3.3.9
- Node.js upgrade: 16 → 22 LTS
- Migrate from Webpacker to jsbundling-rails with esbuild
- Fix SQL injection vulnerability in Component#duplicate_rules
- Implement Rails 8 strong parameters
expectAPI - Update RSpec Rails from 4.0 to 6.0
- OIDC auto-discovery implementation
- Docker image optimization (6.5GB → 1.76GB)
- All 198 tests passing
- ✅ Rails 8.0.2.1 running in production
- ✅ All assets build with jsbundling-rails (Webpacker removed)
- ✅ All features function identically to pre-migration
- ✅ Security vulnerabilities fixed (SonarCloud passing)
- ✅ OIDC configuration simplified to 4 environment variables
- ✅ Docker builds optimized with jemalloc
- GO/NO-GO: Proceed to next phase only when all entry points are successfully migrated
- SCOPE: Identify any critical technical debt to address immediately
- PRIORITIZATION: Use security findings to help determine next phase ordering
- Establish standardized linting and code quality tools
- Implement automated security scanning
- Enhance testing infrastructure and processes
- Create baseline metrics for code quality and security
- Implement standardized linting for Ruby and JavaScript
- Set up automated static analysis tools (Brakeman, ESLint, etc.)
- Configure security scanning in CI pipeline
- Establish test coverage requirements and tools
- Create pre-commit hooks for consistency
- Document code standards and best practices
- Set up performance monitoring baselines
- Functional CI pipeline with linting, testing, and security scanning
- Code quality metrics established and documented
- Pre-commit hooks prevent common issues
- Test coverage meets established threshold (recommend >70%)
- Documented procedures for security review
- TOOLS: Select appropriate linting and security tools for the stack
- STRICTNESS: Determine appropriate levels of enforcement vs. warning
- NEXT PHASE: Determine whether Rails or Vue upgrades should be prioritized next based on security findings
- Upgrade Rails to latest version
- Optimize database design and performance
- Create comprehensive API foundation
- Enhance backend test coverage
- Address prioritized security vulnerabilities
- Audit and update all Rails dependencies
- Upgrade Ruby version if needed
- Implement Rails upgrade in stages (follow major version path)
- Audit database design and implement optimizations
- Design and implement RESTful API for all data requirements
- Consider JSON schema validation tools (similar to Zod)
- Add proper serialization/deserialization with type validation
- Implement proper authentication for API endpoints
- Create comprehensive API documentation
- Add API versioning structure for future compatibility
- Restore any backend simplifications to production settings
- All Rails tests pass on the upgraded version
- Database queries show measurable performance improvements
- Complete API coverage for existing functionality
- API performance meets established benchmarks
- Authentication security review completed
- No remaining temporary simplifications from migration phase
- ARCHITECTURE: Decide on API-only mode versus hybrid approach
- SCHEMA VALIDATION: Evaluate benefits of schema validation libraries
- DATABASE: Decide on specific optimization techniques (indexing, denormalization, etc.)
- SERIALIZATION: Choose between fast_jsonapi, jbuilder, or alternative
- Upgrade Vue from 2.x to 3.x
- Replace bootstrap-vue with bootstrap-vue-3
- Implement comprehensive frontend testing
- Maintain feature parity throughout the upgrade
- Address prioritized frontend security issues
- Update package.json with Vue 3 and related dependencies
- Choose and implement frontend testing framework (Vue Test Utils, Playwright, etc.)
- Create adapter layer for backward compatibility where needed
- Migrate global Vue plugins and configuration
- Replace bootstrap-vue components with bootstrap-vue-3 equivalents
- Update component initialization and mounting
- Refactor simple components to use Composition API
- Create test suite for critical UI components and interactions
- Revise styles to accommodate bootstrap-vue-3 differences
- Restore any frontend simplifications to production patterns
- All Vue components render and function correctly
- Frontend test coverage meets established threshold (recommend >70%)
- No degradation in performance benchmarks
- No user-visible differences in UI or behavior
- No remaining temporary simplifications from migration phase
- TESTING APPROACH: Choose between component testing, E2E testing, or both
- SELECTIVE REFACTOR: Identify which components benefit most from Composition API conversion
- LIBRARY EVALUATION: Re-evaluate bootstrap-vue-3 vs alternatives based on implementation experience
- Implement modern state management solution
- Evaluate and improve component architecture
- Establish clear data flow patterns
- Improve component reusability
- Enhance client-side performance
- Address architectural security concerns
- Conduct Vue component architecture review
- Introduce proper state management (Pinia recommended)
- Create services layer for API interactions
- Refactor components to follow consistent patterns
- Consider TypeScript adoption for enhanced reliability
- Improve error handling and recovery
- Optimize component rendering and reactivity
- Apply security best practices to frontend architecture
- Consider schema validation for client-side data (similar to Zod)
- Measurable performance improvements in key interactions
- Reduced code duplication and complexity
- Improved developer experience metrics
- Enhanced type safety throughout the application
- Frontend security posture improved
- Component architecture follows established best practices
- TYPING: Evaluate effort/value ratio of TypeScript adoption
- ARCHITECTURE: Consider modular architecture for larger application sections
- STATE: Assess centralized vs. component-local state management needs
- VALIDATION: Decide on client-side validation approach
- Implement dynamic runtime configuration management comparable to Heimdall2
- Enable zero-restart administrative operations
- Provide web-based administration interface
- Support bulk operations for users and STIG/SRG management
- Enhance deployment and scaling capabilities
Based on user feedback (Issue #654) comparing Vulcan to Heimdall2's administrative ease, this phase addresses the gap in runtime configuration management. The implementation leverages proven Rails gems to deliver robust administration capabilities rapidly.
Phase 3.5.1: Foundation (4-6 hours)
- Install and configure rails-settings-cached for database-backed configuration
- Install and configure ActiveAdmin for web-based administration interface
- Create admin authentication and authorization system
- Migrate safe settings from environment variables to database-backed configuration:
- Welcome text and contact information
- Session timeout settings (with validation)
- User registration and project creation permissions
- Email template customizations
- Create basic admin interface for settings management
Phase 3.5.2: User Management (2-3 hours)
- Build comprehensive admin interface for user management
- Implement batch operations (bulk admin assignment, account confirmation)
- Add user search, filtering, and management capabilities
- Create audit logging for all administrative actions
Phase 3.5.3: Feature Flags (1-2 hours)
- Install and configure Flipper with web UI for feature management
- Implement feature flags for experimental features
- Enable A/B testing capabilities for UI improvements
- Create gradual feature rollout mechanisms
Phase 3.5.4: Bulk Operations (2-4 hours)
- Implement STIG/SRG bulk import and update operations
- Create component batch management capabilities
- Add automated maintenance task scheduling
- Build background job monitoring interface
- rails-settings-cached: Database-backed configuration with automatic caching
- ActiveAdmin: Complete admin interface framework (battle-tested)
- Flipper + Flipper-UI: Feature flags and runtime feature management
- Background jobs: For bulk operations and maintenance tasks
# Security-critical settings (remain environment variables):
- Database connections (DATABASE_URL)
- OIDC client secrets (VULCAN_OIDC_CLIENT_SECRET)
- Encryption keys and LDAP credentials
# Administrative settings (move to database-backed):
- UI customizations and welcome text
- Session timeout and user permissions
- Email templates and notification settings
- Feature flags for experimental features- Zero-restart configuration changes for administrative settings
- Web-based admin interface accessible to authorized users
- Bulk user operations (admin assignment, confirmation, etc.) functional
- Feature flags enable safe experimental feature deployment
- STIG/SRG bulk import and management capabilities operational
- All administrative changes include comprehensive audit logging
- Settings cached automatically (< 10ms retrieval time)
- Admin interface responsive (< 2s page loads)
- Security boundaries maintained between critical and administrative settings
- SECURITY: Validate separation between security-critical and administrative settings
- PERFORMANCE: Ensure caching strategy meets production scale requirements
- AUTHORIZATION: Determine granular permission levels for admin interface
- INTEGRATION: Assess integration with existing authentication systems
- BLOCKING: Phase 0 completion (Webpacker migration, Ruby 3.2+ upgrade)
- REQUIRED: Rails 7+ and modern asset pipeline
- OPTIONAL: Redis/Memcached for enhanced settings caching
Total: 8-12 hours across 2-3 sprints Priority: Medium (after infrastructure modernization) References: Issue #673 - Comprehensive implementation plan
- Enhance testing infrastructure for better reliability
- Implement CLI architecture improvements
- Overhaul configuration system
- Improve development workflow
- Testing Infrastructure Enhancement
- Hierarchical test runner implementation
- Cross-platform test containers
- Test organization improvements
- Enhanced test isolation
- Expanded Playwright test suite
- CLI Architecture
- TTY-based CLI with improved UX
- Command registry implementation
- Shell escaping security enhancements
- Standardized command formats
- Configuration System Overhaul
- Rails-CLI configuration bridge
- Environment-specific configuration
- Configuration validation
- Secret management improvements
- Test suite runs reliably across all platforms
- CLI provides intuitive developer experience
- Configuration system is validated and secure
- Development workflow is streamlined
- TESTING: Playwright vs other E2E testing frameworks
- CLI: TTY toolkit selection (TTY::Prompt, etc.)
- CONFIG: rails-settings-cached vs custom solution
- Implement SSR or hybrid rendering if beneficial
- Enhance accessibility compliance
- Optimize performance for large datasets
- Improve offline capabilities
- Address remaining GitHub issues
- Evaluate SSR options (Nuxt integration or hybrid approach)
- Conduct accessibility audit and address issues
- Implement performance optimizations for data-heavy screens
- Enhance caching strategies for API responses
- Implement offline-first capabilities where appropriate
- Consider PWA features for improved user experience
- Address remaining GitHub issues from initial triage
- Comprehensive security review of entire application
- Application meets WCAG accessibility guidelines
- Significant performance improvements for large datasets
- Reduced server load through efficient caching
- Improved user experience in limited-connectivity scenarios
- All prioritized GitHub issues resolved
- Security posture meets or exceeds industry standards
- FRAMEWORK: Assess value of Nuxt or similar framework adoption
- AUDIENCE: Determine importance of offline capabilities for user base
- COMPLEXITY: Evaluate complexity/benefit ratio of SSR implementation
- PRIORITIES: Determine which remaining GitHub issues to address
When making decisions about feature implementation or technical approaches, use the following framework:
- Features critical to core application functionality
- Security-related improvements
- Performance issues affecting usability
- Blocking dependencies for future phases
- Significant developer experience improvements
- Performance optimizations with measurable impact
- Features with high user value and moderate implementation cost
- Nice-to-have features with limited user impact
- Refactoring that improves code quality but doesn't affect functionality
- Performance optimizations for edge cases
- Features requiring significant new technology adoption
- Changes requiring major architectural shifts
- Optimizations with minimal measurable impact
- Features not aligned with application core purpose
- Dependency Conflicts: Evaluate all dependencies for Vue 3 compatibility
- Performance Degradation: Benchmark before and after major changes
- API Breaking Changes: Version APIs and maintain backward compatibility
- Data Migration: Plan for seamless data model transitions
- Scope Creep: Use this document to focus efforts on planned work
- Knowledge Gaps: Provide training for new technologies
- Testing Gaps: Prioritize test coverage before major changes
- Timeline Pressure: Explicitly defer non-essential features
This roadmap is a living document and should be revisited at the completion of each phase. Updates should include:
- Lessons learned from completed phases
- Refinements to upcoming phase plans
- Adjustments to priorities based on user feedback
- Updates to technical approach based on evolving best practices
By following this roadmap, we will modernize the Vulcan application in a controlled, incremental manner that minimizes risk while maximizing value. Regular evaluation of progress against this plan will help keep the team focused on the most important improvements.
Remember: The most important outcome is a stable, maintainable application that meets user needs, not perfect adherence to any specific technology or architecture.