docs: [#28] finalize configuration architecture standardization plan

- Document comprehensive per-environment configuration architecture
- Create ADR-008 for per-environment application configuration storage
- Establish enhanced deployment workflow with validation gates
- Define per-environment storage structure in application/config/{environment}/
- Add environment-configuration matching validation system
- Remove alternative simplified approach documentation
- Set foundation for Phase 1 implementation (infrastructure scope reduction)

Addresses architectural inconsistency blocking staging deployment in Issue #28

Author: josecelano

application/config/templates/.gitkeep

@@ -0,0 +1,276 @@
+# ADR-008: Per-Environment Application Configuration Storage
+
+## Status
+
+Proposed
+
+## Date
+
+2025-08-06
+
+## Context
+
+During the configuration architecture standardization for Issue #28 (Hetzner infrastructure
+implementation), we needed to decide how to store and manage application configuration files
+that are generated from templates.
+
+### Previous Approach
+
+The original approach considered using a single shared storage location (`application/storage/`)
+for all application configurations with runtime environment detection to prevent mismatches.
+
+This approach had several limitations:
+
+1. **No Configuration Tracking**: Generated configurations weren't stored per environment
+2. **No Customization Support**: Users couldn't customize configuration per environment
+3. **No Backup Capability**: Configuration couldn't be version-controlled or backed up
+4. **Complex Mismatch Prevention**: Required runtime validation and metadata files
+5. **Limited Testing**: Couldn't easily test environment-specific configurations locally
+
+### Configuration Management Requirements
+
+The system needs to support:
+
+- **Multiple Environments**: Local testing, staging, production deployments
+- **Configuration Customization**: Users should be able to modify configs per environment
+- **Version Control**: Configuration changes should be trackable
+- **Local Testing**: Ability to test environment configurations without VM deployment
+- **Backup and Restore**: Easy backup of environment-specific configurations
+- **Clear Audit Trail**: Visibility into configuration changes per environment
+
+## Decision
+
+We will store application configurations in **per-environment folders** under
+`application/config/{environment}/` where `{environment}` matches the environment file name
+from `infrastructure/config/environments/`.
+
+### Directory Structure
+
+```text
+application/config/
+├── e2e-libvirt/                 # Local testing environment
+│   ├── tracker/etc/tracker.toml
+│   ├── proxy/etc/nginx.conf
+│   ├── prometheus/etc/prometheus.yml
+│   ├── compose/.env
+│   └── .environment            # Environment metadata
+├── staging-hetzner/             # Staging environment
+│   ├── tracker/etc/tracker.toml
+│   ├── proxy/etc/nginx.conf
+│   ├── prometheus/etc/prometheus.yml
+│   ├── compose/.env
+│   └── .environment            # Environment metadata
+└── production-hetzner/          # Production environment
+    ├── tracker/etc/tracker.toml
+    ├── proxy/etc/nginx.conf
+    ├── prometheus/etc/prometheus.yml
+    ├── compose/.env
+    └── .environment            # Environment metadata
+```
+
+### Environment Naming Convention
+
+Environment folder names **must match** the environment file names in
+`infrastructure/config/environments/`:
+
+- `e2e-libvirt` → `infrastructure/config/environments/e2e-libvirt.env`
+- `staging-hetzner` → `infrastructure/config/environments/staging-hetzner.env`
+- `production-hetzner` → `infrastructure/config/environments/production-hetzner.env`
+
+## Rationale
+
+### Benefits of Per-Environment Storage
+
+1. **Configuration Customization**:
+
+   - Users can manually modify configurations per environment
+   - Changes persist across regeneration cycles
+   - Environment-specific tuning and optimization
+
+2. **Version Control and Backup**:
+
+   - Each environment's configuration can be committed to git
+   - Easy to track configuration changes over time
+   - Backup and restore capabilities per environment
+
+3. **Local Testing Support**:
+
+   - Users can copy environment configs to `application/storage/` for local testing
+   - Test production configurations without VM overhead
+   - Debug configuration issues before deployment
+
+4. **Clear Environment Separation**:
+
+   - No risk of configuration pollution between environments
+   - Visual separation of environment concerns
+   - Easy to compare configurations across environments
+
+5. **Simplified Deployment**:
+
+   - No runtime environment detection needed
+   - Clear mapping between environment file and configuration folder
+   - Reduced complexity in deployment scripts
+
+6. **Audit Trail**:
+   - Clear visibility into what configuration each environment uses
+   - Easy to see configuration differences between environments
+   - Trackable configuration evolution per environment
+
+### Environment Validation
+
+The deployment process validates environment-configuration matching:
+
+```bash
+# Generate configuration for specific environment
+make app-config ENVIRONMENT_FILE=staging-hetzner
+
+# Deploy using that environment's configuration
+make app-deploy ENVIRONMENT_FILE=staging-hetzner
+```
+
+The system validates that:
+
+1. Configuration folder `application/config/staging-hetzner/` exists
+2. Environment metadata matches the deployment target
+3. All required configuration files are present and valid
+
+### Local Testing Workflow
+
+Users can test environment-specific configurations locally:
+
+```bash
+# Generate staging configuration
+make app-config ENVIRONMENT_FILE=staging-hetzner
+
+# Copy to storage for local testing
+cp -r application/config/staging-hetzner/* application/storage/
+
+# Test locally
+cd application
+docker compose up -d
+```
+
+## Consequences
+
+### Positive
+
+- **Environment Isolation**: Clear separation between environment configurations
+- **Customization Support**: Users can modify configurations per environment
+- **Version Control**: Configuration changes are trackable and revertible
+- **Local Testing**: Easy to test environment configurations without deployment
+- **Backup Capability**: Environment configurations can be backed up and restored
+- **Simplified Deployment**: Clear environment-to-configuration mapping
+- **Better Debugging**: Easy to inspect and compare environment configurations
+
+### Negative
+
+- **Disk Usage**: Multiple copies of similar configurations consume more disk space
+- **Synchronization**: Need to regenerate configurations when templates change
+- **Directory Management**: More complex directory structure to maintain
+
+### Neutral
+
+- **Git Repository Size**: Configuration files may increase repository size
+- **Learning Curve**: Users need to understand per-environment configuration model
+
+## Implementation
+
+### Configuration Generation
+
+The `make app-config` command generates configurations for the specified environment:
+
+```bash
+# Generate application configuration for staging
+make app-config ENVIRONMENT_FILE=staging-hetzner
+
+# Result: application/config/staging-hetzner/ contains all configs
+```
+
+### Deployment Integration
+
+The `make app-deploy` command uses the environment-specific configuration:
+
+```bash
+# Deploy using pre-generated staging configuration
+make app-deploy ENVIRONMENT_FILE=staging-hetzner
+
+# Copies from: application/config/staging-hetzner/
+# To VM location: /var/lib/torrust/
+```
+
+### Environment Metadata
+
+Each configuration includes metadata for validation:
+
+```bash
+# application/config/staging-hetzner/.environment
+ENVIRONMENT_FILE=staging-hetzner
+GENERATED_AT=2025-08-06T10:30:00Z
+SOURCE_TEMPLATES_HASH=abc123def456
+```
+
+### Error Handling
+
+If environment mismatch is detected during deployment:
+
+```text
+ERROR: Configuration not found for environment 'staging-hetzner'
+
+Please generate configuration first:
+  make app-config ENVIRONMENT_FILE=staging-hetzner
+
+Or check environment file exists:
+  infrastructure/config/environments/staging-hetzner.env
+```
+
+## Alternatives Considered
+
+### Single Shared Storage
+
+Store all configurations in `application/storage/` with runtime environment validation.
+
+**Rejected because:**
+
+- No configuration tracking per environment
+- No customization support
+- Complex runtime validation required
+- No backup capability
+
+### Environment Detection in Storage
+
+Use single storage with environment metadata files for mismatch detection.
+
+**Rejected because:**
+
+- Still doesn't support per-environment customization
+- Adds complexity without solving core issues
+- No clear environment separation
+
+### Template-Only Approach
+
+Generate configurations at deployment time from templates.
+
+**Rejected because:**
+
+- No ability to customize configurations
+- No pre-deployment validation
+- Longer deployment times
+- No local testing capability
+
+## Related Decisions
+
+- [ADR-004: Configuration Approach Files vs Environment Variables](./004-configuration-approach-files-vs-environment-variables.md)
+- [ADR-007: Two-Level Environment Variable Structure](./007-two-level-environment-variable-structure.md)
+- [Configuration Architecture Standardization](../refactoring/configuration-architecture-standardization.md)
+
+## References
+
+- [Issue #28: Phase 4 Hetzner Infrastructure Implementation](../issues/28-phase-4-hetzner-infrastructure-implementation.md)
+- [Twelve-Factor App Configuration](https://12factor.net/config)
+- [Configuration Architecture Standardization Plan](../refactoring/configuration-architecture-standardization.md)
+
+## Revision History
+
+- **2025-08-06**: Initial decision document created
+- **Decision maker**: Development team based on staging deployment requirements
+- **Reviewed by**: Architecture review (pending)