<div align="center">
  <img src="assets/logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="450" />
</div>

A unified, modern, and secure **Rust** platform to build, deploy, and deliver scalable, high-performance, and reactive web applications with integrated content management, user authentication, multilingual UI, email services, CI/CD pipelines, and comprehensive tooling from development to production.

<div align="left">
  <img src="assets/logos/rustelo-imag.svg" alt="RUSTELO" width="50" />
</div>

>[!NOTE]
> A comprehensive **Rust** solution <br>
> combining reactive **WebAssembly** frontends (**Leptos**) with secure native backends (**Axum**),<br>
> featuring database abstraction (**PostgreSQL/SQLite**), modular configuration, **i18n** support, **RBAC**, <br>
> content management, email services, metrics, automated **CI/CD** pipelines, **Docker** deployment,<br>
> and integrated documentation that scales from 2MB static sites to enterprise applications.

<!-- toc -->
- [🎯 **Core Platform Features**](#-complete-feature-matrix)
- [🚀 Quick Start](#-quick-start)
  * [Option 1: One-Command Setup (Recommended)](#option-1-one-command-setup-recommended)
  * [Option 2: Interactive Configuration](#option-2-interactive-configuration)
  * [Option 3: Manual Setup](#option-3-manual-setup)
- [📦 Optional Features](#-optional-features)
  * [🔒 TLS (`tls`)](#-tls-tls)
  * [🔐 Authentication (`auth`) - *Default*](#-authentication-auth---default)
  * [📄 Database Content (`content-db`) - *Default*](#-database-content-content-db---default)
  * [📧 Email System (`email`) - *Default*](#-email-system-email---default)
- [🛠️ Common Configurations](#-common-configurations)
- [🗄️ Database Support](#-database-support)
- [🔧 Environment Configuration](#-environment-configuration)
- [🏗️ Project Structure](#-project-structure)
- [📚 API Endpoints](#-api-endpoints)
- [🚀 Development](#-development)
- [🐳 Docker Deployment](#-docker-deployment)
- [🔒 Security Features](#-security-features)
- [📖 Documentation](#-documentation)
- [🧪 Testing](#-testing)
- [📊 Performance Considerations](#-performance-considerations)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
- [🆘 Support](#-support)
- [🎯 Use Cases](#-use-cases)
- [🔄 Migration Guide](#-migration-guide)
- [🌟 What's Next?](#-whats-next)
- [📚 Documentation System](#-documentation-system)
<!-- tocstop -->

  ## 🚀 Complete Feature Matrix

<details>
  <summary> click to see details </summary>

  ## 🎯 **Core Platform Features**

  ### **🔧 Development Experience**
  - **WebAssembly Frontend** - Rust code compiled to WASM for performance
  - **Reactive UI System** - Fine-grained reactivity with Leptos
  - **Hot Reload Development** - Live code changes without restart
  - **Unified Type System** - Shared types between client and server
  - **Component-Based Architecture** - Reusable UI components
  - **Just Task Runner** - Simple command execution (`just dev`, `just build`)

  ### **🏗️ Architecture & Framework**
  - **Leptos Frontend** - Modern reactive web framework
  - **Axum Backend** - High-performance async web server
  - **Modular Features** - Enable/disable components as needed
  - **Database Abstraction** - Works with PostgreSQL and SQLite
  - **Memory-Safe by Design** - Rust's safety guarantees
  - **Single Binary Deployment** - Self-contained executables from 2MB

  ## 🔐 **Security Features**

  ### **Authentication & Authorization**
  - **JWT Token Authentication** - Secure token-based auth
  - **OAuth2 Integration** - Google, GitHub, and custom providers
  - **Two-Factor Authentication (2FA)** - TOTP with QR codes
  - **Password Security** - Argon2 hashing, complexity requirements
  - **Session Management** - Secure session handling
  - **Role-Based Access Control (RBAC)** - Fine-grained permissions
  - **Account Security** - Lockout protection, rate limiting

  ### **Network & Data Security**
  - **TLS/HTTPS Support** - SSL certificate management
  - **CSRF Protection** - Cross-site request forgery prevention
  - **Security Headers** - HSTS, CSP, and other security headers
  - **Input Validation** - Comprehensive input sanitization
  - **SQL Injection Prevention** - Safe database queries
  - **Data Encryption** - AES-GCM encryption for sensitive data
  - **Audit Logging** - Security event tracking

  ## 📊 **Content Management**

  ### **Content Creation & Management**
  - **Markdown Support** - Rich text with syntax highlighting
  - **YAML Frontmatter** - Structured metadata
  - **Media Management** - Image and video uploads
  - **Content Versioning** - Track content changes
  - **Draft Mode** - Preview before publishing
  - **Scheduled Publishing** - Automated content release
  - **Content Caching** - Performance optimization
  - **Search & Discovery** - Full-text search capabilities

  ### **Template & Theming**
  - **Template Engine** - Handlebars templates
  - **Theme System** - Customizable appearance
  - **Responsive Design** - Mobile-first approach
  - **Component Library** - Pre-built UI components
  - **Custom CSS** - Tailwind CSS integration
  - **Multi-language Support** - i18n localization

  ## 📧 **Communication Features**

  ### **Email System**
  - **Multi-Provider Support** - SMTP, SendGrid, Console
  - **Email Templates** - HTML and text templates
  - **Queue Management** - Reliable email delivery
  - **Contact Forms** - Built-in form handling
  - **Notifications** - System and user notifications
  - **Email Validation** - Address verification
  - **Rate Limiting** - Prevent spam and abuse

  ### **User Management**
  - **User Registration** - Account creation workflow
  - **Profile Management** - User settings and preferences
  - **Password Reset** - Secure password recovery
  - **Email Verification** - Account activation
  - **User Roles** - Admin, moderator, user hierarchies
  - **Private Content** - User-specific content access

  ## 📈 **Monitoring & Analytics**

  ### **Metrics & Monitoring**
  - **Prometheus Integration** - Industry-standard metrics
  - **System Metrics** - CPU, memory, disk usage
  - **Application Metrics** - Request rates, response times
  - **Database Metrics** - Query performance tracking
  - **Custom Metrics** - Business-specific measurements
  - **Health Checks** - System health monitoring
  - **Performance Profiling** - Code performance analysis

  ### **Logging & Debugging**
  - **Structured Logging** - JSON formatted logs
  - **Log Levels** - Configurable verbosity
  - **Error Tracking** - Comprehensive error reporting
  - **Debug Mode** - Enhanced development logging
  - **Audit Trails** - User action tracking

  ## 🗄️ **Database Features**

  ### **Database Support**
  - **PostgreSQL** - Full-featured production database
  - **SQLite** - Lightweight development database
  - **Database Migrations** - Schema versioning
  - **Query Optimization** - Performance tuning
  - **Connection Pooling** - Efficient resource usage
  - **Backup & Recovery** - Data protection

  ### **Caching System**
  - **Multi-Level Caching** - Memory, Redis, file-based
  - **Cache Invalidation** - Smart cache management
  - **Performance Optimization** - Reduced database load
  - **Cache Metrics** - Hit/miss ratio tracking

  ## 🚀 **DevOps & Deployment**

  ### **CI/CD Pipeline**
  - **GitHub Actions** - Automated testing and deployment
  - **Docker Support** - Containerized deployment
  - **Multi-Environment** - Dev, staging, production configs
  - **Automated Testing** - Unit, integration, E2E tests
  - **Security Scanning** - Vulnerability detection
  - **Performance Testing** - Load and stress testing

  ### **Deployment Options**
  - **Cloud Platforms** - AWS, GCP, Azure support
  - **GitHub Pages** - Static site deployment
  - **Docker Containers** - Container orchestration
  - **Traditional Servers** - VPS and dedicated servers
  - **Kubernetes** - Container orchestration
  - **CDN Integration** - Content delivery networks

  ## 🛠️ **Development Tools**

  ### **Documentation System**
  - **mdBook Integration** - Interactive documentation
  - **Auto-Generated Docs** - API documentation
  - **Multi-Format Export** - PDF, HTML, mobile
  - **Search Functionality** - Full-text documentation search
  - **Version Control** - Documentation versioning
  - **Deployment Automation** - Auto-publish documentation

  ### **Configuration Management**
  - **Environment Variables** - Flexible configuration
  - **TOML Configuration** - Structured config files
  - **Feature Flags** - Runtime feature control
  - **Environment-Specific** - Dev, staging, prod settings
  - **Configuration Validation** - Error prevention
  - **Migration Tools** - Config upgrade assistance

  ### **Build & Tooling**
  - **Cargo Integration** - Rust package management
  - **Asset Pipeline** - CSS, JS, image optimization
  - **Code Generation** - Automated code scaffolding
  - **Lint & Format** - Code quality enforcement
  - **Dependency Management** - Automated updates
  - **Binary Optimization** - Size and performance optimization

  ## 🌐 **Platform Integration**

  ### **API & Services**
  - **REST API** - Full-featured web API
  - **GraphQL Support** - Advanced query capabilities
  - **WebSocket Support** - Real-time communication
  - **Rate Limiting** - API abuse prevention
  - **API Versioning** - Backward compatibility
  - **OpenAPI/Swagger** - API documentation

  ### **Third-Party Integration**
  - **OAuth Providers** - Social login integration
  - **Payment Gateways** - E-commerce support
  - **Analytics Services** - Google Analytics, etc.
  - **CDN Services** - Content delivery
  - **Monitoring Services** - External monitoring
  - **Backup Services** - Cloud backup integration

  ## 📱 **User Experience**

  ### **Interface & Interaction**
  - **Responsive Design** - Mobile-first approach
  - **Progressive Web App** - Offline capability
  - **Accessibility** - WCAG compliance
  - **Dark/Light Mode** - User preference themes
  - **Keyboard Navigation** - Full keyboard support
  - **Touch Gestures** - Mobile-friendly interactions

  ### **Performance Features**
  - **Code Splitting** - Optimized loading
  - **Lazy Loading** - On-demand resource loading
  - **Service Workers** - Offline functionality
  - **Image Optimization** - Automatic compression
  - **Bundle Analysis** - Performance monitoring
  - **Memory Management** - Efficient resource usage

  ## 🔧 **System Features**

  ### **Infrastructure**
  - **Load Balancing** - Traffic distribution
  - **Auto-Scaling** - Dynamic resource allocation
  - **Backup Systems** - Data protection
  - **Disaster Recovery** - Business continuity
  - **Monitoring Alerts** - Proactive notifications
  - **Log Aggregation** - Centralized logging

  ### **Security Infrastructure**
  - **Firewall Integration** - Network security
  - **VPN Support** - Secure remote access
  - **SSL Certificate Management** - Automated renewals
  - **Security Scanning** - Vulnerability assessments
  - **Compliance Tools** - GDPR, CCPA compliance
  - **Penetration Testing** - Security validation

  ---

  ## 🎯 **Total Feature Count: 100+ Features**

  Rustelo provides a comprehensive ecosystem with over 100 features across:
  - **25+ Security Features**
  - **20+ Content Management Features**
  - **15+ DevOps & Deployment Features**
  - **15+ Database & Caching Features**
  - **10+ Communication Features**
  - **10+ Monitoring & Analytics Features**
  - **15+ Development Tools**
  - **Plus many more...**

  **This makes Rustelo a complete platform for building modern web applications with enterprise-grade features out of the box! 🚀
</details>

## 🚀 Quick Start

**New to Rustelo?** Check out our **[Quick Start Guide](QUICK_START.md)** for a complete walkthrough!

### Generate a new website (recommended for new sites)

Scaffold a fresh website from a render-mode template (snapshot of the reference site):

```bash
# Interactive — asks project name, render mode, languages, domain, ontoref level
just site::new

# Non-interactive
just site::new --project acme --render-mode htmx-ssr --domain acme.dev --ontoref minimal --yes
```

Render modes:
- `htmx-ssr` — server-rendered HTML + HTMX, no WASM.
- `leptos-hydration` — SSR + WASM hydration.

The site is created as a sibling of this framework (so its `../rustelo` path deps
resolve), with crates renamed to your project and a `SETUP.md` listing what to complete.
`just site::extract` re-snapshots the templates from the living model. See ADR-007.

### Option 1: One-Command Setup (Recommended)
```bash
# Clone and install everything automatically
git clone https://github.com/yourusername/rustelo.git my-app
cd my-app
./scripts/install.sh

# After installation, check your personalized setup report
cat SETUP_COMPLETE.md
```

### Option 2: Interactive Configuration
```bash
./scripts/configure-features.sh
```

### Option 3: Manual Setup
```bash
# Minimal setup (no optional features)
cargo build --no-default-features

# Full-featured setup (default)
cargo build

# Custom feature combination
cargo build --features "tls,auth"
```

## 📦 Optional Features

Rustelo uses a modular architecture where you can choose which components to include:

### 🔒 TLS (`tls`)
- **What it provides**: HTTPS/TLS encryption for secure connections
- **Use when**: Production deployments, security-sensitive applications
- **Dependencies**: `axum-server`, `rustls`, `rustls-pemfile`

### 🔐 Authentication (`auth`) - *Default*
- **What it provides**: Complete authentication system
  - JWT token-based authentication
  - OAuth2 providers (Google, GitHub, etc.)
  - Two-factor authentication (2FA/TOTP)
  - Password hashing with Argon2
  - Session management
  - **Database-agnostic**: Works with both PostgreSQL and SQLite
- **Use when**: User accounts, protected content, SaaS applications
- **Dependencies**: `jsonwebtoken`, `argon2`, `oauth2`, `totp-rs`, `sqlx`

### 📄 Database Content (`content-db`) - *Default*
- **What it provides**: Database-driven content management
  - Markdown rendering with syntax highlighting
  - YAML frontmatter support
  - Content caching
  - Dynamic content loading
  - **Database-agnostic**: Works with both PostgreSQL and SQLite
- **Use when**: Blogs, CMS, documentation sites
- **Dependencies**: `pulldown-cmark`, `syntect`, `serde_yaml`, `sqlx`

### 📧 Email System (`email`) - *Default*
- **What it provides**: Complete email functionality
  - Multiple providers (SMTP, SendGrid, Console)
  - Handlebars email templates (HTML & text)
  - Contact and support form components
  - Form validation and error handling
  - Rate limiting and security features
- **Use when**: Contact forms, notifications, user communications
- **Dependencies**: `lettre`, `handlebars`, `urlencoding`

## 🛠️ Common Configurations

### Minimal Static Website
```bash
cargo build --no-default-features
```
Perfect for: Marketing sites, landing pages, static documentation

### Secure Static Website
```bash
cargo build --no-default-features --features tls
```
Perfect for: Production static sites requiring HTTPS

### Authentication-Only App
```bash
cargo build --no-default-features --features auth
```
Perfect for: User portals, SaaS apps, protected content

### Content Management System
```bash
cargo build --no-default-features --features content-db
```
Perfect for: Blogs, news sites, documentation

### Contact/Communication Site
```bash
cargo build --no-default-features --features email
```
Perfect for: Contact pages, feedback forms, newsletter signups

### Full-Featured Application (Default)
```bash
cargo build --features "auth,content-db,email"
# or simply: cargo build
```
Perfect for: Complete web applications, user-generated content

## 🗄️ Database Support

Rustelo features a **database-agnostic architecture** that seamlessly works with multiple database backends:

### Supported Databases
- **PostgreSQL** - Full-featured production database
- **SQLite** - Lightweight, file-based database perfect for development and small deployments

### Automatic Database Detection
The application automatically detects your database type from the connection URL:
```bash
# PostgreSQL
DATABASE_URL=postgresql://user:pass@localhost/db

# SQLite
DATABASE_URL=sqlite://data/app.db
```

### Migration System
- Separate migration files for each database type
- Automatic database type detection
- Unified migration runner
- Example: `001_initial_setup_postgres.sql` and `001_initial_setup_sqlite.sql`

### Benefits
- **Development Flexibility**: Use SQLite for local development, PostgreSQL for production
- **Deployment Options**: Single binary deployments with SQLite, or scalable PostgreSQL clusters
- **Testing**: Fast SQLite tests, comprehensive PostgreSQL integration tests
- **Migration Path**: Start with SQLite, migrate to PostgreSQL as you scale

### Production-Ready
```bash
cargo build --release --features "tls,auth,content-db,email"
```
Perfect for: Production deployments with all security features

## 🔧 Environment Configuration

Create a `.env` file based on your enabled features:

### Basic Configuration
```env
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
SERVER_PROTOCOL=http
ENVIRONMENT=DEV
LOG_LEVEL=info
```

### TLS Configuration (if `tls` feature enabled)
```env
SERVER_PROTOCOL=https
TLS_CERT_PATH=./certs/cert.pem
TLS_KEY_PATH=./certs/key.pem
```

### Database Configuration (if `auth` or `content-db` features enabled)
```env
DATABASE_URL=postgres://username:password@localhost:5432/database_name
```

### Authentication Configuration (if `auth` feature enabled)
```env
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRATION_HOURS=24

# OAuth Providers (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# 2FA Configuration
TOTP_ISSUER=YourAppName
TOTP_SERVICE_NAME=YourAppName Authentication
```

### Email Configuration (if `email` feature enabled)
```env
# Email Provider: smtp, sendgrid, or console
EMAIL_PROVIDER=console

# Default sender information
EMAIL_FROM_ADDRESS=noreply@yourapp.com
EMAIL_FROM_NAME=Your App Name

# SMTP Configuration (if using SMTP provider)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=true

# SendGrid Configuration (if using SendGrid provider)
SENDGRID_API_KEY=your-sendgrid-api-key
SENDGRID_ENDPOINT=https://api.sendgrid.com/v3/mail/send

# Email Templates Directory
EMAIL_TEMPLATE_DIR=templates/email
```

## 🔌 Plugin Architecture

Rustelo features a trait-based plugin system for unlimited extensibility without framework coupling.

### What Are Plugins?

Plugins extend Rustelo functionality by implementing well-defined traits:
- **ResourceContributor**: Provide themes, menus, and translations
- **PageProvider**: Provide custom page components

### Key Features

- ✅ **Type-Safe**: Compile-time validation of all plugin code
- ✅ **Zero Conditional Compilation**: Framework code is completely independent
- ✅ **Self-Contained**: Plugins are standalone crates
- ✅ **Configuration-Driven**: Resources from TOML/FTL files
- ✅ **Zero Runtime Overhead**: All embedding at compile time

### Creating a Plugin

**1. Create plugin crate:**
```bash
cargo new --lib my-plugin
```

**2. Implement ResourceContributor:**
```rust
use rustelo_core_lib::registration::ResourceContributor;

pub struct MyPlugin;

impl ResourceContributor for MyPlugin {
    fn contribute_themes(&self) -> HashMap<String, String> {
        let mut themes = HashMap::new();
        themes.insert("my-theme".to_string(),
            include_str!("../config/themes/my-theme.toml").to_string());
        themes
    }

    fn name(&self) -> &str {
        "my-plugin"
    }
}
```

**3. Register at startup:**
```rust
rustelo_core_lib::register_contributor(&MyPlugin)?;
rustelo_core_lib::load_resources_from_config()?;
```

### Plugin Types

| Type | Purpose | Example |
|------|---------|---------|
| **Resource-Only** | Themes, menus, translations | Custom theme plugin |
| **Page Provider** | Custom page components | Analytics dashboard |
| **Composite** | Resources + pages | Feature module |

### Evolution Path

**Level 5 (Current):** Compile-time plugins
- Plugins compiled into binary
- Registration at startup
- ✅ Production ready

**Level 8 (Future):** Runtime plugins
- Dynamic `.so`/`.dylib` loading
- Hot reload support
- Same trait interfaces (backward compatible)

### Documentation

- [Plugin Architecture Guide](./docs/architecture/rustelo-plugin-architecture.md)
- [ADR-004: Plugin Architecture Level 5](./adrs/adr-004-plugin-architecture-level5.ncl)
- [Example Plugin](./examples/plugin-example-theme/)

## 🔍 Architecture Self-Description (on+re)

Rustelo is **self-describing** via the [Ontoref](https://github.com/ontoref) `on+re` protocol. The `.ontology/` and `reflection/` directories form a machine- and agent-readable knowledge graph of the framework's architecture, current state, and invariants.

### What's in `.ontology/`

| File | Purpose |
|------|---------|
| `core.ncl` | Knowledge graph: axioms, tensions, practices, edges |
| `state.ncl` | State dimensions with current/desired states and transitions |
| `gate.ncl` | Architecture membranes (routing integrity, config-driven gate, framework boundary) |
| `manifest.ncl` | Consumer modes, layer definitions, operational modes |

### ADR System (`adrs/`)

Architecture Decision Records in typed NCL with contract validation:

- `adr-001` — Build-Time Code Generation Pattern
- `adr-002` — Custom Routing over Leptos Router
- `adr-003` — Layered Override System
- `adr-004` — Compile-Time Plugin Architecture (Level 5) with Runtime Upgrade Path

### How Agents Use This

An agent reading `.ontology/core.ncl` knows before touching any code:
- Which axioms are invariant (routing integrity, config-driven, no framework forks)
- Which tensions exist and how they're resolved
- Which practices are operative and their artifact paths
- Which gates reject changes without justification

```bash
# Browse framework architecture
nickel export .ontology/core.ncl
nickel export .ontology/state.ncl   # current state vs desired state
nickel export .ontology/gate.ncl    # active membranes and protocols
```

## 🏗️ Project Structure

```
template/
├── client/          # Frontend Leptos components
├── server/          # Backend Axum server
├── shared/          # Shared types and utilities
├── content/         # Static content files
├── migrations/      # Database migrations (if using database features)
├── scripts/         # Helper scripts
├── examples/        # Feature usage examples
├── FEATURES.md      # Detailed feature documentation
└── README.md        # This file
```

## 📚 API Endpoints

### Authentication Endpoints (if `auth` feature enabled)
- `POST /api/auth/login` - User login
- `POST /api/auth/logout` - User logout
- `POST /api/auth/register` - User registration
- `POST /api/auth/refresh` - Token refresh
- `GET /api/auth/oauth/google` - Google OAuth
- `GET /api/auth/oauth/github` - GitHub OAuth
- `POST /api/auth/2fa/setup` - 2FA setup
- `POST /api/auth/2fa/verify` - 2FA verification

### Content Endpoints (if `content-db` feature enabled)
- `GET /api/content/pages` - List pages
- `GET /api/content/page/{slug}` - Get page by slug
- `GET /api/content/posts` - List blog posts
- `GET /api/content/post/{slug}` - Get post by slug

## 🚀 Development

### Prerequisites
- **Rust 1.75+** - Core language and toolchain
- **Node.js 18+** - Frontend tooling and asset processing
- **Nickel** (Configuration language) - **REQUIRED** for type-safe configuration
  - macOS: `brew install nickel`
  - Linux/Windows: `cargo install nickel-lang-cli`
  - See [Nickel Installation Guide](../docs/guides/nickel-installation.md)
- **PostgreSQL** - Required if using database features (`auth` or `content-db`)
- **mdBook** - Documentation generation - `cargo install mdbook`
- **Just** - Task runner - `cargo install just`

> **Note**: Nickel is mandatory for Rustelo projects. All configuration files (routes, themes, menus, content types) use NCL format for type-safety and DRY principles. See [Why Nickel?](../docs/adr/0002-nickel-configuration-language.md) and [Configuration Guide](../docs/guides/nickel-configuration-guide.md).

### Quick Setup
```bash
# Interactive feature configuration
./scripts/configure-features.sh

# Setup comprehensive documentation
./scripts/docs/setup-docs.sh

# Start development with documentation
./scripts/docs/docs-dev.sh &
cargo leptos serve

# Check your personalized setup report
cat SETUP_COMPLETE.md
```

### Setup Database (if using `auth` or `content-db` features)
```bash
# Start PostgreSQL
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=password postgres

# Run migrations
sqlx migrate run
```

### Development Server
```bash
# Development mode with hot reloading
cargo run

# Or with specific features
cargo run --features "auth,content-db"

# Using cargo-leptos for enhanced development experience
cargo leptos serve

# Using cargo-leptos with custom config
cargo leptos serve -- -c config.dev.toml
```

> **Note:** If you encounter "Several bin targets found" error with `cargo leptos serve`, this has been fixed by specifying `bin-target = "server"` in the workspace configuration.

### Documentation Development
```bash
# Start documentation development server
./scripts/docs/docs-dev.sh

# Build documentation
./scripts/docs/build-docs.sh

# Sync existing docs into mdBook format
./scripts/docs/build-docs.sh --sync

# Deploy documentation
./scripts/docs/deploy-docs.sh github-pages
```

### Building for Production
```bash
# Production build
cargo build --release --features "tls,auth,content-db"

# Docker build
docker build -t rustelo .
```

## 🐳 Docker Deployment

### Minimal Docker Setup
```dockerfile
FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --no-default-features

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/server /usr/local/bin/
EXPOSE 3030
CMD ["server"]
```

### Full-Featured Docker Setup
```dockerfile
FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --features "tls,auth,content-db"

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=builder /app/target/release/server /usr/local/bin/
EXPOSE 443
CMD ["server"]
```

## 🔒 Security Features

Always enabled:
- CSRF protection
- Security headers
- Rate limiting
- Input validation
- SQL injection prevention

Optional (with features):
- TLS/HTTPS encryption
- JWT authentication
- OAuth2 integration
- Two-factor authentication
- Password hashing (Argon2)

## 📖 Documentation

Rustelo comes with comprehensive documentation in multiple formats:

### 📚 Interactive Documentation (mdBook)
- **[Complete Guide](https://yourusername.github.io/rustelo)** - Full interactive documentation
- **Local Development**: `./scripts/docs/docs-dev.sh` - Start local docs server
- **Build Documentation**: `./scripts/docs/build-docs.sh` - Build static documentation

### 📄 Quick References
- **[FEATURES.md](FEATURES.md)** - Detailed feature documentation
- **[examples/](examples/)** - Usage examples for different configurations
- **[migrations/](migrations/)** - Database schema documentation
- **[docs/](docs/)** - Technical documentation
- **[info/](info/)** - Implementation details and guides

### 🔧 Documentation Tools
```bash
# Setup complete documentation system
./scripts/docs/setup-docs.sh

# Start development server with live reload
./scripts/docs/docs-dev.sh

# Build documentation
./scripts/docs/build-docs.sh

# Deploy to GitHub Pages
./scripts/docs/deploy-docs.sh github-pages
```

## 🧪 Testing

```bash
# Test all features
cargo test

# Test specific feature combinations
cargo test --no-default-features
cargo test --features "auth"
cargo test --features "content-db"
cargo test --features "tls,auth,content-db"
```

## 📊 Performance Considerations

### Binary Size
- Minimal: ~2MB
- With Auth: ~5MB
- With Content-DB: ~4MB
- Full Featured: ~7MB

### Memory Usage
- Minimal: ~10MB RAM
- With Database: ~30-40MB RAM
- With TLS: +5MB RAM

### Startup Time
- Minimal: ~100ms
- With Database: ~500ms
- With TLS: +200ms

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **🚀 Quick Start**: [QUICK_START.md](QUICK_START.md) - Get started in minutes
- **📋 Setup Report**: [SETUP_COMPLETE.md](SETUP_COMPLETE.md) - Your personalized setup summary
- **📚 Documentation**: [Complete Guide](https://yourusername.github.io/rustelo)
- **🛠️ Installation**: [INSTALL.md](INSTALL.md) - Detailed installation guide
- **🐛 Issues**: [GitHub Issues](https://github.com/yourusername/rustelo/issues)
- **💬 Discussions**: [GitHub Discussions](https://github.com/yourusername/rustelo/discussions)
- **📖 Quick Reference**: [FEATURES.md](FEATURES.md)
- **🔧 Local Docs**: `./scripts/docs/docs-dev.sh`

## 🎯 Use Cases

### Perfect for:
- **SaaS Applications**: Full auth + content management
- **Marketing Sites**: Minimal static setup
- **Blogs & CMS**: Content-DB focused
- **User Portals**: Authentication focused
- **Documentation Sites**: Static or dynamic content
- **Enterprise Apps**: Full-featured with TLS

### Not suitable for:
- High-frequency trading systems
- Real-time gaming backends
- IoT device firmware
- Mobile applications

## 🔄 Migration Guide

### Adding Features to Existing Project
1. Update `Cargo.toml` features
2. Add required environment variables
3. Run database migrations (if applicable)
4. Update client-side code
5. Test thoroughly

### Removing Features
1. Export/backup relevant data
2. Update `Cargo.toml` features
3. Remove related environment variables
4. Clean up unused code
5. Test reduced functionality

## 🌟 What's Next?

The modular architecture makes it easy to:
- Add new authentication providers
- Integrate additional databases
- Add caching layers
- Implement WebSocket support
- Add monitoring and metrics
- Scale horizontally

Choose your features, build your application, and scale as needed!

## 📚 Documentation System

Rustelo includes a comprehensive documentation system built with mdBook:

### Features
- **📖 Interactive Documentation**: Complete guide with search and navigation
- **🔧 Build Scripts**: Automated documentation building and deployment
- **🔄 Content Sync**: Automatically sync existing docs into mdBook format
- **🌐 Multiple Deployment Options**: GitHub Pages, Netlify, Vercel, AWS S3, Docker
- **📱 Responsive Design**: Mobile-friendly documentation
- **🎨 Custom Styling**: Branded documentation with custom themes
- **📋 Setup Reports**: Personalized installation summaries and quick start guides

### Quick Start
```bash
# Setup documentation system
./scripts/docs/setup-docs.sh --full

# Start development server
./scripts/docs/docs-dev.sh

# Build and deploy
./scripts/docs/build-docs.sh
./scripts/docs/deploy-docs.sh github-pages

# Check your setup report
cat SETUP_COMPLETE.md
```

### Documentation Structure
- **Getting Started**: Installation, configuration, first app
- **Features**: Complete feature documentation with examples
- **Database**: Database setup and configuration guides
- **Development**: Development workflow and best practices
- **Deployment**: Production deployment guides
- **API Reference**: Complete API documentation
- **Security**: Security best practices and configuration
- **Troubleshooting**: Common issues and solutions

The documentation system automatically syncs content from your existing `docs/` and `info/` directories, making it easy to maintain comprehensive documentation alongside your code.
