add ADRs to the docs directory

docs/adr/0001-use-boltdb-as-local-storage.md

@@ -0,0 +1,35 @@
+# Use of BBolt as Local Storage
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Getting information from the cloud takes time
+- Need for local storage of lab configurations and state
+- Requirement for embedded database
+- Need for atomic operations
+- No requirement for concurrent access from multiple processes
+
+## Decision
+
+Use BBolt (github.com/etcd-io/bbolt) as the embedded key-value store
+
+## Consequences
+
+### Positive
+
+- Simple, reliable embedded storage
+- ACID compliant
+- No external dependencies
+- File-based, easy to backup
+
+### Negative
+
+- Limited to single process access
+- No built-in replication

docs/adr/0002-cloud-provider-interface.md

@@ -0,0 +1,32 @@
+# Cloud Provider Interface Design
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need to support multiple cloud providers
+- Requirement for consistent interface across providers
+- Need for mockable interface for testing
+
+## Decision
+
+Create abstract CloudProvider interface with provider-specific implementations
+
+## Consequences
+
+### Positive
+
+- Easy to add new providers
+- Consistent API across providers
+- Testable with mock implementations
+
+### Negative
+
+- May need to handle provider-specific features
+- Common interface might limit provider-specific capabilities

docs/adr/0003-cli-framework-selection.md

@@ -0,0 +1,34 @@
+# Use of Cobra for CLI Framework
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need for structured command-line interface
+- Requirement for sub-commands
+- Need for flag handling
+- Requirement for good documentation
+
+## Decision
+
+Use Cobra as the CLI framework
+
+## Consequences
+
+### Positive
+
+- Well-established framework
+- Good documentation
+- Built-in help generation
+- Consistent command structure
+
+### Negative
+
+- Additional dependency
+- Learning curve for new contributors

docs/adr/0004-configuration-management.md

@@ -0,0 +1,33 @@
+# Configuration Management with Viper
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need to handle multiple configuration sources
+- Requirement for environment variable support
+- Need for YAML/JSON configuration files
+
+## Decision
+
+Use Viper for configuration management
+
+## Consequences
+
+### Positive
+
+- Flexible configuration sources
+- Environment variable support
+- Type-safe configuration
+- Multiple format support
+
+### Negative
+
+- Additional dependency
+- Complex configuration precedence rules

docs/adr/0005-resource-definition-format.md

@@ -0,0 +1,34 @@
+# Kubernetes-style YAML Resource Definitions
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need for declarative resource definitions
+- Requirement for familiar format
+- Need for versioning and metadata
+
+## Decision
+
+Use Kubernetes-style YAML format for resource definitions
+
+## Consequences
+
+### Positive
+
+- Familiar to users of Kubernetes
+- Built-in versioning
+- Consistent metadata structure
+- Easy to validate
+- Separation between Spec and Status sections
+
+### Negative
+
+- May be overkill for simple resources
+- Learning curve for non-Kubernetes users

docs/adr/0006-ssh-key-management.md

@@ -0,0 +1,31 @@
+# SSH Key Management Strategy
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need for secure server access
+- Requirement for automated key generation
+
+## Decision
+
+Implement dedicated SSH key manager component that creates local keypairs in a specified directory
+
+## Consequences
+
+### Positive
+
+- Centralized key management
+- Automated key generation for servers and labs
+- Secure key handling
+
+### Negative
+
+- Additional complexity
+- Need for secure key storage

docs/adr/0007-error-handling-strategy.md

@@ -0,0 +1,32 @@
+# Error Handling and Logging
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need for consistent error handling
+- Requirement for detailed logging
+- Need for error recovery
+
+## Decision
+
+Use structured logging with slog and custom error types
+
+## Consequences
+
+### Positive
+
+- Consistent error handling
+- Structured logs
+- Better debugging
+
+### Negative
+
+- Additional error wrapping
+- More verbose error handling code

docs/adr/0008-resource-lifecycle-management.md

