Rustelo/docs/guides/new-workflows.md

New Development Workflows - Unified Template Architecture

🎯 Overview

This document outlines the new development workflows enabled by the unified template architecture. The new system transforms how you develop, customize, and maintain Rustelo projects through:

• Layered override system for safe customization
• Feature-aware tooling that adapts to your project
• Framework integrity protection for safe updates
• Unified CLI for all project operations

🚀 Core Workflows

1. Project Creation Workflow

New Project from Scratch

# Create new project with features
cargo rustelo new my-saas \
  --template webapp \
  --features analytics,smart-build,debugging-tools \
  --database postgres \
  --styling tailwind

# What happens automatically:
# ✅ Project structure created with layered config
# ✅ Features integrated with proper templates  
# ✅ Tooling configured (justfile, CSS, package.json)
# ✅ Integrity protection enabled
# ✅ CI/CD templates added

Start Development Immediately

cd my-saas

# One-command development setup
just setup

# Start full development environment
just dev-full

# Features automatically active:
# - Analytics dashboard on http://localhost:3001
# - Smart build caching enabled
# - Debugging tools with browser log capture
# - Hot reload for all file types

2. Feature Management Workflow

Adding Features During Development

# Add new feature to existing project
cargo rustelo add auth

# Interactive feature configuration
✅ Auth feature will be added to my-saas
📋 Select authentication methods:
  [x] JWT tokens
  [x] OAuth2 (Google, GitHub)
  [ ] 2FA/TOTP
  [ ] Magic links

📋 Database integration:
  [x] User model and migrations
  [x] Session management
  [x] Role-based access control

🔧 Installing auth feature...
✅ Added dependencies to Cargo.toml
✅ Created config/features/auth/
✅ Updated justfile with auth commands
✅ Added auth components to src/components/features/auth/
✅ Created database migrations
✅ Updated UnoCSS with auth styles

🚀 Feature ready! Try: just auth-setup

Feature-Specific Development

# Work on specific feature
just auth-dev          # Start auth development server
just auth-test          # Run auth-specific tests  
just auth-migrate       # Run auth database migrations
just auth-demo          # Start feature demo/playground

# Analytics for feature development
just analytics-report   # View auth feature metrics

3. Customization Workflow

Safe Template Customization

# See what can be customized
cargo rustelo list-overrides

# Override a template safely
cargo rustelo override template justfile

# Template copied to config/local/justfile
# Edit with your customizations - they'll take precedence
# Framework updates won't overwrite your changes

# Example local justfile addition:
echo '
# Custom deployment command for my-saas
deploy-staging:
    @echo "🚀 Deploying to staging..."
    docker build -t my-saas:staging .
    kubectl apply -f k8s/staging/
' >> config/local/justfile

Component Override System

# Override framework component
cargo rustelo override component NavBar

# Creates src/components/local/NavBar.rs with current implementation
# Customize without breaking updates:

// src/components/local/NavBar.rs
#[component]
pub fn NavBar() -> impl IntoView {
    view! {
        <nav class="my-custom-nav-style">
            <div class="brand">{"My SaaS"}</div>
            // Your customizations here
        </nav>
    }
}

Configuration Layer System

# Local configuration (highest precedence)
echo 'brand_color = "#ff6b6b"' >> config/local/app.toml

# Feature configuration
echo '[dashboard]
refresh_interval = 30' >> config/features/analytics/config.toml

# Resolution order: Local > Feature > Template > Framework
cargo rustelo trace config brand_color
# Output: config/local/app.toml (value: "#ff6b6b")

4. Quality Assurance Workflow

Continuous Quality Checks

# One command for comprehensive quality validation
just quality

# Runs in parallel:
# ✅ Code formatting (rustfmt)
# ✅ Linting (clippy with strict settings)  
# ✅ Tests (unit + integration)
# ✅ Framework integrity validation
# ✅ Security audit
# ✅ Performance benchmarks (if enabled)
# ✅ Documentation generation

Pre-commit Workflow (Automatic)

