provisioning/docs/src/architecture/README.md

# Architecture Documentation

This directory contains comprehensive architecture documentation for provisioning, including Architecture Decision Records (ADRs) and system design documentation.

## Architecture Decision Records (ADRs)

ADRs document the major architectural decisions made for the system, including context, rationale, and consequences:

- **[ADR-001: Project Structure Decision](adr/adr-001-project-structure.md)** - Domain-driven hybrid structure organization
- **[ADR-002: Distribution Strategy](adr/adr-002-distribution-strategy.md)** - Layered distribution with workspace separation
- **[ADR-003: Workspace Isolation](adr/adr-003-workspace-isolation.md)** - Isolated user workspaces with hierarchical configuration
- **[ADR-004: Hybrid Architecture](adr/adr-004-hybrid-architecture.md)** - Rust coordination layer with Nushell business logic
- **[ADR-005: Extension Framework](adr/adr-005-extension-framework.md)** - Registry-based extension system with manifest-driven loading

## System Design Documentation

Comprehensive documentation covering system architecture, integration patterns, and design principles:

### [System Overview](system-overview.md)

High-level architecture overview including:

- Executive summary and key achievements
- Component architecture with diagrams
- Technology stack and dependencies
- Performance and scalability characteristics
- Security architecture and quality attributes

### [Integration Patterns](integration-patterns.md)

Detailed integration patterns and implementations:

- Hybrid language integration (Rust ↔ Nushell)
- Provider abstraction and multi-cloud support
- Configuration resolution and variable interpolation
- Workflow orchestration and dependency management
- State management and checkpoint recovery
- Event-driven architecture and messaging
- Extension integration and API patterns
- Error handling and performance optimization

### [Design Principles](design-principles.md)

Core architectural principles and guidelines:

- Project Architecture Principles (PAP) compliance
- Hybrid architecture optimization strategies
- Configuration-first architecture approach
- Domain-driven structural organization
- Quality attribute principles (reliability, performance, security)
- Error handling and observability principles
- Evolution and maintenance strategies

## Key Architectural Achievements

### 🚀 Batch Workflow System (v3.1.0)

- **Provider-Agnostic Design**: Mixed UpCloud, AWS, and local provider support
- **Advanced Orchestration**: Dependency resolution, parallel execution, and rollback capabilities
- **Real-time Monitoring**: Live workflow progress tracking and health monitoring

### 🏗️ Hybrid Orchestrator Architecture (v3.0.0)

- **Performance Solution**: Solves Nushell deep call stack limitations
- **Business Logic Preservation**: 65+ Nushell files with domain expertise maintained
- **REST API Integration**: Modern HTTP endpoints for external system integration
- **State Management**: Checkpoint-based recovery with comprehensive rollback

### ⚙️ Configuration System (v2.0.0)

- **Configuration Migration**: Systematic migration from ENV variables to configuration files
- **Hierarchical Configuration**: Complete configuration flexibility with clear precedence
- **Variable Interpolation**: Dynamic configuration with runtime variable resolution
- **PAP Compliance**: True Infrastructure as Code without hardcoded fallbacks

## Reading Guide

### For New Developers

1. Start with [System Overview](system-overview.md) for high-level understanding
2. Read [Design Principles](design-principles.md) to understand architectural philosophy
3. Review relevant ADRs for specific architectural decisions
4. Study [Integration Patterns](integration-patterns.md) for implementation details

### For Architects and Senior Developers

1. Review all ADRs to understand decision rationale and trade-offs
2. Study [Integration Patterns](integration-patterns.md) for advanced implementation patterns
3. Reference [Design Principles](design-principles.md) for architectural guidelines
4. Use [System Overview](system-overview.md) for comprehensive system understanding

### For System Operators

1. Focus on [System Overview](system-overview.md) for deployment and operation insights
2. Review [ADR-002: Distribution Strategy](adr/adr-002-distribution-strategy.md) for deployment patterns
3. Study [ADR-003: Workspace Isolation](adr/adr-003-workspace-isolation.md) for user management
4. Reference [Design Principles](design-principles.md) for operational guidelines

## Document Evolution

These architecture documents are living resources that evolve with the system:

- **ADRs are immutable** once accepted, with new ADRs created for major changes
- **System documentation is updated** to reflect current architecture
- **Cross-references are maintained** between related documents
- **Version compatibility** is documented for architectural changes

## Contributing to Architecture Documentation

When making significant architectural changes:

1. **Create new ADRs** for major decisions using the standard format
2. **Update system documentation** to reflect architectural changes
3. **Maintain cross-references** between related documents
4. **Document trade-offs** and alternatives considered
5. **Update integration patterns** for new architectural patterns

## Architecture Review Process

All significant architectural changes follow a review process:

1. **Proposal Phase**: Create draft ADR with context and proposed decision
2. **Review Phase**: Technical review by architecture team and stakeholders
3. **Decision Phase**: Accept, modify, or reject based on review feedback
4. **Documentation Phase**: Update related documentation and integration patterns
5. **Implementation Phase**: Guide implementation according to architectural decisions

This architecture documentation represents the collective wisdom and experience of building a sophisticated, production-ready infrastructure automation platform.