# Architecture

## Components

1. **Debian host** - Git polling, Docker engine, package assembly and optional publication.
2. **Docker builder** - Rust 1.88, Clang/LLD and a verified FreeBSD 15.1 sysroot extracted from official `base.txz`.
3. **OPNsense package** - `os-rustproxy-*.pkg`, installed directly with `pkg add -f`.

No FreeBSD VM is used.

## Why the sysroot is enough for the binary build

Rust provides `x86_64-unknown-freebsd`. Clang receives `--target=x86_64-unknown-freebsd15.1` and `--sysroot=/opt/freebsd-sysroot`, so Rust and C/assembly dependencies such as `ring` link against FreeBSD headers and libraries instead of Debian ones.

The container is still Linux. It cannot execute the generated FreeBSD binary, so the pipeline performs Linux tests before cross-compilation and ELF inspection after cross-compilation. Runtime validation must happen on an OPNsense/FreeBSD test firewall.

## Package construction

FreeBSD pkg archives are compressed tar archives with metadata files beginning with `+` before package data. The Linux packager creates:

```text
+COMPACT_MANIFEST
+MANIFEST
usr/local/...
```

and compresses it with zstd to `.pkg`.

## Source isolation

```text
/opt/opn-rustproxy/packaging          packaging repository
/opt/opn-rustproxy/source/RustProxy  dynamically fetched application
/opt/opn-rustproxy/cache             Docker/Cargo cache
```

The exact RustProxy SHA and package version are written to `dist/BUILD-INFO.txt`.