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
```bash
# 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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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  
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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!