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

~/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

# 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

# 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