Rustelo/templates/README.md

# Rustelo Implementation Templates

This directory contains the unified asset system for Rustelo implementation templates, following a DRY (Don't Repeat Yourself) architecture.

## ✨ NEW: Unified Asset System

The framework has been completely redesigned to use a unified, remote-first asset system instead of static embedded templates. This provides better maintainability, dynamic discovery, and flexible template composition.

## Architecture Overview

```
templates/
├── shared/                    # Master asset repository (DRY principle)
│   ├── scripts/              # Setup, build, database, deployment scripts
│   ├── configs/              # Configuration templates
│   ├── docker/               # Docker files
│   ├── content/              # Sample content and localization
│   ├── docs/                 # Documentation templates
│   ├── public/               # Public assets
│   ├── src/                  # Source code templates
│   ├── *.template            # Core template files
│   └── README.md             # Detailed documentation
├── templates.json            # Template variant definitions with asset patterns
├── framework-features.json   # Dynamic feature discovery
└── basic/                    # Template-specific files (minimal)
    └── manifest.json         # Template-specific configuration
```

### Key Benefits

✅ **DRY Principle**: Single source of truth in `shared/`  
✅ **Dynamic Discovery**: Templates discovered remotely, not hardcoded  
✅ **Flexible Inclusion**: Templates specify what assets they need  
✅ **Easy Maintenance**: Update once in `shared/`, all templates benefit  
✅ **Requirement Validation**: Each template declares and validates its requirements  
✅ **Framework Agnostic**: No hardcoded assumptions about implementations

## Template Variants

All template variants are defined in `templates.json` with dynamic asset inclusion patterns:

### 🪶 Minimal 
- **Complexity**: Simple
- **Setup Time**: 2 minutes
- **Assets**: Core files only, minimal dependencies
- **Use For**: Prototypes, learning projects, microservices, API-only applications

### 🏗️ Basic
- **Complexity**: Simple 
- **Setup Time**: 5 minutes
- **Assets**: Standard web app assets, blog, responsive design
- **Use For**: Business websites, portfolios, blogs, landing pages

### 📝 CMS
- **Complexity**: Medium
- **Setup Time**: 10 minutes  
- **Assets**: Content management, admin interface, SEO optimization
- **Use For**: Content-heavy websites, corporate blogs, news sites

### 🏢 Enterprise
- **Complexity**: Advanced
- **Setup Time**: 15 minutes
- **Assets**: Full CI/CD, monitoring, security, compliance features
- **Use For**: Enterprise applications, regulated environments, high-availability systems

### 💼 SaaS
- **Complexity**: Advanced
- **Setup Time**: 20 minutes
- **Assets**: Authentication, subscriptions, multi-tenancy, business intelligence
- **Use For**: SaaS applications, subscription services, multi-tenant platforms

### 🤖 AI-Powered
- **Complexity**: Advanced
- **Setup Time**: 25 minutes
- **Assets**: LLM integration, semantic search, embeddings, intelligent features
- **Use For**: AI applications, chatbots, semantic search engines, content generation

### 🛍 E-Commerce
- **Complexity**: Advanced  
- **Setup Time**: 30 minutes
- **Assets**: Product catalog, shopping cart, payments, inventory, order management
- **Use For**: Online stores, marketplace platforms, B2B e-commerce

## Asset Inclusion System

Templates use inclusion/exclusion patterns instead of duplicating files:

```json
{
  "name": "basic",
  "assets": {
    "includes": [
      "shared/scripts/setup/*.sh",
      "shared/configs/base/*.toml",
      "shared/docker/Dockerfile.dev"
    ],
    "excludes": [
      "shared/scripts/enterprise/**/*"
    ],
    "template_files": [
      "shared/justfile.template",
      "shared/Cargo.toml.template"
    ]
  }
}
```

This approach:
- **Eliminates duplication**: Assets defined once in `shared/`
- **Flexible composition**: Each template includes only what it needs  
- **Easy maintenance**: Update once, all templates benefit
- **Dynamic discovery**: Templates fetched from remote sources

## Usage

Templates are automatically downloaded and applied by `cargo rustelo init`:

```bash
# Use default basic template
cargo rustelo init my-app

# Specify a template variant
cargo rustelo init my-app --template enterprise

# With custom asset source
cargo rustelo init my-app --template cms --asset-source https://github.com/my-org/rustelo-templates
```

## Template Variables

Templates support variable substitution:

- `{{project_name}}` - Project name
- `{{project_name_snake}}` - Project name in snake_case
- `{{author}}` - Author name
- `{{description}}` - Project description
- `{{rustelo_version}}` - Framework version
- `{{template_variant}}` - Selected template name
- `{{generation_timestamp}}` - Creation timestamp

## Contributing Templates

To add a new template variant:

1. Create a new directory with the template name
2. Add all necessary template files
3. Use `{{variable}}` syntax for substitutable values
4. Update this README with template description
5. Test with `cargo rustelo init --template your-template`

## Remote Usage

Templates can be served remotely:

```bash
# Use remote template source
cargo rustelo init my-app --asset-source https://raw.githubusercontent.com/your-org/rustelo/main/templates

# Local development with framework
cargo rustelo init my-app --asset-source ../rustelo/templates
```

The asset source can be configured in `rustelo-deps.toml` for persistent settings.