# bootc edit - Process Flowchart

## Overview

This document provides a visual representation of the `bootc edit` process flow, showing the decision points, operations, and state transitions involved in editing bootc host specifications.

## Main Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                        bootc edit                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initialize System                            │
│  • Get storage interface                                        │
│  • Get OSTree repository                                        │
│  • Get current system status                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Load Configuration                           │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   Filename      │    │        Interactive Mode             │ │
│  │   Provided?     │    │                                     │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
│           │                           │                         │
│           ▼                           ▼                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │ Load from File  │    │  • Create temporary file            │ │
│  │ • Open file     │    │  • Write current config to temp     │ │
│  │ • Parse YAML    │    │  • Spawn editor with temp file      │ │
│  │ • Validate      │    │  • Wait for editor completion       │ │
│  └─────────────────┘    │  • Read modified config             │ │
│           │              └─────────────────────────────────────┘ │
│           │                           │                         │
│           └───────────┬───────────────┘                         │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Parse and Validate YAML                       │ │
│  │  • Deserialize to Host structure                           │ │
│  │  • Validate schema                                         │ │
│  │  • Check required fields                                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Compare Configurations                       │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              new_host.spec == host.spec?                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Print:      ││    │  │  Validate Transition            ││ │
│  │  │ "Edit       ││    │  │  • Check image changes          ││ │
│  │  │ cancelled,  ││    │  │  • Validate boot order          ││ │
│  │  │ no changes  ││    │  │  • Verify system state          ││ │
│  │  │ made"       ││    │  └─────────────────────────────────┘│ │
│  │  └─────────────┘│    │                       │             │ │
│  │                 │    │                       ▼             │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │   Return    ││    │  │     Create RequiredHostSpec     ││ │
│  │  │   Success   ││    │  │  • Extract image reference      ││ │
│  │  └─────────────┘│    │  │  • Validate required fields     ││ │
│  └─────────────────┘    │  └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Determine Change Type                        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              boot_order changed?                           │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Execute     ││    │  │     Image Change Process        ││ │
│  │  │ Rollback    ││    │  │                                 ││ │
│  │  │ • Call      ││    │  │  ┌─────────────────────────────┐││ │
│  │  │   rollback  ││    │  │  │     Pull New Image          │││ │
│  │  │ • Update    ││    │  │  │  • Authenticate with        │││ │
│  │  │   boot      ││    │  │  │    registry                 │││ │
│  │  │   order     ││    │  │  │  • Download image layers    │││ │
│  │  └─────────────┘│    │  │  │  • Convert to OSTree        │││ │
│  │                 │    │  │  │  • Validate image           │││ │
│  │  ┌─────────────┐│    │  │  └─────────────────────────────┘││ │
│  │  │   Return    ││    │  │                       │         ││ │
│  │  │   Success   ││    │  │                       ▼         ││ │
│  │  └─────────────┘│    │  │  ┌─────────────────────────────┐││ │
│  └─────────────────┘    │  │  │     Stage New Deployment    │││ │
│                         │  │  │  • Create new deployment    │││ │
│                         │  │  │  • Configure bootloader     │││ │
│                         │  │  │  • Update system status     │││ │
│                         │  │  │  • Preserve /etc and /var   │││ │
│                         │  │  └─────────────────────────────┘││ │
│                         │  └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Update System Status                         │
│                                                                 │
│  • Update system modification time                              │
│  • Refresh system status                                        │
│  • Update deployment information                                │
│  • Log configuration changes                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Configuration applied successfully                           │
│  • System ready for next boot                                   │
│  • Changes staged for application                               │
└─────────────────────────────────────────────────────────────────┘
```

## Editor Integration Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Editor Selection                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Environment                            │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              $EDITOR set?                                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Use $EDITOR ││    │  │  Check Backup Editors           ││ │
│  │  │ • Split     ││    │  │  • nano                         ││ │
│  │  │   command   ││    │  │  • vim                          ││ │
│  │  │ • Extract   ││    │  │  • vi                           ││ │
│  │  │   program   ││    │  │  • Check /usr/bin/              ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    │                       │             │ │
│           │              │                       ▼             │ │
│           │              │  ┌─────────────────────────────────┐│ │
│           │              │  │      Editor Found?             ││ │
│           │              │  └─────────────────────────────────┘│ │
│           │              │                       │             │ │
│           │              │                       ▼             │ │
│           │              │  ┌─────────────────┐    ┌─────────┐│ │
│           │              │  │      Yes        │    │   No    ││ │
│           │              │  │                 │    │         ││ │
│           │              │  │  ┌─────────────┐│    │  ┌─────┐││ │
│           │              │  │  │ Use Backup  ││    │  │Error│││ │
│           │              │  │  │ Editor      ││    │  │     │││ │
│           │              │  │  └─────────────┘│    │  └─────┘││ │
│           │              │  └─────────────────┘    └─────────┘│ │
│           │              └─────────────────────────────────────┘ │
│           │                       │                             │
│           └───────────┬───────────┘                             │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Launch Editor                                  │ │
│  │  • Create command with editor program                      │ │
│  │  • Add editor arguments                                    │ │
│  │  • Add temporary file path                                 │ │
│  │  • Execute with lifecycle binding                          │ │
│  │  • Wait for completion                                     │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Error Handling Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Error Detection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Classification                         │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Editor        │  │ Configuration   │  │   System        │ │
│  │   Errors        │  │   Errors        │  │   Errors        │ │
│  │                 │  │                 │  │                 │ │
│  │ • $EDITOR       │  │ • Invalid YAML  │  │ • Not bootc     │ │
│  │   unset         │  │ • Schema        │  │   compatible    │ │
│  │ • Editor not    │  │   validation    │  │ • Image not     │ │
│  │   found         │  │ • Missing       │  │   found         │ │
│  │ • Editor        │  │   fields        │  │ • Registry      │ │
│  │   execution     │  │ • Invalid       │  │   error         │ │
│  │   failed        │  │   values        │  │ • OSTree error  │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Response                               │
│                                                                 │
│  • Display error message                                        │
│  • Provide context information                                  │
│  • Suggest remediation steps                                    │
│  • Return appropriate exit code                                 │
│  • Clean up temporary files                                     │
└─────────────────────────────────────────────────────────────────┘
```