# Commit triggers automatic validation
git add .
git commit -m "Add user authentication"

# Pre-commit hook runs:
# 🔍 Framework integrity check
# 🧪 Quick test suite
# 📝 Format check
# 🔒 Security scan

# Commit blocked if issues found:
❌ Framework integrity validation failed!
💡 Run 'cargo rustelo integrity repair' to fix common issues
💡 Run 'cargo rustelo integrity validate --detailed' for more info

5. Team Collaboration Workflow

Shared Team Configuration

# Team lead sets up shared configuration
cargo rustelo init --team-mode

# Creates .rustelo/team-config.toml:
[team]
name = "my-saas-team"
shared_features = ["analytics", "auth", "smart-build"]
code_style = "strict"
quality_gates = "required"

[shared_overrides]
justfile = "config/shared/justfile"
theme = "config/shared/theme.toml"

# Team members sync automatically
cargo rustelo sync --team

Developer Onboarding

# New team member setup (one command)
git clone https://github.com/company/my-saas
cd my-saas
cargo rustelo setup --team

# Automatically:
# ✅ Installs correct Rust toolchain
# ✅ Downloads team configuration  
# ✅ Sets up development environment
# ✅ Runs initial build and tests
# ✅ Validates integrity
# ✅ Creates local config template

# Ready to develop in ~2 minutes
just dev

6. Framework Update Workflow

Safe Update Process

# Check update safety first  
cargo rustelo integrity validate --target-version 0.3.0

# If safe (no violations):
cargo rustelo update --version 0.3.0 --auto-migrate

# If violations found:
❌ 3 integrity violations prevent safe update:
   - Hardcoded routes in src/routing.rs:45
   - Direct core import in src/lib.rs:12  
   - Unsafe block in src/auth.rs:67

💡 Run auto-repair for common issues:
cargo rustelo integrity repair --auto

💡 For manual fixes, see detailed report:
cargo rustelo integrity validate --detailed

Update with Migration

# Major update requiring migration
cargo rustelo update --version 1.0.0 --migrate

# Interactive migration process:
🔄 Migrating to Rustelo v1.0.0...

📋 Detected changes requiring attention:
  - Auth trait signature updated (manual fix needed)
  - New configuration format for routing
  - Deprecated API: get_route() → resolve_route()

🛠️ Automatic migrations:
  ✅ Updated Cargo.toml dependencies
  ✅ Migrated configuration files
  ✅ Updated deprecated API calls
  
⚠️ Manual actions required:
  1. Update auth trait implementation in src/auth.rs
     - See migration guide: guides/v0.3-to-v1.0.md
  2. Review new routing configuration format
     - Run: cargo rustelo template show routes.toml

Continue with migration? [y/N]: y

7. Debugging and Troubleshooting Workflow

Comprehensive Debugging

# Start debugging session for specific page
just debug-full /dashboard

# Launches parallel debugging:
# 🖥️ Development server with debug logging
# 🌐 Browser console capture for /dashboard
# 📊 Performance monitoring
# 🔍 Network request analysis
# 📝 Combined debug report generation

# After 30 seconds, generates:
# reports/debug-session-20231201-143022.html

Issue Diagnosis

# Something broken? Run diagnosis
cargo rustelo diagnose

# Comprehensive system check:
✅ Framework integrity: PASSED
✅ Configuration validity: PASSED  
❌ Database connection: FAILED
  - PostgreSQL not running on localhost:5432
  - Fix: just db-start
✅ Asset compilation: PASSED
⚠️  Cache performance: DEGRADED  
  - L1 cache hit rate: 45% (target: >80%)
  - Fix: just cache-optimize

# Suggested actions prioritized by impact

8. Performance Optimization Workflow

Smart Build System

# Enable smart caching (if not already enabled)
cargo rustelo add smart-build

# Immediate benefits:
just build-smart        # Intelligent incremental builds
just cache-stats        # Monitor cache performance
just cache-optimize     # Tune cache parameters

# Performance benchmarking
just benchmark-builds   # Compare build times
just benchmark-runtime  # Application performance metrics

