provisioning/docs/src/architecture/adr/ADR-001-project-structure.md

# ADR-001: Project Structure Decision

## Status

Accepted

## Context

Provisioning had evolved from a monolithic structure into a complex system with mixed organizational patterns. The original structure had multiple issues:

1. **Provider-specific code scattered**: Cloud provider implementations were mixed with core logic
2. **Task services fragmented**: Infrastructure services lacked consistent structure
3. **Domain boundaries unclear**: No clear separation between core, providers, and services
4. **Development artifacts mixed with distribution**: User-facing tools mixed with development utilities
5. **Deep call stack limitations**: Nushell's runtime limitations required architectural solutions
6. **Configuration complexity**: 200+ environment variables across 65+ files needed systematic organization

The system needed a clear, maintainable structure that supports:

- Multi-provider infrastructure provisioning (AWS, UpCloud, local)
- Modular task services (Kubernetes, container runtimes, storage, networking)
- Clear separation of concerns
- Hybrid Rust/Nushell architecture
- Configuration-driven workflows
- Clean distribution without development artifacts

## Decision

Adopt a **domain-driven hybrid structure** organized around functional boundaries:

```plaintext
src/
├── core/           # Core system and CLI entry point
├── platform/       # High-performance coordination layer (Rust orchestrator)
├── orchestrator/   # Legacy orchestrator location (to be consolidated)
├── provisioning/   # Main provisioning with domain modules
├── control-center/ # Web UI management interface
├── tools/          # Development and utility tools
└── extensions/     # Plugin and extension framework
```

### Key Structural Principles

1. **Domain Separation**: Each major component has clear boundaries and responsibilities
2. **Hybrid Architecture**: Rust for performance-critical coordination, Nushell for business logic
3. **Provider Abstraction**: Standardized interfaces across cloud providers
4. **Service Modularity**: Reusable task services with consistent structure
5. **Clean Distribution**: Development tools separated from user-facing components
6. **Configuration Hierarchy**: Systematic config management with interpolation support

### Domain Organization

- **Core**: CLI interface, library modules, and common utilities
- **Platform**: High-performance Rust orchestrator for workflow coordination
- **Provisioning**: Main business logic with providers, task services, and clusters
- **Control Center**: Web-based management interface
- **Tools**: Development utilities and build systems
- **Extensions**: Plugin framework and custom extensions

## Consequences

### Positive

- **Clear Boundaries**: Each domain has well-defined responsibilities and interfaces
- **Scalable Growth**: New providers and services can be added without structural changes
- **Development Efficiency**: Developers can focus on specific domains without system-wide knowledge
- **Clean Distribution**: Users receive only necessary components without development artifacts
- **Maintenance Clarity**: Issues can be isolated to specific domains
- **Hybrid Benefits**: Leverage Rust performance where needed while maintaining Nushell productivity
- **Configuration Consistency**: Systematic approach to configuration management across all domains

### Negative

- **Migration Complexity**: Required systematic migration of existing components
- **Learning Curve**: New developers need to understand domain boundaries
- **Coordination Overhead**: Cross-domain features require careful interface design
- **Path Management**: More complex path resolution with domain separation
- **Build Complexity**: Multiple domains require coordinated build processes

### Neutral

- **Development Patterns**: Each domain may develop its own patterns within architectural guidelines
- **Testing Strategy**: Domain-specific testing strategies while maintaining integration coverage
- **Documentation**: Domain-specific documentation with clear cross-references

## Alternatives Considered

### Alternative 1: Monolithic Structure

Keep all code in a single flat structure with minimal organization.
**Rejected**: Would not solve maintainability or scalability issues. Continued technical debt accumulation.

### Alternative 2: Microservice Architecture

Split into completely separate services with network communication.
**Rejected**: Overhead too high for single-machine deployment use case. Would complicate installation and configuration.

### Alternative 3: Language-Based Organization

Organize by implementation language (rust/, nushell/, kcl/).
**Rejected**: Does not align with functional boundaries. Cross-cutting concerns would be scattered.

### Alternative 4: Feature-Based Organization

Organize by user-facing features (servers/, clusters/, networking/).
**Rejected**: Would duplicate cross-cutting infrastructure and provider logic across features.

### Alternative 5: Layer-Based Architecture

Organize by architectural layers (presentation/, business/, data/).
**Rejected**: Does not align with domain complexity. Infrastructure provisioning has different layering needs.

## References

- Configuration System Migration (ADR-002)
- Hybrid Architecture Decision (ADR-004)
- Extension Framework Design (ADR-005)
- Project Architecture Principles (PAP) Guidelines