FFOS-USER - Component and User Data Repository

Overall State

Component	Build Status	Lint Status	Code Coverage
feral-controld
feral-setupd
feral-sys-monitord
feral-watchdog

---

Architecture Overview

FFOS-USER provides components and user data to the FFOS build system. Build orchestration lives in the FFOS repo, while this repo focuses on component source and user data. CI workflows here run tests and lint only.

┌───────────────────────────────────────────────────────────┐
│                    ffos-user Repository                   │
│                                                           │
│  ┌──────────────────┐    ┌─────────────────┐              │
│  │   components/    │    │     users/      │              │
│  │                  │    │                 │              │
│  │ ┌──────────────┐ │    │ ┌─────────────┐ │              │
│  │ │feral-controld│ │    │ │  feralfile  │ │              │
│  │ │feral-setupd  │ │    │ │  soaktest   │ │              │
│  │ │feral-sys-    │ │    │ │             │ │              │
│  │ │  monitord    │ │    │ │ Configs     │ │              │
│  │ │feral-app-    │ │    │ │ Scripts     │ │              │
│  │ │  monitord    │ │    │ │ Data        │ │              │
│  │ │feral-watchdog│ │    │ └─────────────┘ │              │
│  │ │launcher-ui   │ │    │                 │              │
│  │ │player-wrapper│ │    │                 │              │
│  │ │     -ui      │ │    │                 │              │
│  │ └──────────────┘ │    │                 │              │
│  └──────────────────┘    └─────────────────┘              │
└───────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   ffos Build    │
                    │   Repository    │
                    └─────────────────┘

Repository Structure

ffos-user/
├── components/                    # Service components
│   ├── feral-controld/           # Connection daemon
│   │   ├── main.go
│   │   ├── go.mod
│   │   └── ...
│   ├── feral-setupd/             # Setup daemon (Rust)
│   │   ├── src/
│   │   ├── Cargo.toml
│   │   └── ...
│   ├── feral-sys-monitord/       # System monitoring
│   ├── feral-watchdog/           # System watchdog
│   ├── launcher-ui/              # Launcher UI components
│   └── player-wrapper-ui/        # Player wrapper UI
└── users/                        # User data and configurations
    ├── feralfile/                # feralfile user data
    │   ├── scripts/              # User scripts
    │   │   ├── start-kiosk.sh
    │   │   ├── feral-updater.sh
    │   │   └── ...
    │   ├── .config/              # User configurations
    │   │   │   ├── systemd/user/
    │   │   │   │   ├── feral-sys-monitord.service
    │   │   │   │   ├── feral-setupd.service
    │   │   │   │   ├── chromium-kiosk.service
    │   │   │   │   └── ...
    │   │   ├── controld.json
    │   │   └── watchdog.json
    │   ├── .bash_profile         # Shell configuration
    │   └── ...
    └── soaktest/                 # soaktest user data
        ├── scripts/              # Test scripts
        ├── logs/                 # Test logs
        ├── files/                # Test files
        └── ...

Component Architecture

Service Components Layer

1. Connection Layer (feral-controld)

• Purpose: Manages device connectivity and communication
• Language: Go
• Dependencies: WebSocket, HTTP, CDP
• Build Output: feral-controld-{version}-x86_64.pkg.tar.zst

2. Setup Layer (feral-setupd)

• Purpose: Handles device initialization and configuration
• Language: Rust
• Dependencies: Bluetooth, WiFi, System APIs
• Build Output: feral-setupd-{version}-x86_64.pkg.tar.zst

3. Monitoring Layer

• feral-sys-monitord: System resource monitoring
• feral-watchdog: System watchdog and recovery

4. UI Layer

• launcher-ui: Main launcher interface
• player-wrapper-ui: Media player wrapper interface

User Data Layer

feralfile User

users/feralfile/
├── scripts/                      # System scripts
│   ├── start-kiosk.sh           # Kiosk mode startup
│   ├── feral-updater.sh         # System update
│   ├── log-rotation.sh          # Log management
│   └── ...
├── .config/                      # Application configs
│   ├── systemd/user/             # Systemd services
│   │   ├── feral-sys-monitord.service
│   │   ├── feral-setupd.service
│   │   ├── chromium-kiosk.service
│   │   └── ...
│   ├── controld.json            # Connection daemon config
│   └── watchdog.json            # Watchdog config
└── .bash_profile                # Shell environment

soaktest User

users/soaktest/
├── scripts/                      # Test automation
│   └── soak-test.sh            # Soak testing
├── logs/                        # Test output
├── files/                       # Test assets
└── .bash_profile               # Test environment

Data Flow Architecture

Component Development Flow

Developer → ffos-user/components/ → ffos build process → R2 Storage

User Data Integration Flow

ffos-user/users/feralfile/ → ISO /home/feralfile/
ffos-user/users/soaktest/ → ISO /home/soaktest/ (conditional)

Configuration Propagation

ffos-user/users/feralfile/.config/ → ISO /home/feralfile/.config/
ffos-user/users/feralfile/scripts/ → ISO /home/feralfile/scripts/

Integration with FFOS

Version Control

• FFOS references specific ffos-user commits/tags
• Enables reproducible builds
• Supports multiple component versions

Build Integration

• FFOS checkout ffos-user at specified reference
• Builds components from source
• Merges user data into ISO

Data Synchronization

ffos-user/main → ffos build → R2/{main}/
ffos-user/develop → ffos build → R2/{develop}/

Repository Management

Commit Guidelines

• Use conventional commit format
• Prefix with component name for clarity
• Example: feral-controld: add heartbeat functionality

Setup Instructions

No GitHub Actions Required

This repository is purely for source code and data. All build logic is handled by the FFOS repository.

Sync components to a device (dev)

Use the component sync helpers to push local changes to an FF1 over SSH (key-based).

# Default host + key
make -C components sync-feral-controld

# Override host or key
REMOTE_HOST=ff1-03vdu3x1.local REMOTE_KEY=~/.ssh/id_ed25519 make -C components sync-feral-controld