Vulcan Application Modernization Roadmap

Overview

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.

Guiding Principles

1. Incremental Progress: Prefer smaller, focused changes over sweeping rewrites
2. Measured Outcomes: Define clear success criteria for each phase
3. Backward Compatibility: Maintain functionality throughout the migration
4. Testing First: Establish comprehensive tests before making significant changes
5. Ruthless Prioritization: Defer non-essential improvements to future phases
6. Continuous Integration: Keep the application deployable at all times
7. Technical Debt Reduction: Address existing issues before adding new complexity
8. Evidence-Based Decisions: Use metrics and benchmarks to guide architectural choices

Phase 0: Rails 8 and Infrastructure Modernization (COMPLETED)

Objectives

• ✅ 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

Completed Tasks

• 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 expect API
• Update RSpec Rails from 4.0 to 6.0
• OIDC auto-discovery implementation
• Docker image optimization (6.5GB → 1.76GB)
• All 198 tests passing

Success Criteria Achieved

• ✅ 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

Decision Points

• 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

Phase 0.5: Development Process Enhancement

Objectives

• Establish standardized linting and code quality tools
• Implement automated security scanning
• Enhance testing infrastructure and processes
• Create baseline metrics for code quality and security

Tasks

• 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

Success Criteria

• 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

Decision Points

• 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

Phase 1: Rails Upgrade and Backend Modernization

Objectives

• Upgrade Rails to latest version
• Optimize database design and performance
• Create comprehensive API foundation
• Enhance backend test coverage
• Address prioritized security vulnerabilities

Tasks

• 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

Success Criteria

• 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

Decision Points

• 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

Phase 2: Vue 2 to Vue 3 Transition

Objectives

• 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

Tasks

• 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

Success Criteria

• 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

Decision Points

• 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

Phase 3: Component Architecture Modernization

Objectives

• 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

Tasks

• 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)

Success Criteria

• 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

Decision Points

• 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

Phase 3.5: Runtime Configuration Management

Objectives

• 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

Context

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.

Tasks

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

Technology Stack

• 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 Architecture

# 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

Success Criteria

• 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

Decision Points

• 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

Dependencies

• BLOCKING: Phase 0 completion (Webpacker migration, Ruby 3.2+ upgrade)
• REQUIRED: Rails 7+ and modern asset pipeline
• OPTIONAL: Redis/Memcached for enhanced settings caching

Estimated Effort

Total: 8-12 hours across 2-3 sprints Priority: Medium (after infrastructure modernization) References: Issue #673 - Comprehensive implementation plan

Phase 4: Testing and Development Infrastructure

Objectives

• Enhance testing infrastructure for better reliability
• Implement CLI architecture improvements
• Overhaul configuration system
• Improve development workflow

Tasks (from separate workstream branches)

• 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

Success Criteria

• Test suite runs reliably across all platforms
• CLI provides intuitive developer experience
• Configuration system is validated and secure
• Development workflow is streamlined

Decision Points

• TESTING: Playwright vs other E2E testing frameworks
• CLI: TTY toolkit selection (TTY::Prompt, etc.)
• CONFIG: rails-settings-cached vs custom solution

Phase 5: Advanced Features and Optimizations

Objectives

• Implement SSR or hybrid rendering if beneficial
• Enhance accessibility compliance
• Optimize performance for large datasets
• Improve offline capabilities
• Address remaining GitHub issues

Tasks

• 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

Success Criteria

• 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

Decision Points

• 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

Prioritization Framework

When making decisions about feature implementation or technical approaches, use the following framework:

Must-Have (Required for this phase)

• Features critical to core application functionality
• Security-related improvements
• Performance issues affecting usability
• Blocking dependencies for future phases

Should-Have (Important but not blocking)

• Significant developer experience improvements
• Performance optimizations with measurable impact
• Features with high user value and moderate implementation cost

Could-Have (Desirable but deferrable)

• Nice-to-have features with limited user impact
• Refactoring that improves code quality but doesn't affect functionality
• Performance optimizations for edge cases

Won't-Have (Explicitly deprioritized)

• Features requiring significant new technology adoption
• Changes requiring major architectural shifts
• Optimizations with minimal measurable impact
• Features not aligned with application core purpose

Risk Management

Technical Risks

• 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

Process Risks

• 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

Maintenance and Updates

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

Conclusion

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.