# bootc switch - Process Flowchart

## Overview

This document provides a visual representation of the `bootc switch` process flow, showing the decision points, operations, and state transitions involved in switching container image references.

## Main Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                        bootc switch                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Parse Target Image                          │
│                                                                 │
│  • Parse transport type (registry, oci, oci-archive, etc.)     │
│  • Create ImageReference structure                             │
│  • Configure signature verification policy                     │
│  • Convert to OSTreeImageReference                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Operation Mode                        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              In-Place Mutation?                            │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ In-Place    ││    │  │     Normal Switch Process       ││ │
│  │  │ Switch      ││    │  │                                 ││ │
│  │  │ • Find      ││    │  │  • Get system storage           ││ │
│  │  │   deployment││    │  │  • Get OSTree repository        ││ │
│  │  │ • Update    ││    │  │  • Get current system status    ││ │
│  │  │   origin    ││    │  │  • Create new specification     ││ │
│  │  │ • Log       ││    │  │  • Check for changes            ││ │
│  │  │   operation ││    │  │  • Pull and stage image         ││ │
│  │  └─────────────┘│    │  │  • Update system status         ││ │
│  │                 │    │  │  • Handle soft reboot           ││ │
│  │  ┌─────────────┐│    │  │  • Apply changes if requested   ││ │
│  │  │   Return    ││    │  └─────────────────────────────────┘│ │
│  │  │   Success   ││    │                                     │ │
│  │  └─────────────┘│    │                                     │ │
│  └─────────────────┘    │                                     │ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Get System Status                           │
│                                                                 │
│  • Get storage interface                                        │
│  • Get OSTree repository                                        │
│  • Get current system status                                    │
│  • Get booted deployment information                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Create New Specification                    │
│                                                                 │
│  • Clone current host specification                            │
│  • Update image reference to target                            │
│  • Preserve other settings (boot order, etc.)                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check for Changes                           │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              new_spec == host.spec?                       │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Print:      ││    │  │  Log Switch Operation           ││ │
│  │  │ "Image      ││    │  │  • Log old image reference      ││ │
│  │  │ specification││    │  │  • Log new image reference     ││ │
│  │  │ is          ││    │  │  • Log transport type           ││ │
│  │  │ unchanged"  ││    │  │  • Log to systemd journal       ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  │                 │    │                       │             │ │
│  │  ┌─────────────┐│    │                       ▼             │ │
│  │  │   Return    ││    │  ┌─────────────────────────────────┐│ │
│  │  │   Success   ││    │  │     Pull and Stage Image        ││ │
│  │  └─────────────┘│    │  │  • Authenticate with registry   ││ │
│  └─────────────────┘    │  │  • Download image layers        ││ │
│                         │  │  • Convert to OSTree format     ││ │
│                         │  │  • Validate image compatibility  ││ │
│                         │  │  • Stage new deployment          ││ │
│                         │  └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Handle Image Retention                      │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              --retain specified?                           │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Keep        ││    │  │     Prune Previous Reference    ││ │
│  │  │ Previous    ││    │  │  • Get booted deployment origin ││ │
│  │  │ Image       ││    │  │  • Parse OSTree reference       ││ │
│  │  │ Reference   ││    │  │  • Update OSTree reference      ││ │
│  │  └─────────────┘│    │  │  • Free up disk space           ││ │
│  └─────────────────┘    │  └─────────────────────────────────┘│ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Stage New Deployment                        │
│                                                                 │
│  • Create new deployment in OSTree                             │
│  • Configure bootloader for new deployment                     │
│  • Update system status                                        │
│  • Preserve /etc and /var state                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Update System Status                        │
│                                                                 │
│  • Update system modification time                             │
│  • Refresh system status                                        │
│  • Update deployment information                                │
│  • Log configuration changes                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Handle Soft Reboot                          │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              --soft-reboot specified?                      │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Configure   ││    │  │     Skip Soft Reboot            ││ │
│  │  │ Soft Reboot ││    │  │                                 ││ │
│  │  │ • Check     ││    │  │  • Continue to apply check     ││ │
│  │  │   availability││    │  │                                 ││ │
│  │  │ • Configure ││    │  │                                 ││ │
│  │  │   if needed ││    │  │                                 ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Apply Changes                               │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              --apply specified?                            │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Reboot      ││    │  │     Changes Staged              ││ │
│  │  │ System      ││    │  │                                 ││ │
│  │  │ • Execute   ││    │  │  • Changes ready for next boot  ││ │
│  │  │   reboot    ││    │  │  • No immediate action          ││ │
│  │  │ • Apply     ││    │  │  • User can reboot manually     ││ │
│  │  │   changes   ││    │  │                                 ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Image switch completed successfully                          │
│  • New image staged for next boot                               │
│  • System ready for reboot (if --apply)                        │
└─────────────────────────────────────────────────────────────────┘
```

## In-Place Switch Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    In-Place Switch                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Log Operation                               │
│                                                                 │
│  • Log to systemd journal with unique message ID               │
│  • Include image reference and transport type                  │
│  • Mark as in-place switch operation                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Find Deployment Directory                   │
│                                                                 │
│  • Search for deployment directory in /sysroot/ostree/deploy   │
│  • Locate current booted deployment                            │
│  • Validate deployment structure                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Update Origin File                          │
│                                                                 │
│  • Read current origin file                                    │
│  • Parse origin configuration                                  │
│  • Update image reference                                      │
│  • Write updated origin file                                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Extract Deployment ID                       │
│                                                                 │
│  • Parse deployment directory name                             │
│  • Extract deployment ID                                       │
│  • Return deployment ID for logging                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • In-place switch completed                                   │
│  │  • Deployment ID updated                                   │
│  │  • Image reference changed                                 │
│  │  • System ready for next boot                              │
└─────────────────────────────────────────────────────────────────┘
```

