bootc-docs/state/bootc-state-flowchart.md

# bootc state - Process Flowchart

## Overview

This document provides a visual representation of the `bootc state` process flow, showing the decision points, operations, and system state changes involved in state modification operations.

## Main Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    bootc state                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Parse Command Arguments                      │
│                                                                 │
│  • Parse state subcommand                                      │
│  • Validate arguments                                          │
│  • Check permissions                                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Route to Subcommand                         │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Subcommand Type?                              │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                wipe-ostree                                 │ │
│  │                                                             │ │
│  │  • Remove all OSTree deployments                           │ │
│  │  • Reset system state                                      │ │
│  │  • Prepare for fresh installation                          │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • State modification completed successfully                    │
│  • System state updated                                        │
│  • Deployments removed                                         │
└─────────────────────────────────────────────────────────────────┘
```

## wipe-ostree Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    wipe-ostree Process                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Prerequisites                         │
│                                                                 │
│  • Verify root privileges                                      │
│  • Check OSTree availability                                  │
│  • Validate system state                                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initialize OSTree                           │
│                                                                 │
│  • Create OSTree sysroot instance                              │
│  • Load sysroot configuration                                  │
│  • Prepare for operations                                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute Wipe Operation                      │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Wipe Operation                                │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                Spawn Blocking Task                         │ │
│  │                                                             │ │
│  │  • Move to blocking thread                                 │ │
│  │  • Execute OSTree operations                               │ │
│  │  • Handle cancellable operations                           │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Write Empty Deployments                       │ │
│  │                                                             │ │
│  │  • Call sysroot.write_deployments(&[])                     │ │
│  │  • Remove all deployment entries                           │ │
│  │  • Update system state                                     │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Verify Operation                            │
│                                                                 │
│  • Check operation success                                     │
│  • Verify deployments removed                                  │
│  • Update system state                                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • All OSTree deployments removed                              │
│  • System state reset                                          │
│  • Ready for fresh installation                                │
└─────────────────────────────────────────────────────────────────┘
```

## System State Transitions

```
┌─────────────────────────────────────────────────────────────────┐
│                    System States                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initial State                                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   System with OSTree Deployments                           │ │
│  │                                                             │ │
│  │ • Active deployments present                               │ │
│  │ • Boot entries configured                                  │ │
│  │ • System state managed                                     │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Execute wipe-ostree                     │ │
│  │                                                             │ │
│  │  • Remove all deployments                                  │ │
│  │  • Clear boot entries                                      │ │
│  │  • Reset system state                                      │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Final State                              │ │
│  │                                                             │ │
│  │ • No OSTree deployments                                    │ │
│  │ • No boot entries                                           │ │
│  │ • Clean system state                                        │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Error Handling Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Error Detection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Classification                         │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Permission    │  │   OSTree        │  │   System        │ │
│  │   Errors        │  │   Errors        │  │   Errors        │ │
│  │                 │  │                 │  │                 │ │
│  │ • Not Root      │  │ • Not Available │  │ • Not OSTree    │ │
│  │ • Access Denied │  │ • Load Failed   │  │ • Corrupted     │ │
│  │ • Invalid User  │  │ • Write Failed  │  │ • Unavailable   │ │
│  │                 │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Response                               │
│                                                                 │
│  • Display error message                                        │
│  • Provide context information                                  │
│  • Suggest remediation steps                                    │
│  • Return appropriate exit code                                 │
│  • Log error details                                            │
└─────────────────────────────────────────────────────────────────┘
```

## OSTree Operations Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    OSTree Operations                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initialize Sysroot                          │
│                                                                 │
│  • Create OSTree::Sysroot::new_default()                       │
│  • Load sysroot configuration                                  │
│  • Prepare for operations                                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute Operations                           │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Operation Type?                               │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                Write Deployments                           │ │
│  │                                                             │ │
│  │  • Call write_deployments(&[])                             │ │
│  │  • Remove all deployment entries                           │ │
│  │  • Update system metadata                                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Verify Results                              │
│                                                                 │
│  • Check operation success                                     │
│  • Verify deployments removed                                  │
│  • Update system state                                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • OSTree operations completed                                 │
│  • System state updated                                        │
│  • Deployments removed                                         │
└─────────────────────────────────────────────────────────────────┘
```

## Asynchronous Execution Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Asynchronous Execution                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Spawn Blocking Task                         │
│                                                                 │
│  • Create tokio::task::spawn_blocking                          │
│  • Move sysroot to blocking thread                             │
│  • Prepare for OSTree operations                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute in Blocking Context                 │
│                                                                 │
│  • Run OSTree operations                                       │
│  │  • sysroot.write_deployments(&[])                          │
│  │  • Handle cancellable operations                           │
│  │  • Update system state                                     │
│  • Return results to async context                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Await Results                               │
│                                                                 │
│  • Wait for blocking task completion                           │
│  • Handle any errors                                           │
│  • Return results to caller                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Asynchronous operation completed                            │
│  • Results returned to caller                                  │
│  • System state updated                                        │
└─────────────────────────────────────────────────────────────────┘
```

## System Impact Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    System Impact Analysis                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Before Wipe                                 │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   System State                                             │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Deployments   │  │   Boot Entries  │  │   System State  │ │
│  │                 │  │                 │  │                 │ │
│  │ • Active        │  │ • Grub entries  │  │ • Managed       │ │
│  │ • Staged        │  │ • Systemd       │  │ • Configured    │ │
│  │ • Rollback      │  │ • Bootloader    │  │ • Tracked       │ │
│  │                 │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    During Wipe                                 │
│                                                                 │
│  • Remove all deployments                                      │
│  • Clear boot entries                                          │
│  • Reset system state                                          │
│  • Update metadata                                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    After Wipe                                  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   System State                                             │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Deployments   │  │   Boot Entries  │  │   System State  │ │
│  │                 │  │                 │  │                 │ │
│  │ • None          │  │ • None          │  │ • Clean         │ │
│  │ • Removed       │  │ • Cleared       │  │ • Reset         │ │
│  │ • Wiped         │  │ • Removed       │  │ • Fresh         │ │
│  │                 │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Recovery Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Recovery Process                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Assess System State                         │
│                                                                 │
│  • Check if system is bootable                                 │
│  • Verify data integrity                                       │
│  • Determine recovery needs                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Recovery Options                             │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Recovery Type?                                │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Fresh Install │  │   Restore       │  │   Manual        │ │
│  │                 │  │   Backup        │  │   Recovery      │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ Install     ││  │  │ Restore     ││  │  │ Fix         ││ │
│  │  │ New System  ││  │  │ From Backup ││  │  │ Manually    ││ │
│  │  │ Configure   ││  │  │ Restore     ││  │  │ Rebuild     ││ │
│  │  │ Deploy      ││  │  │ Data        ││  │  │ System      ││ │
│  │  └─────────────┘│  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Verify Recovery                             │
│                                                                 │
│  • Test system bootability                                     │
│  • Verify data integrity                                       │
│  • Check system functionality                                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • System recovered successfully                               │
│  • Data integrity verified                                     │
│  • System functionality restored                               │
└─────────────────────────────────────────────────────────────────┘
```

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