Rustelo/crates/templates/README.md

# Rustelo Templates

This directory contains the new template-based architecture for Rustelo projects. After the architectural refactoring, foundation crates can now be cloned locally and customized through trait-based implementations.

## 🏗️ Architecture Overview

```
rustelo/
├── traits/                    # Layer 1: Pure trait abstractions (zero deps)
│   ├── routing-traits/        
│   ├── component-traits/      
│   └── core-types/           
├── templates/                 # Layer 2: Template implementations
│   ├── core-lib-template/     
│   ├── client-template/       
│   ├── server-template/       
│   └── rustelo-cli/          # CLI tool for project management
└── foundation/               # Layer 3: Reference implementation (legacy)
    └── crates/               
```

## 🚀 Quick Start

### 1. Install the CLI Tool

```bash
cd rustelo-cli
cargo install --path .
```

### 2. Create a New Project

```bash
# Interactive project creation
rustelo new my-project

# Quick project with defaults
rustelo new my-project --quiet
```

### 3. Clone Foundation Crates for Customization

```bash
# Clone specific crate
rustelo clone core-lib --target local-crates

# Clone all foundation crates  
rustelo clone all --target local-crates
```

### 4. Migrate Existing Project

```bash
# Migrate existing project to new architecture
rustelo migrate --path /path/to/project

# Check project status
rustelo status --path /path/to/project
```

## 📋 Template Descriptions

### `core-lib-template`
- **Purpose**: Core trait implementations for routing, content, and localization
- **Customization**: Edit `src/traits_impl.rs` to modify routing logic, content loading, etc.
- **Zero Dependencies**: No environment variables, pure trait-based configuration

### `client-template`  
- **Purpose**: Client-side routing and rendering using trait injection
- **Features**: WASM-compatible, reactive routing, trait-based component rendering
- **Customization**: Modify `ClientRouteRenderer` in `src/routing.rs`

### `server-template`
- **Purpose**: Server-side rendering with trait-based dependency injection
- **Features**: SSR support, localization, metadata generation
- **Customization**: Modify `ServerRouteRenderer` in `src/routing.rs`

## 🎯 Usage Workflows

### For New Projects

1. **Create project**: `rustelo new my-project`
2. **Develop normally**: `cargo leptos watch`
3. **Customize as needed**: Edit trait implementations

### For Existing Projects

1. **Check status**: `rustelo status`
2. **Migrate**: `rustelo migrate` 
3. **Customize**: Edit generated `traits_impl.rs` files
4. **Test**: `cargo leptos watch`

### For Local Customization

1. **Clone templates**: `rustelo clone all --target local-crates`
2. **Customize implementations**: Edit `local-crates/*/src/traits_impl.rs`
3. **Update dependencies**: Point Cargo.toml to local crates
4. **Develop**: Full control over trait implementations

## 🔧 Customization Guide

### Customizing Route Resolution

```rust
// In local-crates/core-lib/src/traits_impl.rs
impl RouteResolver for DefaultRouteResolver {
    fn resolve_route(&self, path: &str) -> RoutingResult<RouteResolution<Self::Component, Self::Parameters>> {
        // Your custom routing logic here
        // No environment variables needed - use configuration objects
        Ok(RouteResolution {
            component: Some("CustomComponent".to_string()),
            path: path.to_string(),
            parameters: HashMap::new(),
        })
    }
}
```

### Customizing Component Rendering

```rust
// In local-crates/client/src/routing.rs  
impl RouteRenderer for ClientRouteRenderer {
    fn render_component(&self, component: &Self::Component, path: &str, language: &str, parameters: &Self::Parameters) -> RoutingResult<Self::View> {
        // Your custom rendering logic here
        match component.as_str() {
            "CustomComponent" => {
                let view = view! { <div>"My Custom Component"</div> }.into_any();
                Ok(view)
            },
            _ => self.render_not_found(path, language)
        }
    }
}
```

### Customizing Content Loading

```rust
// In local-crates/core-lib/src/traits_impl.rs
impl ContentProvider for DefaultContentProvider {
    fn load_content(&self, content_type: &str, identifier: &str, language: &str) -> ComponentResult<ContentMetadata> {
        // Your custom content loading logic
        // Load from database, API, filesystem, etc.
        Ok(ContentMetadata {
            title: "Custom Content".to_string(),
            slug: identifier.to_string(),
            language: language.to_string(),
            // ... other fields
        })
    }
}
```

## 📁 Directory Structure After Cloning

```
your-project/
├── Cargo.toml                    # Updated with local crate references
├── local-crates/                 # Cloned and customized crates
│   ├── core-lib/
│   │   ├── src/traits_impl.rs   # ← Customize trait implementations
│   │   └── Cargo.toml           
│   ├── client/
│   │   ├── src/routing.rs       # ← Customize client routing
│   │   └── Cargo.toml
│   └── server/
│       ├── src/routing.rs       # ← Customize server routing  
│       └── Cargo.toml
└── src/
    └── main.rs                   # Uses local-crates instead of foundation
```

## 🔄 Migration Process

The CLI tool automates migration from the old foundation-based architecture:

1. **Backup**: Creates `.backup-pre-migration/` with original files
2. **Dependencies**: Adds trait crate dependencies to Cargo.toml
3. **Implementations**: Creates `traits_impl.rs` files with default implementations
4. **Routing**: Updates routing files to use trait-based approach
5. **Summary**: Generates `MIGRATION_SUMMARY.md` with details

## ✨ Benefits of New Architecture

- **🔓 No Vendor Lock-in**: Clone templates and customize freely
- **🚫 No Code Generation**: Runtime trait resolution instead of build-time generation
- **🌍 Environment Agnostic**: No dependency on environment variables
- **🔧 Full Customization**: Every aspect can be modified locally
- **📦 Modular**: Only include what you need
- **🧪 Testable**: Mock trait implementations for testing
- **⚡ Performance**: Runtime resolution with caching

## 🆘 Troubleshooting

### Common Issues

**Template not found**
```bash
# Make sure you're in the rustelo project directory
cd /path/to/rustelo
rustelo clone core-lib
```

**Compilation errors after cloning**
```bash
# Update local trait dependency paths in Cargo.toml
[dependencies.rustelo-routing-traits]
path = "../traits/routing-traits"  # Adjust path as needed
```

**Runtime routing failures**  
```bash
# Check your trait implementations in src/traits_impl.rs
# Make sure resolve_route returns valid components
```

### Getting Help

- Check project status: `rustelo status`
- Review migration summary: `cat MIGRATION_SUMMARY.md`
- Restore from backup: Copy from `.backup-pre-migration/`

## 🎯 Next Steps

1. **Try the CLI**: `cargo install --path rustelo-cli`
2. **Create test project**: `rustelo new test-project`  
3. **Experiment with customization**: Clone crates and modify trait implementations
4. **Migrate existing projects**: Use `rustelo migrate` on real projects
5. **Provide feedback**: Report issues and suggest improvements

This template-based architecture provides the granularity and flexibility requested while maintaining all the benefits of Rustelo's configuration-driven, language-agnostic design.