Rustelo/crates/foundation/README.md

# Rustelo Foundation Library System

A complete, modular foundation for building modern web applications with Rust, Leptos, and WebAssembly.

## 🎯 Overview

The Rustelo Foundation provides a comprehensive set of library crates that work together to create powerful web applications. Each crate is designed as a reusable library with importable functions, extensive documentation, and practical examples.

## 📦 Foundation Crates

### Core System
- **[`server/`](crates/server/)** - Server-side library with importable main functions, routing, and middleware
- **[`client/`](crates/client/)** - Client-side library with app mounting, hydration, and state management  
- **[`core-lib/`](crates/core-lib/)** - Shared utilities, configuration, i18n, and business logic
- **[`core-types/`](crates/core-types/)** - Common type definitions and data structures

### UI System
- **[`components/`](crates/components/)** - Reusable UI component library with theming support
- **[`pages/`](crates/pages/)** - Page generation system with templates and content processing

## 🚀 Quick Start

### 1. Import Foundation Libraries
```rust
// In your application's Cargo.toml
[dependencies]
server = { path = "path/to/rustelo/crates/foundation/crates/server" }
client = { path = "path/to/rustelo/crates/foundation/crates/client" }
components = { path = "path/to/rustelo/crates/foundation/crates/components" }
pages = { path = "path/to/rustelo/crates/foundation/crates/pages" }
core-lib = { path = "path/to/rustelo/crates/foundation/crates/core-lib" }
core-types = { path = "path/to/rustelo/crates/foundation/crates/core-types" }
```

### 2. Use Foundation Main Functions
```rust
// src/main.rs - Import and use server main function
use server::{run_server, ServerConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Simple usage - use foundation server directly
    run_server().await?;
    Ok(())
}
```

### 3. Build with Foundation Utilities
```rust
// build.rs - Use foundation build functions
use server::build::generate_routes;
use pages::build::generate_pages;
use core_lib::build::process_configuration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Use foundation build utilities
    process_configuration("config/")?;
    generate_routes("content/routes/")?;
    generate_pages("content/")?;
    Ok(())
}
```

### 4. Create UI with Foundation Components
```rust
// Use foundation components and pages
use components::{
    navigation::{BrandHeader, Footer},
    content::UnifiedContentCard,
    ui::SpaLink,
};
use pages::{HomePage, AboutPage, ContactPage};

#[component]
fn App() -> impl IntoView {
    view! {
        <BrandHeader brand_name="My App">
            <SpaLink href="/">"Home"</SpaLink>
            <SpaLink href="/about">"About"</SpaLink>
        </BrandHeader>
        
        <Routes>
            <Route path="/" view=HomePage />
            <Route path="/about" view=AboutPage />
            <Route path="/contact" view=ContactPage />
        </Routes>
        
        <Footer copyright="© 2024 My Company" />
    }
}
```

## 🏗️ Usage Patterns

### Pattern 1: Direct Import (Simplest)
Perfect for getting started quickly:
```rust
use server::run_server;
use components::navigation::BrandHeader;
use pages::HomePage;

// Use foundation functions directly
run_server().await?;
```

### Pattern 2: Configuration-Based  
Customize behavior through configuration:
```rust
use server::{run_server_with_config, ServerConfig};
use core_lib::config::load_app_config;

let app_config = load_app_config("config.toml")?;
let server_config = ServerConfig::from_app_config(&app_config);
run_server_with_config(server_config).await?;
```

### Pattern 3: Modular Composition
Compose applications from individual foundation functions:
```rust
use server::{create_base_app, setup_tracing, serve_custom_app};
use components::{theme::ThemeProvider, navigation::BrandHeader};
use pages::{PageGenerator, BlogTemplate};

// Compose your application
let app = create_base_app()
    .merge(custom_routes())
    .layer(custom_middleware());
    
serve_custom_app(app, config).await?;
```

### Pattern 4: Full Integration
Complete integration across all foundation crates:
```rust
use server::{run_server_with_config, ServerConfig};
use client::{ClientConfig, hydrate_app};
use components::theme::{ThemeProvider, ThemeConfig};
use pages::{generate_pages, PageGeneratorConfig};
use core_lib::{config::AppConfig, i18n::setup_translations};
use core_types::{ContentItem, User, Route};

// Complete application using all foundation crates
// See FOUNDATION_INTEGRATION_GUIDE.md for full example
```

## 📚 Documentation

### Individual Crate Documentation
- **[Server Foundation](crates/server/README.md)** - Server-side library usage
- **[Client Foundation](crates/client/README.md)** - Client-side library usage  
- **[Components Foundation](crates/components/README.md)** - UI component library
- **[Pages Foundation](crates/pages/README.md)** - Page generation system
- **[Core Lib Foundation](crates/core-lib/README.md)** - Shared utilities
- **[Core Types Foundation](crates/core-types/README.md)** - Type definitions

