Rustelo/docs/architecture/template-architecture.md

# Rustelo Template Architecture

## 🏗️ Unified Template System

After consolidating the template functionality, Rustelo now uses a **layered template architecture** that serves different phases of development:

## Template Hierarchy

### 1. **Project Templates** (`/rustelo/templates/`)
**Purpose**: Complete project scaffolding with full tooling setup
- **When**: Initial project creation (`cargo rustelo new`)
- **Features**: Variable substitution, workspace configuration, complete tooling
- **Coverage**: Configs, scripts, docs, Docker, content, styling, build automation

**Available Templates**:
- `basic` - Standard web application (most common)
- `cms` - Content management focused
- `minimal` - Lightweight for prototypes
- `enterprise` - Advanced features for large deployments
- `saas` - Software-as-a-Service with subscriptions
- `ai-powered` - AI/ML integration
- `ecommerce` - Online store functionality

### 2. **Crate Templates** (`/rustelo/crates/templates/`)
**Purpose**: Deep customization via trait-based architecture
- **When**: Advanced customization needs (`cargo rustelo clone`)
- **Features**: Trait implementations, local dependencies, standalone operation
- **Coverage**: Individual crate functionality with full customization capability

**Available Templates**:
- `client-template` - WASM client with trait-based routing
- `server-template` - Axum server with comprehensive features
- `core-lib-template` - Core business logic implementations
- `rustelo-cli` - CLI tool template for project management

### 3. **Feature Templates** (`/rustelo/features/*/templates/`)
**Purpose**: Modular feature configuration
- **When**: Adding/removing features (`cargo rustelo add/remove`)
- **Features**: Feature-specific configs, dependencies, tooling additions
- **Coverage**: Analytics configs, build optimizations, specialized tooling

## 🔄 Template Integration Workflow

### Phase 1: Project Creation
```bash
cargo rustelo new my-project --template basic --features auth,content
```
**Result**: Complete project with:
- Workspace structure from project template
- Feature-specific configurations from feature templates
- All tooling (just, CSS, package.json, scripts) properly configured

### Phase 2: Crate Customization (Optional)
```bash
cargo rustelo clone client --target local-crates
```
**Result**: Local crate with:
- Trait-based implementations you can modify
- Direct dependencies for standalone development
- Full control over routing, rendering, content loading

### Phase 3: Feature Management
```bash
cargo rustelo add analytics    # Adds feature templates + dependencies
cargo rustelo remove auth      # Removes cleanly without breaking
cargo rustelo update          # Updates framework, preserves customizations
```

## 🎯 Template Composition Strategy

### Variable Substitution System
**Project Templates** support dynamic configuration:
```toml
name = "{{project_name_snake}}-client"
authors = [{{authors}}]
features = {{selected_features}}
```

### Layered Override System
**Precedence Order**: Local > Feature > Template > Framework

1. **Framework Layer**: Core rustelo crates (never modified)
2. **Template Layer**: Default implementations from templates
3. **Feature Layer**: Feature-specific additions/configurations
4. **Local Layer**: Project-specific overrides and customizations

### Dependency Resolution
**Project Templates**: Use workspace dependencies
```toml
rustelo-web = { workspace = true }
```

**Crate Templates**: Use direct dependencies for customization
```toml
rustelo-routing-traits = { path = "../../traits/routing-traits" }
```

## 🧩 Template System Benefits

### For New Projects
- **Single Command**: Complete setup with `cargo rustelo new`
- **Full Tooling**: Just, CSS, configs, scripts all working
- **Feature Selection**: Choose capabilities during creation

### For Customization
- **Trait-Based**: Modify behavior without forking framework
- **Granular Control**: Customize routing, rendering, content loading
- **Update Safety**: Framework updates don't break customizations

### for Framework Integrity
- **No Forking**: Framework stays in dependencies
- **Validation**: CLI ensures customizations don't break contracts
- **Upgrade Path**: Clear migration between framework versions

## 🔧 Template Development Guidelines

### Adding Project Templates
1. Create directory in `/rustelo/templates/`
2. Add configuration to `templates.json`
3. Include shared components via `assets.includes`
4. Support variable substitution for dynamic values

### Adding Crate Templates
1. Create directory in `/rustelo/crates/templates/`
2. Include trait dependencies and implementations
3. Support standalone operation with direct dependencies
4. Provide customization examples in README

### Adding Feature Templates
1. Create in `/rustelo/features/{feature}/templates/`
2. Include feature-specific configurations
3. Update CLI to handle feature addition/removal
4. Document feature interactions and dependencies

## 🚀 Migration Path

### From Old Foundation Templates
Foundation templates have been **consolidated into the unified system**:
- Build functionality moved to crate templates
- Template variety preserved in project templates
- CLI integration enhanced for seamless workflows

### For Existing Projects
```bash
# Check current project structure
cargo rustelo status

# Migrate to new template system
cargo rustelo migrate

# Optionally clone crates for customization
cargo rustelo clone all --target local-crates
```

This unified architecture provides the flexibility for both rapid prototyping and deep customization while maintaining framework integrity and upgrade safety.