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/ - Server-side library with importable main functions, routing, and middleware
• client/ - Client-side library with app mounting, hydration, and state management
• core-lib/ - Shared utilities, configuration, i18n, and business logic
• core-types/ - Common type definitions and data structures

UI System

• components/ - Reusable UI component library with theming support
• pages/ - Page generation system with templates and content processing

🚀 Quick Start

1. Import Foundation Libraries

// 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

// 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

// 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

// 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:

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:

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:

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:

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 - Server-side library usage
• Client Foundation - Client-side library usage
• Components Foundation - UI component library
• Pages Foundation - Page generation system
• Core Lib Foundation - Shared utilities
• Core Types Foundation - Type definitions

Integration Guides

• Foundation Integration Guide - Complete integration examples
• Cross-Crate Patterns - Communication patterns
• Build System Integration - Build system usage
• Testing Strategies - Testing across crates

💡 Examples

Each crate includes comprehensive examples:

Server Examples

• Basic Server - Direct main import
• Custom Config Server - Configuration-based
• Extended Server - Adding custom functionality
• Modular Server - Composition patterns

Components Examples

• Basic Layout - Simple component usage
• Navigation Demo - Navigation patterns
• Content Showcase - Content components

Pages Examples

• Basic Pages - Simple page usage
• Blog System - Complete blog implementation
• Multi-language Pages - 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

# 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. 🦀✨