# ADR-001: Project Structure Decision\n\n## Status\n\nAccepted\n\n## Context\n\nProvisioning had evolved from a monolithic structure into a complex system with mixed organizational patterns. The original structure had multiple issues:\n\n1. **Provider-specific code scattered**: Cloud provider implementations were mixed with core logic\n2. **Task services fragmented**: Infrastructure services lacked consistent structure\n3. **Domain boundaries unclear**: No clear separation between core, providers, and services\n4. **Development artifacts mixed with distribution**: User-facing tools mixed with development utilities\n5. **Deep call stack limitations**: Nushell's runtime limitations required architectural solutions\n6. **Configuration complexity**: 200+ environment variables across 65+ files needed systematic organization\n\nThe system needed a clear, maintainable structure that supports:\n\n- Multi-provider infrastructure provisioning (AWS, UpCloud, local)\n- Modular task services (Kubernetes, container runtimes, storage, networking)\n- Clear separation of concerns\n- Hybrid Rust/Nushell architecture\n- Configuration-driven workflows\n- Clean distribution without development artifacts\n\n## Decision\n\nAdopt a **domain-driven hybrid structure** organized around functional boundaries:\n\n```\nsrc/\n├── core/           # Core system and CLI entry point\n├── platform/       # High-performance coordination layer (Rust orchestrator)\n├── orchestrator/   # Legacy orchestrator location (to be consolidated)\n├── provisioning/   # Main provisioning with domain modules\n├── control-center/ # Web UI management interface\n├── tools/          # Development and utility tools\n└── extensions/     # Plugin and extension framework\n```\n\n### Key Structural Principles\n\n1. **Domain Separation**: Each major component has clear boundaries and responsibilities\n2. **Hybrid Architecture**: Rust for performance-critical coordination, Nushell for business logic\n3. **Provider Abstraction**: Standardized interfaces across cloud providers\n4. **Service Modularity**: Reusable task services with consistent structure\n5. **Clean Distribution**: Development tools separated from user-facing components\n6. **Configuration Hierarchy**: Systematic config management with interpolation support\n\n### Domain Organization\n\n- **Core**: CLI interface, library modules, and common utilities\n- **Platform**: High-performance Rust orchestrator for workflow coordination\n- **Provisioning**: Main business logic with providers, task services, and clusters\n- **Control Center**: Web-based management interface\n- **Tools**: Development utilities and build systems\n- **Extensions**: Plugin framework and custom extensions\n\n## Consequences\n\n### Positive\n\n- **Clear Boundaries**: Each domain has well-defined responsibilities and interfaces\n- **Scalable Growth**: New providers and services can be added without structural changes\n- **Development Efficiency**: Developers can focus on specific domains without system-wide knowledge\n- **Clean Distribution**: Users receive only necessary components without development artifacts\n- **Maintenance Clarity**: Issues can be isolated to specific domains\n- **Hybrid Benefits**: Leverage Rust performance where needed while maintaining Nushell productivity\n- **Configuration Consistency**: Systematic approach to configuration management across all domains\n\n### Negative\n\n- **Migration Complexity**: Required systematic migration of existing components\n- **Learning Curve**: New developers need to understand domain boundaries\n- **Coordination Overhead**: Cross-domain features require careful interface design\n- **Path Management**: More complex path resolution with domain separation\n- **Build Complexity**: Multiple domains require coordinated build processes\n\n### Neutral\n\n- **Development Patterns**: Each domain may develop its own patterns within architectural guidelines\n- **Testing Strategy**: Domain-specific testing strategies while maintaining integration coverage\n- **Documentation**: Domain-specific documentation with clear cross-references\n\n## Alternatives Considered\n\n### Alternative 1: Monolithic Structure\n\nKeep all code in a single flat structure with minimal organization.\n**Rejected**: Would not solve maintainability or scalability issues. Continued technical debt accumulation.\n\n### Alternative 2: Microservice Architecture\n\nSplit into completely separate services with network communication.\n**Rejected**: Overhead too high for single-machine deployment use case. Would complicate installation and configuration.\n\n### Alternative 3: Language-Based Organization\n\nOrganize by implementation language (rust/, nushell/, kcl/).\n**Rejected**: Does not align with functional boundaries. Cross-cutting concerns would be scattered.\n\n### Alternative 4: Feature-Based Organization\n\nOrganize by user-facing features (servers/, clusters/, networking/).\n**Rejected**: Would duplicate cross-cutting infrastructure and provider logic across features.\n\n### Alternative 5: Layer-Based Architecture\n\nOrganize by architectural layers (presentation/, business/, data/).\n**Rejected**: Does not align with domain complexity. Infrastructure provisioning has different layering needs.\n\n## References\n\n- Configuration System Migration (ADR-002)\n- Hybrid Architecture Decision (ADR-004)\n- Extension Framework Design (ADR-005)\n- Project Architecture Principles (PAP) Guidelines
