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