bootc-docs/internals/bootc-internals-flowchart.md

# bootc internals - Process Flowchart

## Overview

This document provides a visual representation of the `bootc internals` process flow, showing the decision points, operations, and data structures involved in internal system operations.

## Main Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    bootc internals                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Parse Command Arguments                      │
│                                                                 │
│  • Parse internals subcommand                                  │
│  • Parse command-specific options                              │
│  • Validate arguments                                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Route to Subcommand                         │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Subcommand Type?                              │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Systemd       │  │   Filesystem    │  │   Proxy         │ │
│  │   Generator     │  │   Operations    │  │   Commands      │ │
│  │                 │  │                 │  │                 │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ Generate    ││  │  │ Fsck        ││  │  │ OstreeExt   ││ │
│  │  │ Units       ││  │  │ Cleanup     ││  │  │ Cfs         ││ │
│  │  │ Fix Fstab   ││  │  │ Relabel     ││  │  │ OstreeCont  ││ │
│  │  └─────────────┘│  │  │ Fsverity    ││  │  └─────────────┘│ │
│  └─────────────────┘  │  └─────────────┘│  └─────────────────┘ │
│                       │                 │                     │
│  ┌─────────────────┐  │  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Testing       │  │  │   System        │  │   Development   │ │
│  │   Commands      │  │  │   Operations    │  │   Tools         │ │
│  │                 │  │  │                 │  │                 │ │
│  │  ┌─────────────┐│  │  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ TestComp    ││  │  │  │ Reboot      ││  │  │ PrintSchema ││ │
│  │  │ Loopback    ││  │  │  │ InstallComp ││  │  │ DumpCliJson ││ │
│  │  │ DirDiff     ││  │  │  │ RhsmFacts   ││  │  │ DirDiff     ││ │
│  │  └─────────────┘│  │  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  │  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Internal operation completed successfully                    │
│  • Results displayed or logged                                  │
│  • System state updated if applicable                           │
└─────────────────────────────────────────────────────────────────┘
```

## Systemd Generator Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Systemd Generator Process                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check System State                          │
│                                                                 │
│  • Check if system is ostree-booted                            │
│  • Verify /etc/fstab exists                                    │
│  • Check for existing bootc stamps                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Analyze /etc/fstab                          │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Fstab Analysis                                │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   From Anaconda │    │           Not From Anaconda         │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Generate    ││    │  │         No Action Needed        ││ │
│  │  │ Fstab Editor││    │  │                                 ││ │
│  │  │ Service     ││    │  │  • Return false                 ││ │
│  │  │             ││    │  │  • Exit cleanly                 ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Generate Systemd Unit                       │
│                                                                 │
│  • Create bootc-fstab-edit.service                             │
│  • Set up service dependencies                                 │
│  • Configure service execution                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Systemd unit generated successfully                         │
│  • Service ready for execution                                 │
│  • Fstab will be updated on next boot                          │
└─────────────────────────────────────────────────────────────────┘
```

