Rustelo/docs/architecture/overview.md

Rustelo Feature-Based Architecture Overview

Architecture Vision

Rustelo has been transformed from a basic framework into a modular, feature-composable system that preserves all advanced functionality from p-jpl-website while enabling clean composition and reuse.

Core Structure

rustelo/
├── framework/           # Core framework crates
│   └── crates/
│       ├── rustelo-core/
│       ├── rustelo-web/
│       ├── rustelo-auth/
│       ├── rustelo-content/
│       └── rustelo-cli/     # Enhanced CLI with feature management
├── foundation/          # Advanced blueprint from p-jpl-website
│   └── crates/
│       ├── client/          # Advanced Leptos client
│       ├── server/          # Advanced Axum server
│       ├── core-lib/        # Sophisticated shared library
│       ├── core-types/      # Enhanced type system
│       ├── components/      # Rich UI component library
│       ├── pages/           # Advanced page generation
│       ├── tools/           # Development tools and analytics
│       └── utils/           # Utility functions
├── features/            # Modular features
│   ├── analytics/           # Comprehensive analytics system
│   ├── smart-build/         # Incremental build system
│   ├── debugging-tools/     # Enhanced debugging capabilities
│   └── ui-components/       # Reusable Leptos components
├── registry/            # Central configuration
│   ├── dependencies.toml   # Centralized dependency versions
│   └── features.toml       # Feature registry and metadata
└── templates/           # Project scaffolding templates

Key Architectural Principles

1. Language Agnostic Design

• No hardcoded languages in the framework
• Dynamic language discovery from configuration
• i18n integration with Fluent files
• Language-specific routing without code changes

2. Configuration-Driven Architecture

• All paths configurable via environment variables
• Route definitions in TOML files, not code
• Content types via content-kinds.toml
• Feature composition through configuration

3. Modular Design

• Features are self-contained and composable
• Clean interfaces between components
• Dependency injection patterns
• Zero breaking changes policy

4. Dependency Priority System

• p-jpl-website dependencies take priority
• Registry-based version management
• Conflict detection and resolution
• Workspace dependency coordination

Integration Levels

The system provides integration at all stack levels:

1. Dependencies

• Cargo.toml: Workspace dependencies and external crates
• package.json: Node.js dependencies for tooling
• Registry: Centralized version management

2. Environment

• .env: Environment variables and configuration
• Secrets: Secure handling of sensitive values
• Defaults: Sensible default values

3. Configuration

• TOML/JSON: Intelligent config file merging
• Override: Feature-specific configuration
• Validation: Configuration integrity checks

4. Resources

• Public: Static assets (JS, CSS, images)
• Site: Content and documentation files
• i18n: Translation files (Fluent .ftl)

5. Styling

• UnoCSS: Atomic CSS with feature presets
• Themes: Feature-specific theme extensions
• Components: Styled component libraries

6. Infrastructure

• Docker: Service composition and deployment
• CI/CD: Automated testing and deployment
• Monitoring: Observability and alerting

7. Development

• Scripts: Nushell automation scripts
• Just: Task runner integration
• Git: Hooks and workflow automation

Feature Lifecycle

Discovery → Installation → Configuration → Integration → Usage → Removal

Discovery

• Browse available features in registry
• Check feature compatibility
• Review feature documentation

Installation

• Dependency resolution and conflict detection
• Resource copying and integration
• Configuration merging and validation

Configuration

• Environment variable setup
• Feature-specific configuration
• Integration validation

Integration

• All stack levels integrated automatically
• Dependency injection and wiring
• Testing and validation

Usage

• Feature APIs and functionality available
• Documentation and examples provided
• Monitoring and analytics enabled

Removal

• Clean removal of all feature artifacts
• Dependency cleanup and validation
• Configuration restoration

Migration Strategy

The architecture preserves backward compatibility while enabling gradual migration:

1. Existing rustelo users: Continue using basic functionality
2. p-jpl-website users: Full feature set available as composable features
3. New users: Start with foundation + selected features
4. Advanced users: Create custom features and compositions

Success Metrics

✅ Achieved Goals:

• All p-jpl-website functionality preserved as features
• Zero hardcoded dependencies or paths
• Clean feature addition/removal
• No breaking changes for existing users
• Single command project creation
• Complete resource integration
• Feature composition without conflicts
• Clean separation of concerns