Rustelo/book/features/overview.md

# Features Overview

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

Rustelo is built around a modular feature system that allows you to enable only the functionality you need. This approach keeps your application lean, reduces compile times, and ensures you're not carrying unnecessary dependencies.

## Philosophy

The feature system is designed with these principles in mind:

- **🎯 Opt-in by Design**: Start minimal and add features as needed
- **🔧 Zero Configuration**: Features work out of the box with sensible defaults
- **📦 Minimal Dependencies**: Each feature only includes what it absolutely needs
- **🔄 Composable**: Features work together seamlessly
- **🛡️ Secure by Default**: Security considerations built into every feature

## Feature Categories

### Core Features (Always Available)

These features are always available regardless of your configuration:

- **Static File Serving**: Serve static assets (CSS, JS, images)
- **Routing**: Client-side and server-side routing
- **CSRF Protection**: Cross-site request forgery protection
- **Security Headers**: Basic security headers
- **Rate Limiting**: Basic rate limiting
- **Health Checks**: System health monitoring endpoints
- **Logging**: Structured logging with tracing

### Optional Features

#### 🔐 Authentication (`auth`)
**Default: Enabled**

Complete user authentication and authorization system.

**What it provides:**
- JWT token-based authentication
- OAuth2 integration (Google, GitHub, etc.)
- Two-factor authentication (2FA/TOTP)
- Password hashing with Argon2
- Session management
- User registration and login
- Password reset functionality
- Role-based access control (RBAC)

**Use cases:**
- User portals and dashboards
- SaaS applications
- Protected content areas
- Multi-tenant applications

**Dependencies:**
- `jsonwebtoken` - JWT handling
- `argon2` - Secure password hashing
- `oauth2` - OAuth2 client implementation
- `totp-rs` - Two-factor authentication
- `qrcode` - QR code generation
- `tower-sessions` - Session management

#### 📄 Content Management (`content-db`)
**Default: Enabled**

Database-driven content management with Markdown support.

**What it provides:**
- Markdown content rendering
- Syntax highlighting for code blocks
- YAML frontmatter support
- Content caching system
- Dynamic content loading
- Content versioning
- SEO-friendly URLs
- Full-text search capabilities

**Use cases:**
- Blogs and news sites
- Documentation sites
- Content management systems
- Marketing websites
- Knowledge bases

**Dependencies:**
- `pulldown-cmark` - Markdown parsing
- `syntect` - Syntax highlighting
- `serde_yaml` - YAML frontmatter
- `sqlx` - Database access

#### 🔒 TLS Support (`tls`)
**Default: Disabled**

HTTPS/TLS encryption for secure connections.

**What it provides:**
- HTTPS server support
- TLS certificate management
- Automatic HTTP to HTTPS redirects
- SSL/TLS configuration
- Certificate validation
- Support for Let's Encrypt certificates

**Use cases:**
- Production deployments
- Security-sensitive applications
- Compliance requirements
- E-commerce applications

**Dependencies:**
- `axum-server` - TLS-enabled server
- `rustls` - Pure Rust TLS implementation
- `rustls-pemfile` - Certificate file handling

#### 📧 Email System (`email`)
**Default: Enabled**

Comprehensive email functionality with multiple providers.

**What it provides:**
- Multiple email providers (SMTP, SendGrid, AWS SES)
- HTML and text email templates
- Contact form handling
- Email verification
- Password reset emails
- Notification system
- Email queue management
- Bounce handling

**Use cases:**
- Contact forms
- User notifications
- Marketing emails
- Transactional emails
- Newsletter systems

**Dependencies:**
- `lettre` - Email sending
- `handlebars` - Email templating
- `urlencoding` - URL encoding
- `async-trait` - Async trait support

## Feature Combinations

### Common Combinations

#### Minimal Static Site
```bash
cargo build --no-default-features
```
**Perfect for:**
- Marketing websites
- Landing pages
- Documentation sites
- Portfolio sites

**Features included:**
- Static file serving
- Basic routing
- Security headers

#### Secure Static Site
```bash
cargo build --no-default-features --features "tls"
```
**Perfect for:**
- Production static sites
- Security-conscious deployments
- Compliance requirements

**Features included:**
- All minimal features
- HTTPS/TLS support

#### Authentication-Only App
```bash
cargo build --no-default-features --features "auth"
```
**Perfect for:**
- User portals
- Dashboard applications
- API services with authentication

**Features included:**
- User management
- JWT authentication
- OAuth2 providers
- Session management

#### Content Management System
```bash
cargo build --no-default-features --features "content-db"
```
**Perfect for:**
- Blogs
- News sites
- Documentation platforms
- Knowledge bases

**Features included:**
- Markdown rendering
- Database content storage
- Content caching

#### Communication Site
```bash
cargo build --no-default-features --features "email"
```
**Perfect for:**
- Contact pages
- Feedback forms
- Newsletter signups
- Notification systems