## Filesystem Consistency Check Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Fsck Process                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initialize Storage                           │
│                                                                 │
│  • Get storage instance                                         │
│  • Open OSTree repository                                       │
│  • Prepare output stream                                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Run Consistency Checks                       │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Check Type?                                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   OSTree        │  │   Composefs     │  │   Deployment    │ │
│  │   Repository    │  │   Repository    │   State           │ │
│  │                 │  │                 │                   │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ Check Repo  ││  │  │ Check Repo  ││  │  │ Check Depl  ││ │
│  │  │ Integrity   ││  │  │ Integrity   ││  │  │ States      ││ │
│  │  │ Validate    ││  │  │ Validate    ││  │  │ Validate    ││ │
│  │  │ Objects     ││  │  │ Images      ││  │  │ Configs     ││ │
│  │  └─────────────┘│  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Report Results                               │
│                                                                 │
│  • Display check results                                        │
│  • Report any errors found                                      │
│  • Provide recommendations                                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • All checks completed                                         │
│  │  • System integrity verified                                │
│  │  • Issues reported if found                                 │
│  │  • Recommendations provided                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Cleanup Operations Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Cleanup Process                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initialize Storage                           │
│                                                                 │
│  • Get storage instance                                         │
│  • Open OSTree repository                                       │
│  • Prepare cleanup operations                                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Identify Cleanup Targets                    │
│                                                                 │
│  • Find old deployments                                         │
│  • Identify unused container images                             │
│  • Locate temporary files                                       │
│  • Check for orphaned data                                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Perform Cleanup                             │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Cleanup Type?                                 │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Deployments   │  │   Images        │  │   Temporary     │ │
│  │                 │  │                 │  │   Files         │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ Remove Old  ││  │  │ Remove      ││  │  │ Remove      ││ │
│  │  │ Deployments ││  │  │ Unused      ││  │  │ Temp Files  ││ │
│  │  │ Clean Refs  ││  │  │ Images      ││  │  │ Clean Cache ││ │
│  │  └─────────────┘│  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Garbage Collection                           │
│                                                                 │
│  • Run OSTree garbage collection                               │
│  • Clean up repository objects                                 │
│  • Update repository metadata                                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Cleanup completed successfully                               │
│  • Storage space freed                                          │
│  • System optimized                                             │
└─────────────────────────────────────────────────────────────────┘
```

## Proxy Commands Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Proxy Commands Process                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Determine Proxy Type                         │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Proxy Type?                                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   OstreeExt     │  │   Cfs           │  │   OstreeCont    │ │
│  │                 │  │                 │  │                 │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ Parse Args  ││  │  │ Parse Args  ││  │  │ Parse Args  ││ │
│  │  │ Call CLI    ││  │  │ Call CLI    ││  │  │ Call CLI    ││ │
│  │  │ Return      ││  │  │ Return      ││  │  │ Return      ││ │
│  │  │ Results     ││  │  │ Results     ││  │  │ Results     ││ │
│  │  └─────────────┘│  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute Proxy Command                       │
│                                                                 │
│  • Forward arguments to target CLI                             │
│  • Execute command with proper context                         │
│  • Return results to caller                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Proxy command executed successfully                          │
│  • Results returned to caller                                  │
│  • Target CLI completed                                        │
└─────────────────────────────────────────────────────────────────┘
```

## Testing Commands Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Testing Commands Process                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Determine Test Type                          │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Test Type?                                    │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   TestComp      │  │   Loopback      │  │   DirDiff       │ │
│  │                 │  │                 │  │                 │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ Init Repo   ││  │  │ Create Dev  ││  │  │ Setup Dirs  ││ │
│  │  │ Write Test  ││  │  │ Test Ops    ││  │  │ Run Merge   ││ │
│  │  │ Verify      ││  │  │ Cleanup     ││  │  │ Verify      ││ │
│  │  └─────────────┘│  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute Test                                │
│                                                                 │
│  • Run test operations                                          │
│  • Verify expected results                                      │
│  • Clean up test data                                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Test completed successfully                                  │
│  • Results verified                                             │
│  • System state restored                                        │
└─────────────────────────────────────────────────────────────────┘
```

## Error Handling Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Error Detection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Classification                         │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   System        │  │   Permission    │  │   Resource      │ │
│  │   Errors        │  │   Errors        │  │   Errors        │ │
│  │                 │  │                 │  │                 │ │
│  │ • Not Root      │  │ • Access Denied │  │ • Out of Space  │ │
│  │ • Not Booted    │  │ • Invalid Path  │  │ • Memory Error  │ │
│  │ • Invalid State │  │ • File Not Found│  │ • Device Error  │ │
│  │                 │  │                 │  │                 │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Response                               │
│                                                                 │
│  • Display error message                                        │
│  • Provide context information                                  │
│  • Suggest remediation steps                                    │
│  • Return appropriate exit code                                 │
│  • Clean up any partial state                                   │
└─────────────────────────────────────────────────────────────────┘
```

## State Transitions

```
┌─────────────────────────────────────────────────────────────────┐
│                    System States                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initial State                                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   System Ready                                             │ │
│  │                                                             │ │
│  │ • All services running                                     │ │
│  │ • Storage available                                         │ │
│  │ • Permissions correct                                       │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Execute Command                          │ │
│  │                                                             │ │
│  │  • Parse arguments                                          │ │
│  │  • Validate inputs                                          │ │
│  │  • Check prerequisites                                      │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Processing State                         │ │
│  │                                                             │ │
│  │ • Command executing                                         │ │
│  │ • System state changing                                     │ │
│  │ • Resources being used                                      │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Final State                              │ │
│  │                                                             │ │
│  │ • Command completed                                         │ │
│  │ • System state updated                                      │ │
│  │ • Resources cleaned up                                      │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

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