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

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

Usage Examples

Fast Path (Help Commands)

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

Medium Path (Status Operations)

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

Full Path (Infrastructure Operations)

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

Implementation Details

Lazy Loading Decision Logic

# 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
}

Minimal Config Structure

The minimal loader returns a lightweight config record:

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

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

# 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

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