# Results:
Build Performance Improvements:
  - Clean build: 3m 45s → 1m 12s (68% faster)
  - Incremental: 45s → 8s (82% faster)  
  - Cache hit rate: 89%

Runtime Performance

# Add performance monitoring
cargo rustelo add metrics

# Monitor application performance
just metrics-dashboard  # Real-time performance dashboard
just metrics-report     # Generate performance report

# Optimization workflow:
1. just dev              # Start with monitoring
2. # Use application normally
3. just metrics-report   # Identify bottlenecks
4. # Optimize hot paths
5. just benchmark-compare # Validate improvements

9. Deployment Workflow

Production Deployment

# Pre-deployment validation
just deploy-check

# Comprehensive pre-deployment validation:
✅ Framework integrity validated
✅ All tests passing (unit + integration + e2e)
✅ Security audit clean
✅ Performance benchmarks acceptable
✅ Database migrations ready
✅ Assets optimized
✅ Configuration valid for production

# Deploy to staging first
just deploy-staging

# Staging validation
just validate-staging

# Production deployment (if staging passes)
just deploy-prod

Zero-Downtime Deployment

# Blue-green deployment (if configured)
just deploy-blue-green

# Rolling deployment
just deploy-rolling

# Canary deployment  
just deploy-canary --percentage 10

# Automatic rollback on issues
# (Configured through deployment templates)

10. Monitoring and Maintenance Workflow

Health Monitoring

# Application health dashboard
just monitoring-dashboard

# Automated health checks
just health-check-full

# System status:
🟢 Application: Healthy (99.9% uptime)
🟢 Database: Healthy (avg response: 12ms)
🟡 Cache: Warning (hit rate: 75%)
🟢 External APIs: Healthy
🔍 Integrity: Validated (last check: 5m ago)

Maintenance Tasks

# Weekly maintenance routine
just maintenance-weekly

# Runs automatically:
# 🧹 Cache cleanup and optimization
# 📊 Performance report generation  
# 🔄 Dependency security updates
# 📋 Health summary report
# 🔍 Framework integrity check
# 💾 Automated backups

🎯 Workflow Benefits

For Individual Developers

Traditional Approach	New Unified Workflows
Manual template management	Automated with CLI
Risky customizations	Safe layered overrides
Complex feature integration	One-command feature addition
Update anxiety	Integrity-protected updates
Inconsistent tooling	Feature-aware automation

For Teams

Challenge	Solution
Environment inconsistency	Standardized team configuration
Onboarding complexity	One-command setup
Knowledge silos	Shared templates and workflows
Integration conflicts	Layered override system
Update coordination	Validated update process

For Organizations

Need	Fulfillment
Quality assurance	Automated validation pipelines
Security compliance	Built-in security scanning
Performance standards	Integrated benchmarking
Maintenance efficiency	Automated maintenance workflows
Knowledge management	Documented, templated processes

📚 Learning Resources

Getting Started (Day 1)

1. Quick Start: Follow migration guide for existing project
2. New Project: Create new project with cargo rustelo new
3. Basic Commands: Learn just --list and cargo rustelo --help
4. First Override: Try cargo rustelo override template justfile

Intermediate (Week 1)

1. Feature Management: Add your first feature with cargo rustelo add
2. Layer Understanding: Use cargo rustelo trace to understand resolution
3. Quality Workflows: Run just quality and understand each check
4. Integrity System: Learn cargo rustelo integrity validate

Advanced (Month 1)

1. Custom Features: Create organization-specific features
2. Team Configuration: Set up shared team workflows
3. Performance Optimization: Master smart-build and caching
4. Deployment Automation: Configure production deployment workflows

Expert (Month 3+)

1. Framework Contribution: Contribute templates and features back
2. Architecture Design: Design systems using layered principles
3. Training Others: Help teammates and community members
4. Innovation: Pioneer new workflow patterns

---

Next Steps: Choose the workflow most relevant to your current needs and try it out. The system is designed to be discoverable - use --help on any command to learn more!