# ADR-003: Workspace Isolation\n\n## Status\n\nAccepted\n\n## Context\n\nProvisioning required a clear strategy for managing user-specific data, configurations,\nand customizations separate from system-wide installations. Key challenges included:\n\n1. **Configuration Conflicts**: User settings mixed with system defaults, causing unclear precedence\n2. **State Management**: User state (cache, logs, temporary files) scattered across filesystem\n3. **Customization Isolation**: User extensions and customizations affecting system behavior\n4. **Multi-User Support**: Multiple users on same system interfering with each other\n5. **Development vs Production**: Developer needs different from end-user needs\n6. **Path Resolution Complexity**: Complex logic to locate user-specific resources\n7. **Backup and Migration**: Difficulty backing up and migrating user-specific settings\n8. **Security Boundaries**: Need clear separation between system and user-writable areas\n\nThe system needed workspace isolation that provides:\n\n- Clear separation of user data from system installation\n- Predictable configuration precedence and inheritance\n- User-specific customization without system impact\n- Multi-user support on shared systems\n- Easy backup and migration of user settings\n- Security isolation between system and user areas\n\n## Decision\n\nImplement **isolated user workspaces** with clear boundaries and hierarchical configuration:\n\n### Workspace Structure\n\n```\n~/workspace/provisioning/           # User workspace root\n├── config/\n│   ├── user.toml                  # User preferences and overrides\n│   ├── environments/              # Environment-specific configs\n│   │   ├── dev.toml\n│   │   ├── test.toml\n│   │   └── prod.toml\n│   └── secrets/                   # User-specific encrypted secrets\n├── infra/                         # User infrastructure definitions\n│   ├── personal/                  # Personal infrastructure\n│   ├── work/                      # Work-related infrastructure\n│   └── shared/                    # Shared infrastructure definitions\n├── extensions/                    # User-installed extensions\n│   ├── providers/                 # Custom providers\n│   ├── taskservs/                 # Custom task services\n│   └── plugins/                   # User plugins\n├── templates/                     # User-specific templates\n├── cache/                         # Local cache and temporary data\n│   ├── provider-cache/            # Provider API cache\n│   ├── version-cache/             # Version information cache\n│   └── build-cache/               # Build and generation cache\n├── logs/                          # User-specific logs\n├── state/                         # Local state files\n└── backups/                       # Automatic workspace backups\n```\n\n### Configuration Hierarchy (Precedence Order)\n\n1. **Runtime Parameters** (command line, environment variables)\n2. **Environment Configuration** (`config/environments/{env}.toml`)\n3. **Infrastructure Configuration** (`infra/{name}/config.toml`)\n4. **Project Configuration** (project-specific settings)\n5. **User Configuration** (`config/user.toml`)\n6. **System Defaults** (system-wide defaults)\n\n### Key Isolation Principles\n\n1. **Complete Isolation**: User workspace completely independent of system installation\n2. **Hierarchical Inheritance**: Clear configuration inheritance with user overrides\n3. **Security Boundaries**: User workspace in user-writable area only\n4. **Multi-User Safe**: Multiple users can have independent workspaces\n5. **Portable**: Entire user workspace can be backed up and restored\n6. **Version Independent**: Workspace compatible across system version upgrades\n7. **Extension Safe**: User extensions cannot affect system behavior\n8. **State Isolation**: All user state contained within workspace\n\n## Consequences\n\n### Positive\n\n- **User Independence**: Users can customize without affecting system or other users\n- **Configuration Clarity**: Clear hierarchy and precedence for all configuration\n- **Security Isolation**: User modifications cannot compromise system installation\n- **Easy Backup**: Complete user environment can be backed up and restored\n- **Development Flexibility**: Developers can have multiple isolated workspaces\n- **System Upgrades**: System updates don't affect user customizations\n- **Multi-User Support**: Multiple users can work independently on same system\n- **Portable Configurations**: User workspace can be moved between systems\n- **State Management**: All user state in predictable locations\n\n### Negative\n\n- **Initial Setup**: Users must initialize workspace before first use\n- **Path Complexity**: More complex path resolution to support workspace isolation\n- **Disk Usage**: Each user maintains separate cache and state\n- **Configuration Duplication**: Some configuration may be duplicated across users\n- **Migration Overhead**: Existing users need workspace migration\n- **Documentation Complexity**: Need clear documentation for workspace management\n\n### Neutral\n\n- **Backup Strategy**: Users responsible for their own workspace backup\n- **Extension Management**: User-specific extension installation and management\n- **Version Compatibility**: Workspace versions must be compatible with system versions\n- **Performance Implications**: Additional path resolution overhead\n\n## Alternatives Considered\n\n### Alternative 1: System-Wide Configuration Only\n\nAll configuration in system directories with user overrides via environment variables.\n**Rejected**: Creates conflicts between users and makes customization difficult. Poor isolation and security.\n\n### Alternative 2: Home Directory Dotfiles\n\nUse traditional dotfile approach (~/.provisioning/).\n**Rejected**: Clutters home directory and provides less structured organization. Harder to backup and migrate.\n\n### Alternative 3: XDG Base Directory Specification\n\nFollow XDG specification for config/data/cache separation.\n**Rejected**: While standards-compliant, would fragment user data across multiple directories making management complex.\n\n### Alternative 4: Container-Based Isolation\n\nEach user gets containerized environment.\n**Rejected**: Too heavy for simple configuration isolation. Adds deployment complexity without sufficient benefits.\n\n### Alternative 5: Database-Based Configuration\n\nStore all user configuration in database.\n**Rejected**: Adds dependency complexity and makes backup/restore more difficult. Over-engineering for configuration needs.\n\n## Implementation Details\n\n### Workspace Initialization\n\n```\n# Automatic workspace creation on first run\nprovisioning workspace init\n\n# Manual workspace creation with template\nprovisioning workspace init --template=developer\n\n# Workspace status and validation\nprovisioning workspace status\nprovisioning workspace validate\n```\n\n### Configuration Resolution Process\n\n1. **Workspace Discovery**: Locate user workspace (env var → default location)\n2. **Configuration Loading**: Load configuration hierarchy with proper precedence\n3. **Path Resolution**: Resolve all paths relative to workspace and system installation\n4. **Variable Interpolation**: Process configuration variables and templates\n5. **Validation**: Validate merged configuration for completeness and correctness\n\n### Backup and Migration\n\n```\n# Backup entire workspace\nprovisioning workspace backup --output ~/backup/provisioning-workspace.tar.gz\n\n# Restore workspace from backup\nprovisioning workspace restore --input ~/backup/provisioning-workspace.tar.gz\n\n# Migrate workspace to new version\nprovisioning workspace migrate --from-version 2.0.0 --to-version 3.0.0\n```\n\n### Security Considerations\n\n- **File Permissions**: Workspace created with appropriate user permissions\n- **Secret Management**: Secrets encrypted and isolated within workspace\n- **Extension Sandboxing**: User extensions cannot access system directories\n- **Path Validation**: All paths validated to prevent directory traversal\n- **Configuration Validation**: User configuration validated against schemas\n\n## References\n\n- Distribution Strategy (ADR-002)\n- Configuration System Migration (CLAUDE.md)\n- Security Guidelines (Design Principles)\n- Extension Framework (ADR-005)\n- Multi-User Deployment Patterns
