Rustelo/docs/guides/quick-start-guide.md

# Quick Start Guide - Create Rustelo Implementation

## 🚀 Two Ways to Get Started

This guide shows you how to create a Rustelo implementation using two approaches:
1. **Command Line**: Interactive, step-by-step creation
2. **Config File**: Declarative, reproducible setup

Both approaches create the same result - choose what fits your workflow best!

---

## 📋 Prerequisites (2 minutes)

### Install Rustelo CLI
```bash
# Install latest Rustelo CLI
cargo install rustelo-cli

# Verify installation
cargo rustelo --version
# Output: rustelo-cli 0.1.0

# Check available commands
cargo rustelo --help
```

### System Requirements
- **Rust**: 1.70+ (install from [rustup.rs](https://rustup.rs))
- **Node.js**: 18+ (for CSS and tooling)
- **Git**: For version control
- **Database**: PostgreSQL or SQLite (optional, for database features)

---

## 🎯 Approach 1: Command Line Creation

### Step 1: Create New Project (Interactive)
```bash
# Start interactive project creation
cargo rustelo new

# Interactive prompts:
📋 Project name: my-webapp
📋 Description: My awesome web application
📋 Template type:
  > webapp (Full-stack web application)
    api (REST API server)
    static (Static site generator)
    desktop (Desktop application)

📋 Select features:
  [x] analytics (Usage analytics and monitoring)
  [x] auth (Authentication and authorization)  
  [ ] smart-build (Intelligent build caching)
  [x] debugging-tools (Enhanced debugging capabilities)
  [ ] email (Multi-provider email system)
  [ ] tls (HTTPS/TLS support)

📋 Database:
  > postgres (PostgreSQL - production ready)
    sqlite (SQLite - development friendly)
    none (No database)

📋 Styling:
  [x] tailwind (Tailwind CSS via UnoCSS)
  [ ] custom (Custom CSS setup)

📋 Additional options:
  [x] github-actions (CI/CD workflows)
  [x] docker (Docker configuration)
  [x] docs (Documentation setup)
```

### Step 2: Project Generated
```bash
✅ Created my-webapp project with:
   - Template: webapp
   - Features: analytics, auth, debugging-tools
   - Database: PostgreSQL
   - Styling: Tailwind/UnoCSS
   - CI/CD: GitHub Actions
   - Containerization: Docker

📁 Project structure created at: ./my-webapp/
🔧 Configuration files generated
📦 Dependencies resolved
🚀 Ready for development!

Next steps:
  cd my-webapp
  just setup
  just dev
```

### Step 3: Development Setup
```bash
cd my-webapp

# One-command setup (installs dependencies, sets up database, etc.)
just setup

# Setup process:
🔧 Installing Rust dependencies...
📦 Installing Node.js dependencies...
🗄️ Setting up PostgreSQL database...
🎨 Building initial CSS...
✅ Development environment ready!

# Start development server
just dev

# Development server started:
🚀 Server running at http://localhost:3000
📊 Analytics dashboard at http://localhost:3001
🔧 Debug tools enabled
🔄 Hot reload active
```

### Step 4: Explore Your Project
```bash
# See available commands
just --list

# Available recipes:
# dev              Start development server
# dev-full         Start all services (server, analytics, debugging)
# build            Build for development
# build-prod       Build for production
# test             Run tests
# auth-setup       Setup authentication
# analytics-report Generate analytics report
# db-migrate       Run database migrations
# quality          Run all quality checks

# Try some commands:
just auth-setup     # Configure authentication
just db-migrate     # Run database migrations
just quality        # Check code quality
```

---

## ⚙️ Approach 2: Config File Creation

### Step 1: Create Project Config File
```bash
# Create project configuration
mkdir my-webapp
cd my-webapp

# Create rustelo.toml configuration
cat > rustelo.toml << 'EOF'
[project]
name = "my-webapp"
description = "My awesome web application"
version = "0.1.0"
authors = ["Your Name <your.email@example.com>"]
license = "MIT"

[template]
type = "webapp"
variant = "full-stack"

[features]
# Core features
analytics = { enabled = true, config = { retention_days = 30, dashboard_port = 3001 } }
auth = { enabled = true, config = { methods = ["jwt", "oauth2"], providers = ["google", "github"] } }
debugging-tools = { enabled = true, config = { browser_logs = true, performance_monitoring = true } }

# Optional features (disabled by default)
smart-build = { enabled = false }
email = { enabled = false }
tls = { enabled = false }

[database]
type = "postgres"
url = "postgresql://localhost:5432/my_webapp"
migrations = true
auto_setup = true

[styling]
framework = "tailwind"
processor = "unocss"
themes = ["light", "dark"]
custom_colors = { primary = "#3b82f6", secondary = "#10b981" }

[development]
hot_reload = true
debug_mode = true
log_level = "debug"
port = 3000

[build]
optimize = true
target_dir = "target"
features = ["analytics", "auth", "debugging-tools"]

[deployment]
docker = true
ci_cd = "github-actions"
environments = ["staging", "production"]

[tooling]
justfile = true
package_json = true
dockerfile = true
github_actions = true
documentation = true

[quality]
pre_commit_hooks = true
code_formatting = "rustfmt"
linting = "clippy"
testing = { unit = true, integration = true, e2e = false }
EOF
```

### Step 2: Generate Project from Config
```bash
# Create project from configuration file
cargo rustelo create --config rustelo.toml

# Output:
📋 Reading configuration from rustelo.toml...
✅ Configuration validated
🏗️ Creating project structure...
📦 Installing dependencies...
🔧 Configuring features...
🎨 Setting up styling system...
🗄️ Configuring database...
🚀 Setting up development environment...

✅ Project created successfully!

Project: my-webapp (v0.1.0)
Template: webapp (full-stack variant)
Features: analytics, auth, debugging-tools
Database: PostgreSQL
Styling: Tailwind/UnoCSS

Next steps:
  just setup
  just dev
```

### Step 3: Verify Configuration
```bash
# Check generated project matches config
cargo rustelo info

# Output:
📋 Project Information:
  Name: my-webapp
  Template: webapp (full-stack)
  Generated by: cargo rustelo v0.1.0
  Configuration: rustelo.toml
  
🎯 Enabled Features:
  ✅ analytics (retention: 30 days, port: 3001)
  ✅ auth (JWT + OAuth2: google, github)  
  ✅ debugging-tools (browser logs, performance monitoring)
  
🗄️ Database:
  Type: PostgreSQL
  URL: postgresql://localhost:5432/my_webapp
  Migrations: Enabled
  
🎨 Styling:
  Framework: Tailwind CSS
  Processor: UnoCSS
  Themes: light, dark
  Primary: #3b82f6, Secondary: #10b981

🔧 Development:
  Port: 3000
  Hot Reload: Enabled
  Debug Mode: Enabled
  Log Level: debug
```

### Step 4: Customize Configuration (Optional)
```bash
# Edit configuration for your needs
nano rustelo.toml

# Example customizations:
[features]
# Add more features
smart-build = { enabled = true, config = { cache_size = "2GB", parallel_jobs = 4 } }
email = { enabled = true, config = { provider = "sendgrid", templates = true } }

[styling.custom_colors]
# Update brand colors
primary = "#ff6b6b"
secondary = "#4ecdc4"
accent = "#45b7d1"

# Regenerate with new configuration
cargo rustelo update --config rustelo.toml

# Applies configuration changes:
✅ Added smart-build feature
✅ Added email feature  
✅ Updated color theme
🔄 Rebuilding CSS with new colors...
✅ Configuration updated successfully!
```

---

## 🔄 Configuration File Templates

### Minimal Configuration (API Only)
```toml
# minimal-api.toml
[project]
name = "my-api"
description = "Simple REST API"

[template]
type = "api"

[features]
auth = { enabled = true }

[database]
type = "sqlite"
```

### Full-Featured Web App
```toml
# full-webapp.toml
[project]
name = "my-saas"
description = "Full SaaS application"

[template] 
type = "webapp"
variant = "saas"

[features]
analytics = { enabled = true }
auth = { enabled = true, config = { methods = ["jwt", "oauth2", "2fa"] } }
smart-build = { enabled = true }
debugging-tools = { enabled = true }
email = { enabled = true }
tls = { enabled = true }

[database]
type = "postgres"
url = "$DATABASE_URL"

[styling]
framework = "tailwind"
themes = ["light", "dark", "system"]

[deployment]
docker = true
ci_cd = "github-actions"
environments = ["dev", "staging", "prod"]
```

### Static Site
```toml
# static-site.toml
[project]
name = "my-blog"
description = "Personal blog"

[template]
type = "static"

[features]
analytics = { enabled = true, config = { provider = "google" } }

[styling]
framework = "tailwind"
themes = ["minimal"]

[content]
type = "markdown"
source = "content/"
```

### Team/Organization Template
```toml
# team-template.toml
[project]
name = "team-project"
description = "Standardized team project"

[template]
type = "webapp"

[features]
analytics = { enabled = true }
auth = { enabled = true }
smart-build = { enabled = true }
debugging-tools = { enabled = true }

[team]
shared_config = true
code_style = "strict"
pre_commit_hooks = ["format", "lint", "test", "integrity"]

[quality]
coverage_threshold = 90.0
security_scan = true
performance_budget = { fcp = "1.5s", lcp = "2.5s" }
```

---

## 🎯 Next Steps After Creation

### Development Workflow
```bash
# Start development
just dev

# In separate terminal, try features:
just auth-setup        # Setup authentication
just analytics-report  # View analytics
just db-migrate        # Run database migrations

# Check code quality
just quality

# Run tests
just test
```

### Customization
```bash
# Override templates locally
cargo rustelo override template justfile
# Edit config/local/justfile with your custom commands

# Override components
cargo rustelo override component NavBar
# Edit src/components/local/NavBar.rs

# Add local configuration
echo 'debug_toolbar = true' >> config/local/development.toml
```

### Feature Management
```bash
# Add more features
cargo rustelo add smart-build
cargo rustelo add email

# Check feature status
cargo rustelo features status

# Remove features
cargo rustelo remove debugging-tools
```

### Production Deployment
```bash
# Build for production
just build-prod

# Run deployment checks
just deploy-check

# Deploy (if configured)
just deploy-staging  # Deploy to staging first
just deploy-prod     # Deploy to production
```

---

## 🚨 Common Issues and Solutions

### Issue 1: Database Connection Failed
```bash
# Problem: PostgreSQL not running
# Solution:
just db-start        # Start database
just db-setup        # Setup database schema
just db-migrate      # Run migrations
```

### Issue 2: Port Already in Use
```bash
# Problem: Port 3000 already in use
# Solution: Change port in config/local/development.toml
echo 'port = 3001' >> config/local/development.toml
just dev
```

### Issue 3: Node.js Dependencies Missing
```bash
# Problem: CSS build fails
# Solution:
npm install          # Install Node.js dependencies
just css-build       # Rebuild CSS
```

### Issue 4: Permission Denied
```bash
# Problem: Permission errors on Linux/Mac
# Solution:
chmod +x scripts/**/*.sh  # Make scripts executable
sudo chown -R $USER target/  # Fix target directory ownership
```

---

## 📚 What's Next?

1. **Read the Migration Guide**: [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)
2. **Explore New Workflows**: [NEW_WORKFLOWS.md](./NEW_WORKFLOWS.md)  
3. **Understand Architecture**: [TEMPLATE_ARCHITECTURE.md](./TEMPLATE_ARCHITECTURE.md)
4. **Learn Layer System**: [LAYERED_OVERRIDE_SYSTEM.md](./LAYERED_OVERRIDE_SYSTEM.md)
5. **Check Integrity Protection**: [FRAMEWORK_INTEGRITY_PROTECTION.md](./FRAMEWORK_INTEGRITY_PROTECTION.md)

## 🆘 Getting Help

- **CLI Help**: `cargo rustelo help <command>`
- **Project Issues**: `cargo rustelo diagnose`
- **Community**: GitHub Discussions
- **Documentation**: `cargo rustelo docs`

**Happy coding with Rustelo! 🦀🚀**