# Workspace Configuration Architecture\n\n**Version**: 2.0.0\n**Date**: 2025-10-06\n**Status**: Implemented\n\n## Overview\n\nThe provisioning system now uses a **workspace-based configuration architecture** where each workspace has its own complete configuration structure.\nThis replaces the old ENV-based and template-only system.\n\n## Critical Design Principle\n\n**`config.defaults.toml` is ONLY a template, NEVER loaded at runtime**\n\nThis file exists solely as a reference template for generating workspace configurations. The system does NOT load it during operation.\n\n## Configuration Hierarchy\n\nConfiguration is loaded in the following order (lowest to highest priority):\n\n1. **Workspace Config** (Base): `{workspace}/config/provisioning.yaml`\n2. **Provider Configs**: `{workspace}/config/providers/*.toml`\n3. **Platform Configs**: `{workspace}/config/platform/*.toml`\n4. **User Context**: `~/Library/Application Support/provisioning/ws_{name}.yaml`\n5. **Environment Variables**: `PROVISIONING_*` (highest priority)\n\n## Workspace Structure\n\nWhen a workspace is initialized, the following structure is created:\n\n```\n{workspace}/\n├── config/\n│   ├── provisioning.yaml       # Main workspace config (generated from template)\n│   ├── providers/              # Provider-specific configs\n│   │   ├── aws.toml\n│   │   ├── local.toml\n│   │   └── upcloud.toml\n│   ├── platform/               # Platform service configs\n│   │   ├── orchestrator.toml\n│   │   └── mcp.toml\n│   └── kms.toml                # KMS configuration\n├── infra/                      # Infrastructure definitions\n├── .cache/                     # Cache directory\n├── .runtime/                   # Runtime data\n│   ├── taskservs/\n│   └── clusters/\n├── .providers/                 # Provider state\n├── .kms/                       # Key management\n│   └── keys/\n├── generated/                  # Generated files\n└── .gitignore                  # Workspace gitignore\n```\n\n## Template System\n\nTemplates are located at: `/Users/Akasha/project-provisioning/provisioning/config/templates/`\n\n### Available Templates\n\n1. **workspace-provisioning.yaml.template** - Main workspace configuration\n2. **provider-aws.toml.template** - AWS provider configuration\n3. **provider-local.toml.template** - Local provider configuration\n4. **provider-upcloud.toml.template** - UpCloud provider configuration\n5. **kms.toml.template** - KMS configuration\n6. **user-context.yaml.template** - User context configuration\n\n### Template Variables\n\nTemplates support the following interpolation variables:\n\n- `{{workspace.name}}` - Workspace name\n- `{{workspace.path}}` - Absolute path to workspace\n- `{{now.iso}}` - Current timestamp in ISO format\n- `{{env.HOME}}` - User's home directory\n- `{{env.*}}` - Environment variables (safe list only)\n- `{{paths.base}}` - Base path (after config load)\n\n## Workspace Initialization\n\n### Command\n\n```\n# Using the workspace init function\nnu -c "use provisioning/core/nulib/lib_provisioning/workspace/init.nu *; \\n  workspace-init 'my-workspace' '/path/to/workspace' \\n  --providers ['aws' 'local'] --activate"\n```\n\n### Process\n\n1. **Create Directory Structure**: All necessary directories\n2. **Generate Config from Template**: Creates `config/provisioning.yaml`\n3. **Generate Provider Configs**: For each specified provider\n4. **Generate KMS Config**: Security configuration\n5. **Create User Context** (if --activate): User-specific overrides\n6. **Create .gitignore**: Ignore runtime/cache files\n\n## User Context\n\nUser context files are stored per workspace:\n\n**Location**: `~/Library/Application Support/provisioning/ws_{workspace_name}.yaml`\n\n### Purpose\n\n- Store user-specific overrides (debug settings, output preferences)\n- Mark active workspace\n- Override workspace paths if needed\n\n### Example\n\n```\nworkspace:\n  name: "my-workspace"\n  path: "/path/to/my-workspace"\n  active: true\n\ndebug:\n  enabled: true\n  log_level: "debug"\n\noutput:\n  format: "json"\n\nproviders:\n  default: "aws"\n```\n\n## Configuration Loading Process\n\n### 1. Determine Active Workspace\n\n```\n# Check user config directory for active workspace\nlet user_config_dir = ~/Library/Application Support/provisioning/\nlet active_workspace = (find workspace with active: true in ws_*.yaml files)\n```\n\n### 2. Load Workspace Config\n\n```\n# Load main workspace config\nlet workspace_config = {workspace.path}/config/provisioning.yaml\n```\n\n### 3. Load Provider Configs\n\n```\n# Merge all provider configs\nfor provider in {workspace.path}/config/providers/*.toml {\n  merge provider config\n}\n```\n\n### 4. Load Platform Configs\n\n```\n# Merge all platform configs\nfor platform in {workspace.path}/config/platform/*.toml {\n  merge platform config\n}\n```\n\n### 5. Apply User Context\n\n```\n# Apply user-specific overrides\nlet user_context = ~/Library/Application Support/provisioning/ws_{name}.yaml\nmerge user_context (highest config priority)\n```\n\n### 6. Apply Environment Variables\n\n```\n# Final overrides from environment\nPROVISIONING_DEBUG=true\nPROVISIONING_LOG_LEVEL=debug\nPROVISIONING_PROVIDER=aws\n# etc.\n```\n\n## Migration from Old System\n\n### Before (ENV-based)\n\n```\nexport PROVISIONING=/usr/local/provisioning\nexport PROVISIONING_INFRA_PATH=/path/to/infra\nexport PROVISIONING_DEBUG=true\n# ... many ENV variables\n```\n\n### After (Workspace-based)\n\n```\n# Initialize workspace\nworkspace-init "production" "/workspaces/prod" --providers ["aws"] --activate\n\n# All config is now in workspace\n# No ENV variables needed (except for overrides)\n```\n\n### Breaking Changes\n\n1. **`config.defaults.toml` NOT loaded** - Only used as template\n2. **Workspace required** - Must have active workspace or be in workspace directory\n3. **New config locations** - User config in `~/Library/Application Support/provisioning/`\n4. **YAML main config** - `provisioning.yaml` instead of TOML\n\n## Workspace Management Commands\n\n### Initialize Workspace\n\n```\nuse provisioning/core/nulib/lib_provisioning/workspace/init.nu *\nworkspace-init "my-workspace" "/path/to/workspace" --providers ["aws" "local"] --activate\n```\n\n### List Workspaces\n\n```\nworkspace-list\n```\n\n### Activate Workspace\n\n```\nworkspace-activate "my-workspace"\n```\n\n### Get Active Workspace\n\n```\nworkspace-get-active\n```\n\n## Implementation Files\n\n### Core Files\n\n1. **Template Directory**: `/Users/Akasha/project-provisioning/provisioning/config/templates/`\n2. **Workspace Init**: `/Users/Akasha/project-provisioning/provisioning/core/nulib/lib_provisioning/workspace/init.nu`\n3. **Config Loader**: `/Users/Akasha/project-provisioning/provisioning/core/nulib/lib_provisioning/config/loader.nu`\n\n### Key Changes in Config Loader\n\n#### Removed\n\n- `get-defaults-config-path()` - No longer loads config.defaults.toml\n- Old hierarchy with user/project/infra TOML files\n\n#### Added\n\n- `get-active-workspace()` - Finds active workspace from user config\n- Support for YAML config files\n- Provider and platform config merging\n- User context loading\n\n## Configuration Schema\n\n### Main Workspace Config (provisioning.yaml)\n\n```\nworkspace:\n  name: string\n  version: string\n  created: timestamp\n\npaths:\n  base: string\n  infra: string\n  cache: string\n  runtime: string\n  # ... all paths\n\ncore:\n  version: string\n  name: string\n\ndebug:\n  enabled: bool\n  log_level: string\n  # ... debug settings\n\nproviders:\n  active: [string]\n  default: string\n\n# ... all other sections\n```\n\n### Provider Config (providers/*.toml)\n\n```\n[provider]\nname = "aws"\nenabled = true\nworkspace = "workspace-name"\n\n[provider.auth]\nprofile = "default"\nregion = "us-east-1"\n\n[provider.paths]\nbase = "{workspace}/.providers/aws"\ncache = "{workspace}/.providers/aws/cache"\n```\n\n### User Context (ws_{name}.yaml)\n\n```\nworkspace:\n  name: string\n  path: string\n  active: bool\n\ndebug:\n  enabled: bool\n  log_level: string\n\noutput:\n  format: string\n```\n\n## Benefits\n\n1. **No Template Loading**: config.defaults.toml is template-only\n2. **Workspace Isolation**: Each workspace is self-contained\n3. **Explicit Configuration**: No hidden defaults from ENV\n4. **Clear Hierarchy**: Predictable override behavior\n5. **Multi-Workspace Support**: Easy switching between workspaces\n6. **User Overrides**: Per-workspace user preferences\n7. **Version Control**: Workspace configs can be committed (except secrets)\n\n## Security Considerations\n\n### Generated .gitignore\n\nThe workspace .gitignore excludes:\n\n- `.cache/` - Cache files\n- `.runtime/` - Runtime data\n- `.providers/` - Provider state\n- `.kms/keys/` - Secret keys\n- `generated/` - Generated files\n- `*.log` - Log files\n\n### Secret Management\n\n- KMS keys stored in `.kms/keys/` (gitignored)\n- SOPS config references keys, doesn't store them\n- Provider credentials in user-specific locations (not workspace)\n\n## Troubleshooting\n\n### No Active Workspace Error\n\n```\nError: No active workspace found. Please initialize or activate a workspace.\n```\n\n**Solution**: Initialize or activate a workspace:\n\n```\nworkspace-init "my-workspace" "/path/to/workspace" --activate\n```\n\n### Config File Not Found\n\n```\nError: Required configuration file not found: {workspace}/config/provisioning.yaml\n```\n\n**Solution**: The workspace config is corrupted or deleted. Re-initialize:\n\n```\nworkspace-init "workspace-name" "/existing/path" --providers ["aws"]\n```\n\n### Provider Not Configured\n\n**Solution**: Add provider config to workspace:\n\n```\n# Generate provider config manually\ngenerate-provider-config "/workspace/path" "workspace-name" "aws"\n```\n\n## Future Enhancements\n\n1. **Workspace Templates**: Pre-configured workspace templates (dev, prod, test)\n2. **Workspace Import/Export**: Share workspace configurations\n3. **Remote Workspace**: Load workspace from remote Git repository\n4. **Workspace Validation**: Comprehensive workspace health checks\n5. **Config Migration Tool**: Automated migration from old ENV-based system\n\n## Summary\n\n- **config.defaults.toml is ONLY a template** - Never loaded at runtime\n- **Workspaces are self-contained** - Complete config structure generated from templates\n- **New hierarchy**: Workspace → Provider → Platform → User Context → ENV\n- **User context for overrides** - Stored in ~/Library/Application Support/provisioning/\n- **Clear, explicit configuration** - No hidden defaults\n\n## Related Documentation\n\n- Template files: `provisioning/config/templates/`\n- Workspace init: `provisioning/core/nulib/lib_provisioning/workspace/init.nu`\n- Config loader: `provisioning/core/nulib/lib_provisioning/config/loader.nu`\n- User guide: `docs/user/workspace-management.md`
