provisioning/docs/src/architecture/adr/ADR-003-workspace-isolation.md

# ADR-003: Workspace Isolation

## Status

Accepted

## Context

Provisioning required a clear strategy for managing user-specific data, configurations,
and customizations separate from system-wide installations. Key challenges included:

1. **Configuration Conflicts**: User settings mixed with system defaults, causing unclear precedence
2. **State Management**: User state (cache, logs, temporary files) scattered across filesystem
3. **Customization Isolation**: User extensions and customizations affecting system behavior
4. **Multi-User Support**: Multiple users on same system interfering with each other
5. **Development vs Production**: Developer needs different from end-user needs
6. **Path Resolution Complexity**: Complex logic to locate user-specific resources
7. **Backup and Migration**: Difficulty backing up and migrating user-specific settings
8. **Security Boundaries**: Need clear separation between system and user-writable areas

The system needed workspace isolation that provides:

- Clear separation of user data from system installation
- Predictable configuration precedence and inheritance
- User-specific customization without system impact
- Multi-user support on shared systems
- Easy backup and migration of user settings
- Security isolation between system and user areas

## Decision

Implement **isolated user workspaces** with clear boundaries and hierarchical configuration:

### Workspace Structure

```bash
~/workspace/provisioning/           # User workspace root
├── config/
│   ├── user.toml                  # User preferences and overrides
│   ├── environments/              # Environment-specific configs
│   │   ├── dev.toml
│   │   ├── test.toml
│   │   └── prod.toml
│   └── secrets/                   # User-specific encrypted secrets
├── infra/                         # User infrastructure definitions
│   ├── personal/                  # Personal infrastructure
│   ├── work/                      # Work-related infrastructure
│   └── shared/                    # Shared infrastructure definitions
├── extensions/                    # User-installed extensions
│   ├── providers/                 # Custom providers
│   ├── taskservs/                 # Custom task services
│   └── plugins/                   # User plugins
├── templates/                     # User-specific templates
├── cache/                         # Local cache and temporary data
│   ├── provider-cache/            # Provider API cache
│   ├── version-cache/             # Version information cache
│   └── build-cache/               # Build and generation cache
├── logs/                          # User-specific logs
├── state/                         # Local state files
└── backups/                       # Automatic workspace backups
```

### Configuration Hierarchy (Precedence Order)

1. **Runtime Parameters** (command line, environment variables)
2. **Environment Configuration** (`config/environments/{env}.toml`)
3. **Infrastructure Configuration** (`infra/{name}/config.toml`)
4. **Project Configuration** (project-specific settings)
5. **User Configuration** (`config/user.toml`)
6. **System Defaults** (system-wide defaults)

### Key Isolation Principles

1. **Complete Isolation**: User workspace completely independent of system installation
2. **Hierarchical Inheritance**: Clear configuration inheritance with user overrides
3. **Security Boundaries**: User workspace in user-writable area only
4. **Multi-User Safe**: Multiple users can have independent workspaces
5. **Portable**: Entire user workspace can be backed up and restored
6. **Version Independent**: Workspace compatible across system version upgrades
7. **Extension Safe**: User extensions cannot affect system behavior
8. **State Isolation**: All user state contained within workspace

## Consequences

### Positive

- **User Independence**: Users can customize without affecting system or other users
- **Configuration Clarity**: Clear hierarchy and precedence for all configuration
- **Security Isolation**: User modifications cannot compromise system installation
- **Easy Backup**: Complete user environment can be backed up and restored
- **Development Flexibility**: Developers can have multiple isolated workspaces
- **System Upgrades**: System updates don't affect user customizations
- **Multi-User Support**: Multiple users can work independently on same system
- **Portable Configurations**: User workspace can be moved between systems
- **State Management**: All user state in predictable locations

### Negative

- **Initial Setup**: Users must initialize workspace before first use
- **Path Complexity**: More complex path resolution to support workspace isolation
- **Disk Usage**: Each user maintains separate cache and state
- **Configuration Duplication**: Some configuration may be duplicated across users
- **Migration Overhead**: Existing users need workspace migration
- **Documentation Complexity**: Need clear documentation for workspace management

### Neutral

- **Backup Strategy**: Users responsible for their own workspace backup
- **Extension Management**: User-specific extension installation and management
- **Version Compatibility**: Workspace versions must be compatible with system versions
- **Performance Implications**: Additional path resolution overhead

## Alternatives Considered

### Alternative 1: System-Wide Configuration Only

All configuration in system directories with user overrides via environment variables.
**Rejected**: Creates conflicts between users and makes customization difficult. Poor isolation and security.

### Alternative 2: Home Directory Dotfiles

Use traditional dotfile approach (~/.provisioning/).
**Rejected**: Clutters home directory and provides less structured organization. Harder to backup and migrate.

### Alternative 3: XDG Base Directory Specification

Follow XDG specification for config/data/cache separation.
**Rejected**: While standards-compliant, would fragment user data across multiple directories making management complex.

### Alternative 4: Container-Based Isolation

Each user gets containerized environment.
**Rejected**: Too heavy for simple configuration isolation. Adds deployment complexity without sufficient benefits.

### Alternative 5: Database-Based Configuration

Store all user configuration in database.
**Rejected**: Adds dependency complexity and makes backup/restore more difficult. Over-engineering for configuration needs.

## Implementation Details

### Workspace Initialization

```bash
# Automatic workspace creation on first run
provisioning workspace init

# Manual workspace creation with template
provisioning workspace init --template=developer

# Workspace status and validation
provisioning workspace status
provisioning workspace validate
```

### Configuration Resolution Process

1. **Workspace Discovery**: Locate user workspace (env var → default location)
2. **Configuration Loading**: Load configuration hierarchy with proper precedence
3. **Path Resolution**: Resolve all paths relative to workspace and system installation
4. **Variable Interpolation**: Process configuration variables and templates
5. **Validation**: Validate merged configuration for completeness and correctness

### Backup and Migration

```bash
# Backup entire workspace
provisioning workspace backup --output ~/backup/provisioning-workspace.tar.gz

# Restore workspace from backup
provisioning workspace restore --input ~/backup/provisioning-workspace.tar.gz

# Migrate workspace to new version
provisioning workspace migrate --from-version 2.0.0 --to-version 3.0.0
```

### Security Considerations

- **File Permissions**: Workspace created with appropriate user permissions
- **Secret Management**: Secrets encrypted and isolated within workspace
- **Extension Sandboxing**: User extensions cannot access system directories
- **Path Validation**: All paths validated to prevent directory traversal
- **Configuration Validation**: User configuration validated against schemas

## References

- Distribution Strategy (ADR-002)
- Configuration System Migration (CLAUDE.md)
- Security Guidelines (Design Principles)
- Extension Framework (ADR-005)
- Multi-User Deployment Patterns