provisioning/docs/src/architecture/adr/ADR-002-distribution-strategy.md

# ADR-002: Distribution Strategy

## Status

Accepted

## Context

Provisioning needed a clean distribution strategy that separates user-facing tools from development artifacts. Key challenges included:

1. **Development Artifacts Mixed with Production**: Build tools, test files, and development utilities scattered throughout user directories
2. **Complex Installation Process**: Users had to navigate through development-specific directories and files
3. **Unclear User Experience**: No clear distinction between what users need versus what developers need
4. **Configuration Complexity**: Multiple configuration files with unclear precedence and purpose
5. **Workspace Pollution**: User workspaces contained development-only files and directories
6. **Path Resolution Issues**: Complex path resolution logic mixing development and production concerns

The system required a distribution strategy that provides:

- Clean user experience without development artifacts
- Clear separation between user and development tools
- Simplified configuration management
- Consistent installation and deployment patterns
- Maintainable development workflow

## Decision

Implement a **layered distribution strategy** with clear separation between development and user environments:

### Distribution Layers

1. **Core Distribution Layer**: Essential user-facing components
   - Main CLI tools and libraries
   - Configuration templates and defaults
   - Provider implementations
   - Task service definitions

2. **Development Layer**: Development-specific tools and artifacts
   - Build scripts and development utilities
   - Test suites and validation tools
   - Development configuration templates
   - Code generation tools

3. **Workspace Layer**: User-specific customization and data
   - User configurations and overrides
   - Local state and cache files
   - Custom extensions and plugins
   - User-specific templates and workflows

### Distribution Structure

```
# User Distribution
/usr/local/bin/
├── provisioning              # Main CLI entry point
└── provisioning-*           # Supporting utilities

/usr/local/share/provisioning/
├── core/                    # Core libraries and modules
├── providers/               # Provider implementations
├── taskservs/              # Task service definitions
├── templates/              # Configuration templates
└── config.defaults.toml    # System-wide defaults

# User Workspace
~/workspace/provisioning/
├── config.user.toml        # User preferences
├── infra/                  # User infrastructure definitions
├── extensions/             # User extensions
└── cache/                  # Local cache and state

# Development Environment
<project-root>/
├── src/                    # Source code
├── scripts/                # Development tools
├── tests/                  # Test suites
└── tools/                  # Build and development utilities
```

### Key Distribution Principles

1. **Clean Separation**: Development artifacts never appear in user installations
2. **Hierarchical Configuration**: Clear precedence from system defaults to user overrides
3. **Self-Contained User Tools**: Users can work without accessing development directories
4. **Workspace Isolation**: User data and customizations isolated from system installation
5. **Consistent Paths**: Predictable path resolution across different installation types
6. **Version Management**: Clear versioning and upgrade paths for distributed components

## Consequences

### Positive

- **Clean User Experience**: Users interact only with production-ready tools and interfaces
- **Simplified Installation**: Clear installation process without development complexity
- **Workspace Isolation**: User customizations don't interfere with system installation
- **Development Efficiency**: Developers can work with full toolset without affecting users
- **Configuration Clarity**: Clear hierarchy and precedence for configuration settings
- **Maintainable Updates**: System updates don't affect user customizations
- **Path Simplicity**: Predictable path resolution without development-specific logic
- **Security Isolation**: User workspace separated from system components

### Negative

- **Distribution Complexity**: Multiple distribution targets require coordinated build processes
- **Path Management**: More complex path resolution logic to support multiple layers
- **Migration Overhead**: Existing users need to migrate to new workspace structure
- **Documentation Burden**: Need clear documentation for different user types
- **Testing Complexity**: Must validate distribution across different installation scenarios

### Neutral

- **Development Patterns**: Different patterns for development versus production deployment
- **Configuration Strategy**: Layer-specific configuration management approaches
- **Tool Integration**: Different integration patterns for development versus user tools

## Alternatives Considered

### Alternative 1: Monolithic Distribution

Ship everything (development and production) in single package.
**Rejected**: Creates confusing user experience and bloated installations. Mixes development concerns with user needs.

### Alternative 2: Container-Only Distribution

Package entire system as container images only.
**Rejected**: Limits deployment flexibility and complicates local development workflows. Not suitable for all use cases.

### Alternative 3: Source-Only Distribution

Require users to build from source with development environment.
**Rejected**: Creates high barrier to entry and mixes user concerns with development complexity.

### Alternative 4: Plugin-Based Distribution

Minimal core with everything else as downloadable plugins.
**Rejected**: Would fragment essential functionality and complicate initial setup. Network dependency for basic functionality.

### Alternative 5: Environment-Based Distribution

Use environment variables to control what gets installed.
**Rejected**: Creates complex configuration matrix and potential for inconsistent installations.

## Implementation Details

### Distribution Build Process

1. **Core Layer Build**: Extract essential user components from source
2. **Template Processing**: Generate configuration templates with proper defaults
3. **Path Resolution**: Generate path resolution logic for different installation types
4. **Documentation Generation**: Create user-specific documentation excluding development details
5. **Package Creation**: Build distribution packages for different platforms
6. **Validation Testing**: Test installations in clean environments

### Configuration Hierarchy

```
System Defaults (lowest precedence)
└── User Configuration
    └── Project Configuration
        └── Infrastructure Configuration
            └── Environment Configuration
                └── Runtime Configuration (highest precedence)
```

### Workspace Management

- **Automatic Creation**: User workspace created on first run
- **Template Initialization**: Workspace populated with configuration templates
- **Version Tracking**: Workspace tracks compatible system versions
- **Migration Support**: Automatic migration between workspace versions
- **Backup Integration**: Workspace backup and restore capabilities

## References

- Project Structure Decision (ADR-001)
- Workspace Isolation Decision (ADR-003)
- Configuration System Migration (CLAUDE.md)
- User Experience Guidelines (Design Principles)
- Installation and Deployment Procedures