@@ -0,0 +1,32 @@
+# Resource Lifecycle Management
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need for resource cleanup
+- Requirement for TTL support
+- Need for dependency management
+
+## Decision
+
+Implement TTL-based lifecycle management with labels
+
+## Consequences
+
+### Positive
+
+- Automatic resource cleanup
+- Clear resource ownership
+- Managed dependencies
+
+### Negative
+
+- Complex cleanup logic
+- Need for background processes

docs/adr/0009-logging-strategy.md

@@ -0,0 +1,68 @@
+# Logging Strategy
+
+## Status
+
+Accepted
+
+## Date
+
+2024-12-12
+
+## Context
+
+- Need for consistent logging across the application
+- Requirement for different log levels (debug, info, error)
+- Need for structured logging to facilitate log analysis
+- Requirement for flexible log output formats (text, JSON)
+- Need to support both development and production environments
+
+## Decision
+
+Use Go's built-in `log/slog` package as the primary logging framework with the following principles:
+
+1. Structured Logging
+   - Use structured fields instead of string interpolation
+   - Include consistent field names across log entries
+
+2. Log Levels
+   - DEBUG: Detailed information for debugging
+   - INFO: General operational events
+   - WARN: Warning events that might need attention
+   - ERROR: Error events that need immediate attention
+
+3. Standard Context Fields
+   - timestamp
+   - level
+   - component
+   - operation
+   - error (when applicable)
+
+4. Configuration
+   - Allow log level configuration via config file and environment variables
+   - Support both text and JSON output formats
+   - Enable log level adjustment at runtime
+
+## Consequences
+
+### Positive
+
+- Built-in to Go 1.21+, no external dependencies
+- Structured logging makes log parsing and analysis easier
+- Consistent logging format across the application
+- Easy to integrate with log aggregation tools
+- Good performance characteristics
+- Type-safe field values
+
+### Negative
+
+- Requires Go 1.21 or later
+- More verbose than simple printf-style logging
+- Need to maintain consistent field names
+- May require additional configuration for advanced features
+
+## Related Decisions
+
+- [ADR-0004](0004-configuration-management.md) - Configuration Management with Viper
+- [ADR-0007](0007-error-handling-strategy.md) - Error Handling and Logging
+
+## Notes

docs/adr/index.md

@@ -0,0 +1,23 @@
+# Architecture Decision Records
+
+This directory contains Architecture Decision Records (ADRs) for the storctl project.
+
+## What is an ADR?
+
+An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
+
+## ADR List
+
+* [ADR-0001](0001-use-boltdb-as-local-storage.md) - Use of BBolt as Local Storage
+* [ADR-0002](0002-cloud-provider-interface.md) - Cloud Provider Interface Design
+* [ADR-0003](0003-cli-framework-selection.md) - Use of Cobra for CLI Framework
+* [ADR-0004](0004-configuration-management.md) - Configuration Management with Viper
+* [ADR-0005](0005-resource-definition-format.md) - Kubernetes-style YAML Resource Definitions
+* [ADR-0006](0006-ssh-key-management.md) - SSH Key Management Strategy
+* [ADR-0007](0007-error-handling-strategy.md) - Error Handling and Logging
+* [ADR-0008](0008-resource-lifecycle-management.md) - Resource Lifecycle Management
+* [ADR-0009](0009-logging-strategy.md) - Logging Strategy
+
+## ADR Template
+
+See [template.md](template.md) for the ADR template.

docs/adr/template.md

@@ -0,0 +1,35 @@
+# [Title]
+
+## Status
+
+[Proposed, Accepted, Deprecated, Superseded]
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+[Describe the context and problem statement that led to this decision]
+
+## Decision
+
+[Describe the decision that was made]
+
+## Consequences
+
+### Positive
+
+- [List positive consequences]
+
+### Negative
+
+- [List negative consequences]
+
+## Related Decisions
+
+- [List related ADRs or decisions]
+
+## Notes
+
+[Any additional notes or references]