### Integration Guides
- **[Foundation Integration Guide](FOUNDATION_INTEGRATION_GUIDE.md)** - Complete integration examples
- **[Cross-Crate Patterns](docs/CROSS_CRATE_PATTERNS.md)** - Communication patterns
- **[Build System Integration](docs/BUILD_INTEGRATION.md)** - Build system usage
- **[Testing Strategies](docs/TESTING_STRATEGIES.md)** - Testing across crates

## 💡 Examples

Each crate includes comprehensive examples:

### Server Examples
- [Basic Server](crates/server/examples/basic_server.rs) - Direct main import
- [Custom Config Server](crates/server/examples/custom_config_server.rs) - Configuration-based
- [Extended Server](crates/server/examples/extended_server.rs) - Adding custom functionality
- [Modular Server](crates/server/examples/modular_server.rs) - Composition patterns

### Components Examples  
- [Basic Layout](crates/components/examples/basic_layout.rs) - Simple component usage
- [Navigation Demo](crates/components/examples/navigation_demo.rs) - Navigation patterns
- [Content Showcase](crates/components/examples/content_showcase.rs) - Content components

### Pages Examples
- [Basic Pages](crates/pages/examples/basic_pages.rs) - Simple page usage
- [Blog System](crates/pages/examples/blog_system.rs) - Complete blog implementation
- [Multi-language Pages](crates/pages/examples/multilang_pages.rs) - I18n support

## 🎨 Architecture Benefits

### 1. **True Library Pattern**
- Import main functions instead of copying code
- Reusable across multiple applications
- Clean separation between foundation and implementation

### 2. **Flexible Usage**
- Use as much or as little as needed
- Start simple, add complexity gradually
- Multiple integration patterns supported

### 3. **Comprehensive Documentation**
- Every crate includes usage patterns and examples
- Cross-crate integration guides
- Progressive complexity from beginner to advanced

### 4. **Type Safety**
- Shared types across all crates via core-types
- Consistent APIs and error handling
- Full Rust compiler guarantees

### 5. **Build System Integration**
- Exportable build functions from each crate
- Coordinated build processes
- Feature flag coordination

## 🛠️ Development Workflow

### For Application Developers
1. **Choose your pattern** - Direct import, configuration, or full integration
2. **Import foundation crates** - Add to Cargo.toml with needed features  
3. **Use foundation functions** - Import main functions, components, and utilities
4. **Extend as needed** - Add custom functionality on top of foundation
5. **Build with foundation** - Use foundation build utilities in build.rs

### For Foundation Contributors
1. **Maintain library pattern** - Exportable functions, not executables
2. **Comprehensive examples** - Every usage pattern documented
3. **Cross-crate consistency** - Shared types and patterns
4. **Backward compatibility** - Stable APIs for applications
5. **Integration testing** - Test across crate boundaries

## 🏁 Getting Started

### Quick Setup
```bash
# Clone or copy foundation crates
git clone https://github.com/yourusername/rustelo.git

# Create new application
cargo new my-rustelo-app
cd my-rustelo-app

# Add foundation dependencies to Cargo.toml
# See Quick Start section above

# Import and use foundation functions  
# See examples in each crate's examples/ directory
```

### Next Steps
1. **Read individual crate READMEs** for specific usage patterns
2. **Study the examples** to understand integration approaches
3. **Review the Integration Guide** for complete application patterns
4. **Start with simple patterns** and add complexity as needed
5. **Contribute improvements** back to the foundation

## 📈 Migration from Legacy

### From Executable Crates
If you were using foundation crates as executables:
1. **Change imports** - Import functions instead of running binaries
2. **Update build.rs** - Use foundation build functions  
3. **Adapt main.rs** - Import and call foundation main functions
4. **Review examples** - See new usage patterns

### From Custom Implementations
If you built custom implementations:
1. **Identify foundation equivalents** - Check what foundation provides
2. **Gradually migrate** - Replace custom code with foundation functions
3. **Extend foundation** - Add your custom logic on top of foundation
4. **Contribute back** - Share useful extensions with the community

## 🤝 Contributing

The foundation system is designed to grow:

1. **Add new patterns** - Document additional usage approaches
2. **Extend examples** - Show more integration scenarios  
3. **Improve documentation** - Clarify usage and patterns
4. **Add features** - Enhance foundation capabilities
5. **Fix issues** - Improve reliability and performance

## 📜 License

MIT License - See individual crate LICENSE files for details.

---

**The Rustelo Foundation: Building the future of Rust web applications, one library at a time.** 🦀✨