provisioning/docs/src/architecture/config-loading-architecture.md

# Modular Configuration Loading Architecture

## Overview

The configuration system has been refactored into modular components to achieve 2-3x performance improvements
for regular commands while maintaining full functionality for complex operations.

## Architecture Layers

### Layer 1: Minimal Loader (0.023s)

**File**: `loader-minimal.nu` (~150 lines)

Contains only essential functions needed for:

- Workspace detection
- Environment determination
- Project root discovery
- Fast path detection

**Exported Functions**:

- `get-active-workspace` - Get current workspace
- `detect-current-environment` - Determine dev/test/prod
- `get-project-root` - Find project directory
- `get-defaults-config-path` - Path to default config
- `check-if-sops-encrypted` - SOPS file detection
- `find-sops-config-path` - Locate SOPS config

**Used by**:

- Help commands (help infrastructure, help workspace, etc.)
- Status commands
- Workspace listing
- Quick reference operations

### Layer 2: Lazy Loader (decision layer)

**File**: `loader-lazy.nu` (~80 lines)

Smart loader that decides which configuration to load:

- Fast path for help/status commands
- Full path for operations that need config

**Key Function**:

- `command-needs-full-config` - Determines if full config required

### Layer 3: Full Loader (0.091s)

**File**: `loader.nu` (1990 lines)

Original comprehensive loader that handles:

- Hierarchical config loading
- Variable interpolation
- Config validation
- Provider configuration
- Platform configuration

**Used by**:

- Server creation
- Infrastructure operations
- Deployment commands
- Anything needing full config

## Performance Characteristics

### Benchmarks

| Operation | Time | Notes |
| --------- | ---- | ----- |
| Workspace detection | 0.023s | 23ms for minimal load |
| Full config load | 0.091s | ~4x slower than minimal |
| Help command | 0.040s | Uses minimal loader only |
| Status command | 0.030s | Fast path, no full config |
| Server operations | 0.150s+ | Requires full config load |

### Performance Gains

- **Help commands**: 30-40% faster (40ms vs 60ms with full config)
- **Workspace operations**: 50% faster (uses minimal loader)
- **Status checks**: Nearly instant (23ms)

## Module Dependency Graph

```plaintext
Help/Status Commands
    ↓
loader-lazy.nu
    ↓
loader-minimal.nu (workspace, environment detection)
    ↓
     (no further deps)

Infrastructure/Server Commands
    ↓
loader-lazy.nu
    ↓
loader.nu (full configuration)
    ├── loader-minimal.nu (for workspace detection)
    ├── Interpolation functions
    ├── Validation functions
    └── Config merging logic
```plaintext

## Usage Examples

### Fast Path (Help Commands)

```nushell
# Uses minimal loader - 23ms
./provisioning help infrastructure
./provisioning workspace list
./provisioning version
```plaintext

### Medium Path (Status Operations)

```nushell
# Uses minimal loader with some full config - ~50ms
./provisioning status
./provisioning workspace active
./provisioning config validate
```plaintext

### Full Path (Infrastructure Operations)

```nushell
# Uses full loader - ~150ms
./provisioning server create --infra myinfra
./provisioning taskserv create kubernetes
./provisioning workflow submit batch.yaml
```plaintext

## Implementation Details

### Lazy Loading Decision Logic

```nushell
# In loader-lazy.nu
let is_fast_command = (
    $command == "help" or
    $command == "status" or
    $command == "version"
)

if $is_fast_command {
    # Use minimal loader only (0.023s)
    get-minimal-config
} else {
    # Load full configuration (0.091s)
    load-provisioning-config
}
```plaintext

### Minimal Config Structure

The minimal loader returns a lightweight config record:

```nushell
{
    workspace: {
        name: "librecloud"
        path: "/path/to/workspace_librecloud"
    }
    environment: "dev"
    debug: false
    paths: {
        base: "/path/to/workspace_librecloud"
    }
}
```plaintext

This is sufficient for:

- Workspace identification
- Environment determination
- Path resolution
- Help text generation

### Full Config Structure

The full loader returns comprehensive configuration with:

- Workspace settings
- Provider configurations
- Platform settings
- Interpolated variables
- Validation results
- Environment-specific overrides

## Migration Path

### For CLI Commands

1. Commands are already categorized (help, workspace, server, etc.)
2. Help system uses fast path (minimal loader)
3. Infrastructure commands use full path (full loader)
4. No changes needed to command implementations

### For New Modules

When creating new modules:

1. Check if full config is needed
2. If not, use `loader-minimal.nu` functions only
3. If yes, use `get-config` from main config accessor

## Future Optimizations

### Phase 2: Per-Command Config Caching

- Cache full config for 60 seconds
- Reuse config across related commands
- Potential: Additional 50% improvement

### Phase 3: Configuration Profiles

- Create thin config profiles for common scenarios
- Pre-loaded templates for workspace/infra combinations
- Fast switching between profiles

### Phase 4: Parallel Config Loading

- Load workspace and provider configs in parallel
- Async validation and interpolation
- Potential: 30% improvement for full config load

## Maintenance Notes

### Adding New Functions to Minimal Loader

Only add if:

1. Used by help/status commands
2. Doesn't require full config
3. Performance-critical path

### Modifying Full Loader

- Changes are backward compatible
- Validate against existing config files
- Update tests in test suite

### Performance Testing

```bash
# Benchmark minimal loader
time nu -n -c "use loader-minimal.nu *; get-active-workspace"

# Benchmark full loader
time nu -c "use config/accessor.nu *; get-config"

# Benchmark help command
time ./provisioning help infrastructure
```plaintext

## See Also

- `loader.nu` - Full configuration loading system
- `loader-minimal.nu` - Fast path loader
- `loader-lazy.nu` - Smart loader decision logic
- `config/ARCHITECTURE.md` - Configuration architecture details