**Features included:**
- Email sending
- Form handling
- Template system

#### Full-Featured Application
```bash
cargo build --features "auth,content-db,email"
# or simply: cargo build (uses defaults)
```
**Perfect for:**
- Complete web applications
- SaaS platforms
- User-generated content sites
- E-commerce applications

**Features included:**
- Complete user management
- Content management
- Email system
- All security features

#### Production-Ready
```bash
cargo build --release --features "tls,auth,content-db,email"
```
**Perfect for:**
- Production deployments
- Enterprise applications
- High-security requirements

**Features included:**
- All features enabled
- HTTPS/TLS security
- Optimized for performance

## Configuration Matrix

| Feature | Database Required | Email Required | TLS Recommended |
|---------|------------------|----------------|-----------------|
| Static Site | ❌ | ❌ | ✅ (Production) |
| Auth | ✅ | ✅ (Password Reset) | ✅ |
| Content-DB | ✅ | ❌ | ✅ (Production) |
| Email | ❌ | ✅ | ✅ (Production) |
| TLS | ❌ | ❌ | N/A |

## Performance Impact

### Build Times
- **Minimal**: ~30 seconds
- **Auth Only**: ~45 seconds
- **Content-DB Only**: ~40 seconds
- **Full Featured**: ~60 seconds

### Binary Size
- **Minimal**: ~2MB
- **Auth Only**: ~5MB
- **Content-DB Only**: ~4MB
- **Full Featured**: ~8MB

### Memory Usage
- **Minimal**: ~10MB RAM
- **Auth Only**: ~25MB RAM
- **Content-DB Only**: ~20MB RAM
- **Full Featured**: ~40MB RAM

### Cold Start Time
- **Minimal**: ~50ms
- **Auth Only**: ~200ms
- **Content-DB Only**: ~150ms
- **Full Featured**: ~300ms

## Feature Dependencies

### Database Features
Features that require database access:
- `auth` - User accounts, sessions, OAuth tokens
- `content-db` - Content storage, caching, search

### Email Features
Features that benefit from email:
- `auth` - Password reset, email verification
- `email` - Contact forms, notifications

### Security Features
Features that enhance security:
- `tls` - HTTPS encryption
- `auth` - User authentication
- All features include basic security (CSRF, rate limiting, headers)

## Development vs Production

### Development Recommendations
```bash
# Fast development cycle
cargo build --features "auth,content-db,email"

# With hot reloading
cargo leptos serve --features "auth,content-db,email"
```

### Production Recommendations
```bash
# Secure production build
cargo build --release --features "tls,auth,content-db,email"

# Minimal production (static sites)
cargo build --release --no-default-features --features "tls"
```

## Migration Between Features

### Adding Features
1. Update feature flags in build command
2. Add required environment variables
3. Run database migrations (if applicable)
4. Update frontend components
5. Test thoroughly

### Removing Features
1. Export/backup relevant data
2. Update feature flags
3. Remove unused environment variables
4. Clean up unused code
5. Test reduced functionality

## Feature Roadmap

### Planned Features
- **WebSocket Support**: Real-time communication
- **File Upload**: File management system
- **Admin Dashboard**: Administrative interface
- **API Documentation**: Automatic API docs
- **Metrics & Monitoring**: Application metrics
- **Search Engine**: Full-text search
- **Caching Layer**: Redis integration
- **Message Queue**: Background job processing

### Experimental Features
- **GraphQL API**: Alternative to REST
- **Server-Side Events**: Real-time updates
- **Multi-tenancy**: Tenant isolation
- **Audit Logging**: Comprehensive audit trails

## Best Practices

### Feature Selection
1. **Start Minimal**: Begin with only essential features
2. **Add Gradually**: Introduce features as requirements evolve
3. **Consider Dependencies**: Understand feature interactions
4. **Test Combinations**: Verify feature combinations work together
5. **Document Choices**: Record why features were selected

### Configuration
1. **Environment-Specific**: Use different features per environment
2. **Feature Flags**: Use runtime feature flags for A/B testing
3. **Graceful Degradation**: Handle missing features gracefully
4. **Monitoring**: Monitor feature usage and performance

### Development
1. **Feature Branches**: Develop features in isolation
2. **Integration Testing**: Test feature combinations
3. **Documentation**: Document feature usage
4. **Performance Testing**: Measure feature impact

## Next Steps

Ready to dive deeper into specific features? Check out:

- **[Authentication System](./authentication.md)** - Complete user management
- **[Content Management](./content-management.md)** - Database-driven content
- **[TLS Support](./tls.md)** - HTTPS configuration
- **[Email System](./email.md)** - Communication features
- **[Feature Combinations](./combinations.md)** - Detailed combination guide

Or explore the technical details:
- **[Database Overview](../database/overview.md)** - Database configuration
- **[Security Overview](../security/overview.md)** - Security features
- **[Performance Overview](../performance/overview.md)** - Performance considerations