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

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)

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

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:

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

rustelo-web = { workspace = true }

Crate Templates: Use direct dependencies for customization

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

# 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.