System Architecture

Monorepo structure, component boundaries, and tech decisions.

Monorepo Layout


floppy.wtf/
├── nixos/                          # NixOS system definitions
│   ├── flake.nix                   # Build manifest (pinned inputs)
│   ├── flake.lock                  # Dependency lock
│   ├── hosts/                      # Per-machine configurations
│   │   └── dell/
│   │       ├── configuration.nix   # Host-specific system config
│   │       └── hardware-configuration.nix
│   ├── modules/                    # Reusable NixOS modules
│   │   ├── base.nix                # Core system (networking, users, SSH)
│   │   ├── filesystem.nix          # Btrfs layout + snapshots
│   │   ├── desktop.nix             # DE/WM selection
│   │   ├── power.nix               # TLP + power tuning
│   │   └── networking.nix          # WireGuard, Syncthing, Avahi
│   ├── theme/                      # Visual identity modules
│   │   ├── colors.nix              # Central color palette
│   │   ├── fonts.nix               # Font packages + fontconfig
│   │   ├── applenix.nix            # macOS-rivaling theme
│   │   └── matrix.nix              # Matrix mode theme
│   └── roles/                      # Role-based compositions
│       ├── dev.nix                 # Developer workstation
│       ├── node.nix                # Infrastructure node
│       ├── minimal.nix             # Bare minimum
│       └── lab.nix                 # Experimentation
│
├── cli/                            # floppy CLI tool
│   ├── src/
│   │   ├── main.ts                 # Entry point
│   │   ├── commands/               # CLI command handlers
│   │   ├── registry/               # Device registry storage
│   │   └── lib/                    # Shared utilities
│   ├── package.json
│   └── tsconfig.json
│
├── web/                            # Website + documentation
│   ├── app/                        # Next.js app router
│   ├── content/                    # MDX documentation
│   └── package.json
│
├── assets/                         # Shared assets
├── registry/                       # Device registry data (gitignored)
├── specs/                          # Specifications
└── .gitignore

Component Boundaries

NixOS Configurations (`nixos/`)

Responsibility: Define deterministic system states.

Pure Nix language
No imperative scripts
Flake-based with pinned inputs
Evaluated locally or on target machine
Produces bootable system closures

Depends on: Nothing (self-contained Nix evaluation)

CLI Tool (`cli/`)

Responsibility: Operational workflows — registration, provisioning, fleet.

TypeScript + Bun runtime
Commander.js for CLI framework
SQLite for local device registry
SHA256 for content addressing
Shells out to Nix commands for provisioning

Depends on: nixos/ configs (references flake for provisioning)

Device Registry (`registry/`)

Responsibility: Persistent device identity + evidence storage.

Gitignored (contains binary artifacts + device-specific data)
JSON records per device
Content-addressed evidence store
Queryable via CLI

Depends on: CLI tool writes here

Tech Stack

Concern	Choice	Rationale
OS Definition	NixOS + Flakes	Deterministic, reproducible, hash-addressed
Package Pinning	flake.lock	Exact dependency versions
Filesystem	Btrfs	CoW, checksums, snapshots, low overhead
Desktop	XFCE (default)	Lightweight, GPU-safe for old hardware
Compositor	Picom	Subtle effects without GPU strain
CLI Runtime	Bun + TypeScript	Fast, modern, good DX
CLI Framework	Commander.js	Standard, well-documented
Local DB	SQLite	Zero-config, embedded, reliable
Hashing	SHA256	Industry standard, Nix-compatible
File Transfer	LocalSend	AirDrop-like, cross-platform
Sync	Syncthing	Continuous, decentralized, integrity-aware
VPN Mesh	WireGuard	Modern, fast, simple
Discovery	Avahi (mDNS)	Standard LAN discovery

Data Flow

Device Registration Flow


Physical Device
    │
    ▼
floppy device register --model "Dell ..." --serial "..."
    │
    ├── Creates device record (JSON)
    ├── Assigns device ID (FLOPPY-{TYPE}-{SEQ})
    └── Stores in registry/devices/{id}.json
    │
    ▼
floppy device attach-photo {id} ./photo.jpg
    │
    ├── Strips EXIF metadata
    ├── Computes SHA256
    ├── Stores in registry/evidence/{hash}.jpg
    └── Updates device record with evidence reference

Provisioning Flow


Registered Device
    │
    ▼
floppy provision {device-id} --role dev
    │
    ├── Resolves role → NixOS host config
    ├── Generates hardware-specific overrides
    ├── Builds NixOS installer USB image
    └── Validates build closure
    │
    ▼
Physical Flash (USB → Device)
    │
    ▼
Boot → nixos-install --flake .#{host}
    │
    ▼
Post-install verification
    │
    ├── System hash verification
    ├── Service health checks
    └── Device status → "provisioned"

Security Model

Concern	Approach
Evidence integrity	SHA256 content-addressing
Config integrity	Nix store hash verification
Transport security	WireGuard encrypted mesh
File transfer	TLS via LocalSend
Registry access	Local-only (no remote API in early phases)
Secrets	Never committed; managed via agenix or sops-nix