# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Critical Convention

**ALL scripts must be executed in an environment that has sourced the configuration:**

```bash
# Always start by sourcing configuration
source backup.env

# Then execute any script
./backup/manage list
./backup/gen-conf.sh
sudo ./backup/install-service paperless
```

This is the core architectural pattern of this codebase. Scripts do NOT auto-source configuration files.

## Common Commands

### Initial Setup
```bash
cp backup.env.sample backup.env  # Copy configuration template
# Edit backup.env to match environment
source backup.env
./backup/gen-conf.sh          # Generate secure Restic configuration
./backup/init-restic.sh       # Initialize Restic repository
```

### Service Management
```bash
source backup.env
./backup/manage list                    # List all backup timers
./backup/manage status <service>        # Service backup status
./backup/manage run <service>           # Manual backup execution
./backup/manage logs <service>          # View backup logs
sudo ./backup/install-service <service> # Install systemd timer
```

### Backup Operations
```bash
source backup.env
./backup/list-snapshots [service]                # List available snapshots
./backup/restore <service> --test                # Test restoration
./backup/restore <service> --production          # Production restoration
```

### Configuration Testing
```bash
source backup.env
show_config                   # Display current configuration
validate_paths               # Check directory existence
```

## Architecture

### Configuration System
- **`backup.env`**: Master configuration file at project root containing all environment variables
- **`config/restic.conf`**: Generated Restic-specific configuration (created by `gen-conf.sh`)
- **Variable substitution**: systemd templates use `${VAR}` placeholders replaced during installation

### Core Components
- **`backup/manage`**: Primary interface for all backup operations and service management
- **`backup/install-service`**: Systemd timer installer that performs variable substitution in templates
- **`backup/restore`**: Advanced restoration tool with test/production modes and safety checks
- **Templates**: `service-backup@.service` and `service-backup@.timer` are systemd unit templates

### Variable Override Pattern
Configuration uses environment variable defaults with override capability:
```bash
BACKUP_USER="${BACKUP_USER:-citadel}"
PROJECT_ROOT="${PROJECT_ROOT:-/home/nicolas/dev/quantumrick}"
```

Users can customize by setting environment variables before sourcing `backup.env`.

### Systemd Integration
- Templates in `backup/` directory contain `${VARIABLE}` placeholders
- `install-service` script performs `sed` substitution to generate final systemd units
- Generated units placed in `/etc/systemd/system/` with proper permissions

### Security Model
- Restic passwords auto-generated with OpenSSL
- Configuration files have restricted permissions (600)
- Scripts validate directory existence before operations
- Restoration includes test mode for safety

## Key Files and Their Roles

### Configuration Layer
- `backup.env`: Master configuration with all variables and utility functions
- `config/restic.conf`: Generated Restic authentication and repository settings

### Operational Scripts
- `backup/manage`: Main interface (list, status, run, logs commands)
- `backup/gen-conf.sh`: Secure configuration generator
- `backup/init-restic.sh`: Repository initialization
- `backup/install-service`: Systemd timer installation with template substitution

### Templates and Restoration
- `backup/service-backup@.{service,timer}`: Systemd unit templates with variable placeholders
- `backup/restore`: Production-grade restoration with test mode and extensive validation
- `backup/list-snapshots`: Snapshot browsing utility

## Development Guidelines

When adding new scripts:
1. Add comment: `# Configuration should be sourced before running: source backup.env`
2. Use variables from `backup.env` directly (do not auto-source)
3. Follow the pattern of existing scripts for error handling and logging
4. For systemd integration, use template substitution pattern from `install-service`

When modifying configuration:
- All path variables should have environment override capability
- Maintain backward compatibility with default values
- Update both `backup.env` and this documentation if adding new variables