# apt-ostree Architecture Overview

## Project Organization

### Directory Structure
The apt-ostree project follows a well-organized structure designed for maintainability and clarity:

```
apt-ostree/
├── src/                          # Source code
│   ├── main.rs                   # CLI application entry point
│   ├── lib.rs                    # Library interface
│   ├── apt.rs                    # APT package management
│   ├── ostree.rs                 # OSTree operations
│   ├── system.rs                 # System integration
│   ├── package_manager.rs        # High-level package operations
│   ├── ostree_detection.rs       # Environment detection
│   ├── permissions.rs            # Permission handling
│   ├── error.rs                  # Error types
│   ├── bin/                      # Binary applications
│   │   ├── apt-ostreed.rs        # D-Bus daemon
│   │   └── test_runner.rs        # Test runner
│   └── daemon/                   # Daemon and service files
├── docs/                         # Documentation
│   ├── architecture/             # Architecture documentation
│   ├── development/              # Development guides
│   └── user-guide/               # User documentation
├── scripts/                      # Scripts
│   ├── testing/                  # Test scripts
│   └── daemon/                   # Daemon management scripts
├── tests/                        # Test files
├── .notes/                       # Research and planning notes
├── Cargo.toml                    # Project configuration
└── README.md                     # Project overview
```

### Key Design Decisions
- **Modular Architecture**: Each component is self-contained with clear interfaces
- **Separation of Concerns**: CLI, daemon, and library code are clearly separated
- **Documentation-First**: Comprehensive documentation for all components
- **Testing Infrastructure**: Dedicated testing framework and utilities
- **Research Integration**: Planning and research notes preserved for reference

## Introduction

apt-ostree is a Debian/Ubuntu equivalent of rpm-ostree, providing a hybrid image/package system that combines APT package management with OSTree's atomic, immutable deployment model.

## Core Design Principles

### 1. "From Scratch" Philosophy
Every change regenerates the target filesystem completely, avoiding hysteresis and ensuring reproducible results.

### 2. Atomic Operations
All changes are atomic with proper rollback support, ensuring no partial states.

### 3. Immutable Base + Layered Packages
- Base image remains unchanged
- User packages layered on top
- Clear separation of concerns

## Architecture Components

### Core Modules

#### APT Manager (`src/apt.rs`)
- Package management using libapt-pkg
- Repository management and metadata handling
- Package downloading and dependency resolution

#### OSTree Manager (`src/ostree.rs`)
- Deployment management and filesystem operations
- Repository operations and commit management
- Boot configuration management

#### System Integration (`src/system.rs`)
- Coordination between APT and OSTree
- High-level system operations
- Transaction management and rollback

#### Package Manager (`src/package_manager.rs`)
- High-level package operations
- Atomic transaction handling
- State synchronization

#### OSTree Detection (`src/ostree_detection.rs`)
- Environment detection and validation
- Multiple detection methods
- Error handling for non-OSTree environments

### Integration Modules

#### APT-OSTree Integration (`src/apt_ostree_integration.rs`)
- Bridge between APT and OSTree systems
- Package conversion and metadata handling
- Filesystem layout management

#### Filesystem Assembly (`src/filesystem_assembly.rs`)
- "From scratch" filesystem regeneration
- Hardlink optimization for content deduplication
- Proper layering order for packages

#### Dependency Resolver (`src/dependency_resolver.rs`)
- Package dependency resolution
- Topological sorting for layering
- Conflict detection and resolution

#### Script Execution (`src/script_execution.rs`)
- Sandboxed execution using bubblewrap
- Namespace isolation and security controls
- Rollback support for failed script execution

#### Bubblewrap Sandbox (`src/bubblewrap_sandbox.rs`)
- Security sandboxing for script execution
- Namespace isolation and capability management
- Environment variable handling

#### APT Database (`src/apt_database.rs`)
- APT database management in OSTree context
- State persistence and synchronization
- Package tracking and metadata management

#### OSTree Commit Manager (`src/ostree_commit_manager.rs`)
- OSTree commit management
- Atomic commit creation and deployment
- Layer tracking and metadata management

### Support Modules

#### Error Handling (`src/error.rs`)
- Unified error types
- Error conversion and propagation
- User-friendly error messages

#### Permissions (`src/permissions.rs`)
- Root privilege checks
- Permission validation
- User-friendly error messages

## Daemon Architecture

### D-Bus Service (`src/bin/apt-ostreed.rs`)
- System service providing D-Bus interface
- Privileged operations and transaction management
- Progress reporting and cancellation support

### Client Library
- D-Bus communication with daemon
- Fallback to direct system calls
- Error handling and retry logic

## Data Flow

### Package Installation Flow
1. **Command Parsing**: CLI options and package list
2. **Permission Check**: Root privilege validation
3. **Environment Detection**: OSTree environment validation
4. **Package Resolution**: APT dependency resolution
5. **Download**: Package downloading and verification
6. **Extraction**: DEB package extraction
7. **Filesystem Assembly**: "From scratch" filesystem creation
8. **Script Execution**: Sandboxed script execution
9. **Commit Creation**: Atomic OSTree commit
10. **Deployment**: Boot configuration update

### Rollback Flow
1. **State Validation**: Verify rollback target
2. **Transaction Start**: Begin rollback transaction
3. **State Restoration**: Restore previous state
4. **Boot Configuration**: Update boot configuration
5. **Transaction Commit**: Complete rollback

## Security Model

### Script Sandboxing
- All DEB scripts run in bubblewrap sandbox
- Namespace isolation and capability management
- Seccomp profiles for system call filtering

### Permission Controls
- Proper file and directory permissions
- Root privilege validation
- Environment validation

### Atomic Operations
- No partial states that could be exploited
- Instant rollback capability
- Transactional updates

## Performance Characteristics

### Optimization Features
- **Hardlink Optimization**: Content deduplication for identical files
- **Caching Strategies**: Efficient package and metadata caching
- **Parallel Processing**: Async operations for better performance
- **Content Addressing**: SHA256-based deduplication

### Expected Performance
- **Package Resolution**: Comparable to native APT
- **Memory Usage**: Reduced due to Rust's ownership system
- **Deployment Speed**: Optimized with OSTree's content addressing
- **Error Recovery**: Faster due to compile-time guarantees

## Integration Points

### System Integration
- **systemd**: Service management and boot integration
- **D-Bus**: Inter-process communication
- **OSTree**: Deployment and filesystem management
- **APT**: Package management and dependency resolution

### External Dependencies
- **bubblewrap**: Script sandboxing
- **libapt-pkg**: APT package management
- **libostree**: OSTree deployment management
- **zbus**: D-Bus communication

## Error Handling

### Error Types
- **AptOstreeError**: Unified error type for all operations
- **Permission Errors**: Root privilege and access control
- **Environment Errors**: OSTree environment validation
- **Package Errors**: APT package management errors
- **OSTree Errors**: OSTree operation errors

### Error Recovery
- **Automatic Rollback**: Failed operations automatically rollback
- **Graceful Degradation**: Fallback mechanisms for failures
- **User Feedback**: Clear error messages and recovery suggestions

## Testing Strategy

### Test Categories
- **Unit Tests**: Individual component testing
- **Integration Tests**: End-to-end workflow testing
- **OSTree Integration Tests**: Real OSTree repository testing
- **Sandbox Testing**: Bubblewrap integration validation
- **Rollback Testing**: Rollback functionality validation

### Test Infrastructure
- **Test Runner**: Comprehensive test execution framework
- **Test Utilities**: Common test helpers and utilities
- **Mock Objects**: Mock implementations for testing
- **Test Data**: Test packages and repositories 