## State Transitions

```
┌─────────────────────────────────────────────────────────────────┐
│                    System States                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Current State                                │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   Normal        │    │            Rollback                 │ │
│  │   Boot          │    │            Queued                   │ │
│  │                 │    │                                     │ │
│  │ • Image: v1.0   │    │ • Image: v1.0                      │ │
│  │ • Boot: normal  │    │ • Boot: rollback                   │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
│           │                           │                         │
│           ▼                           ▼                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Edit Operation                           │ │
│  │                                                             │ │
│  │  ┌─────────────────┐    ┌─────────────────────────────────┐ │ │
│  │  │   Image         │    │         Boot Order              │ │ │
│  │  │   Change        │    │         Change                  │ │ │
│  │  │                 │    │                                 │ │ │
│  │  │ • Pull new      │    │ • Execute rollback              │ │ │
│  │  │   image         │    │ • Update boot order             │ │ │
│  │  │ • Stage         │    │ • Preserve state                │ │ │
│  │  │   deployment    │    │                                 │ │ │
│  │  └─────────────────┘    └─────────────────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                           │                         │
│           ▼                           ▼                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   New State     │    │            New State                │ │
│  │                 │    │                                     │ │
│  │ • Image: v2.0   │    │ • Image: v1.0                      │ │
│  │ • Boot: normal  │    │ • Boot: normal                     │ │
│  │ • Staged: v2.0  │    │ • Rollback: queued                 │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Configuration Validation Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Configuration Input                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    YAML Parsing                                │
│                                                                 │
│  • Parse YAML syntax                                            │
│  • Deserialize to Host structure                                │
│  • Validate required fields                                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Schema Validation                            │
│                                                                 │
│  • Validate Host structure                                      │
│  • Check HostSpec fields                                        │
│  • Verify ImageReference format                                 │
│  • Validate BootOrder values                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Transition Validation                        │
│                                                                 │
│  • Compare with current configuration                           │
│  • Check for valid state transitions                            │
│  • Verify image accessibility                                   │
│  • Validate boot order changes                                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Validation Result                            │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │     Valid       │    │            Invalid                  │ │
│  │                 │    │                                     │ │
│  │ • Proceed with  │    │ • Display error message             │ │
│  │   changes       │    │ • Provide context                   │ │
│  │ • Apply         │    │ • Suggest fixes                     │ │
│  │   configuration │    │ • Return error                      │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

This flowchart provides a comprehensive visual representation of the bootc edit process, showing all decision points, operations, and state transitions involved in editing bootc host specifications.