## Error Handling Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Error Detection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Classification                         │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Image         │  │   System        │  │   Network       │ │
│  │   Errors        │  │   Errors        │  │   Errors        │ │
│  │                 │  │                 │  │                 │ │
│  │ • Invalid       │  │ • Not bootc     │  │ • Registry      │ │
│  │   transport     │  │   compatible    │  │   connectivity  │ │
│  │ • Image not     │  │ • No deployment │  │ • Authentication│ │
│  │   found         │  │   found         │  │   failed        │ │
│  │ • Signature     │  │ • Invalid       │  │ • Image pull    │ │
│  │   verification  │  │   state         │  │   failed        │ │
│  │   failed        │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Response                               │
│                                                                 │
│  • Display error message                                        │
│  • Provide context information                                  │
│  • Suggest remediation steps                                    │
│  • Return appropriate exit code                                 │
│  • Clean up any partial state                                   │
└─────────────────────────────────────────────────────────────────┘
```

## State Transitions

```
┌─────────────────────────────────────────────────────────────────┐
│                    System States                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Current State                                │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   Image: v1.0   │    │            Image: v1.0              │ │
│  │   Boot: normal  │    │            Boot: normal             │ │
│  │   Staged: none  │    │            Staged: v2.0             │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
│           │                           │                         │
│           ▼                           ▼                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Switch 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                 │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Transport Type Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Transport Selection                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Parse Transport Type                         │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              --transport specified?                        │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Use         ││    │  │     Use Default (registry)      ││ │
│  │  │ Specified   ││    │  │                                 ││ │
│  │  │ Transport   ││    │  │  • Set transport to 'registry'  ││ │
│  │  │ • registry  ││    │  │  • Use registry authentication  ││ │
│  │  │ • oci       ││    │  │  • Use HTTPS protocol           ││ │
│  │  │ • oci-      ││    │  │                                 ││ │
│  │  │   archive   ││    │  │                                 ││ │
│  │  │ • containers││    │  │                                 ││ │
│  │  │   -storage  ││    │  │                                 ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Create Image Reference                       │
│                                                                 │
│  • Create ImageReference structure                             │
│  • Set transport type                                          │
│  │  • Set image name/tag                                       │
│  │  • Configure signature verification                         │
│  │  • Convert to OSTreeImageReference                          │
└─────────────────────────────────────────────────────────────────┘
```

This flowchart provides a comprehensive visual representation of the bootc switch process, showing all decision points, operations, and state transitions involved in switching container image references.