# Developer Documentation

This directory contains comprehensive developer documentation for the provisioning project's new structure and development workflows.

## Documentation Suite

### Core Guides

1. **[Project Structure Guide](project-structure.md)** - Complete overview of the new vs existing structure, directory organization, and navigation guide
2. **[Build System Documentation](build-system.md)** - Comprehensive Makefile reference with 40+ targets, build tools, and cross-platform compilation
3. **[Workspace Management Guide](workspace-management.md)** - Development workspace setup, path resolution system, and runtime management
4. **[Development Workflow Guide](workflow.md)** - Daily development patterns, coding practices, testing strategies, and debugging techniques

### Advanced Topics

5. **[Extension Development Guide](extensions.md)** - Creating providers, task services, and clusters with templates and testing frameworks
6. **[Distribution Process Documentation](distribution-process.md)** - Release workflows, package generation, multi-platform distribution, and rollback procedures
7. **[Configuration Management](configuration.md)** - Configuration architecture, environment-specific settings, validation, and migration strategies
8. **[Integration Guide](integration.md)** - How new structure integrates with existing systems, API compatibility, and deployment considerations

## Quick Start

### For New Developers

1. **Setup Environment**: Follow [Workspace Management Guide](workspace-management.md#setup-and-initialization)
2. **Understand Structure**: Read [Project Structure Guide](project-structure.md#overview)
3. **Learn Workflows**: Study [Development Workflow Guide](workflow.md#daily-development-workflow)
4. **Build System**: Familiarize with [Build System Documentation](build-system.md#quick-start)

### For Extension Developers

1. **Extension Types**: Understand [Extension Development Guide](extensions.md#extension-types)
2. **Templates**: Use templates in `workspace/extensions/*/template/`
3. **Testing**: Follow [Extension Development Guide](extensions.md#testing-and-validation)
4. **Publishing**: Review [Extension Development Guide](extensions.md#publishing-and-distribution)

### For System Administrators

1. **Configuration**: Master [Configuration Management](configuration.md#configuration-architecture)
2. **Distribution**: Learn [Distribution Process Documentation](distribution-process.md#deployment-considerations)
3. **Integration**: Study [Integration Guide](integration.md#deployment-considerations)
4. **Monitoring**: Review [Integration Guide](integration.md#monitoring-and-observability)

## Architecture Overview

Provisioning has evolved to support a dual-organization approach:

- **`src/`**: Development-focused structure with build tools and core components
- **`workspace/`**: Development workspace with isolated environments and tools
- **Legacy**: Preserved existing functionality for backward compatibility

## Key Features

### Development Efficiency
- **Comprehensive Build System**: 40+ Makefile targets for all development needs
- **Workspace Isolation**: Per-developer isolated environments
- **Hot Reloading**: Development-time hot reloading support

### Production Reliability
- **Backward Compatibility**: All existing functionality preserved
- **Hybrid Architecture**: Rust orchestrator + Nushell business logic
- **Configuration-Driven**: Complete migration from ENV to TOML configuration
- **Zero-Downtime Deployment**: Seamless integration and migration strategies

### Extensibility
- **Template-Based Development**: Comprehensive templates for all extension types
- **Type-Safe Configuration**: KCL schemas with validation
- **Multi-Platform Support**: Cross-platform compilation and distribution
- **API Versioning**: Backward-compatible API evolution

## Development Tools

### Build System (`src/tools/`)
- **Makefile**: 40+ targets for comprehensive build management
- **Cross-Compilation**: Support for Linux, macOS, Windows
- **Distribution**: Automated package generation and validation
- **Release Management**: Complete CI/CD integration

### Workspace Tools (`workspace/tools/`)
- **workspace.nu**: Unified workspace management interface
- **Path Resolution**: Smart path resolution with workspace awareness
- **Health Monitoring**: Comprehensive health checks with automatic repairs
- **Extension Development**: Template-based extension development

### Migration Tools
- **Configuration Migration**: ENV to TOML migration utilities
- **Data Migration**: Database migration strategies and tools
- **Validation**: Comprehensive migration validation and verification

## Best Practices

### Code Quality
- **Configuration-Driven**: Never hardcode, always configure
- **Comprehensive Testing**: Unit, integration, and end-to-end testing
- **Error Handling**: Comprehensive error context and recovery
- **Documentation**: Self-documenting code with comprehensive guides

### Development Process
- **Test-First Development**: Write tests before implementation
- **Incremental Migration**: Gradual transition without disruption
- **Version Control**: Semantic versioning with automated changelog
- **Code Review**: Comprehensive review process with quality gates

### Deployment Strategy
- **Blue-Green Deployment**: Zero-downtime deployment strategies
- **Rolling Updates**: Gradual deployment with health validation
- **Monitoring**: Comprehensive observability and alerting
- **Rollback Procedures**: Safe rollback and recovery mechanisms

## Support and Troubleshooting

Each guide includes comprehensive troubleshooting sections:
- **Common Issues**: Frequently encountered problems and solutions
- **Debug Mode**: Comprehensive debugging tools and techniques
- **Performance Optimization**: Performance tuning and monitoring
- **Recovery Procedures**: Data recovery and system repair

## Contributing

When contributing to provisioning:
1. Follow the [Development Workflow Guide](workflow.md#collaboration-guidelines)
2. Use appropriate [Extension Development](extensions.md#best-practices) patterns
3. Ensure [Build System](build-system.md#ci-cd-integration) compatibility
4. Maintain [Integration](integration.md#api-compatibility-and-versioning) standards

## Migration Status

✅ **Configuration Migration Complete** (2025-09-23)
- 65+ files migrated across entire codebase
- Configuration system migration from ENV variables to TOML files
- Systematic migration with comprehensive validation

✅ **Documentation Suite Complete** (2025-09-25)
- 8 comprehensive developer guides
- Cross-referenced documentation with practical examples
- Complete troubleshooting and FAQ sections
- Integration with project build system

This documentation represents the culmination of the project's evolution from simple provisioning to a comprehensive, multi-language, enterprise-ready infrastructure automation platform.