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