# LGF Technical Manifest: System Specifications & Logic
Version: 2026.1.4
Status: Production-Ready

## 1. The "Bench" Infrastructure Model
LGF redefines the container lifecycle by treating a "Bench" as a state-managed virtual machine equivalent.

- **Isolation Logic:** Each Bench is a dedicated Docker Network (`lgf-net-[id]`). No inter-bench routing is permitted by default.
- **Deterministic Ports:** - Primary: `8080 + n` (where `n` is bench index).
  - Secondary/API: `(8080 + n) + 100`.
- **Resource Governance:** CPU/RAM limits are defined in the JSON contract. LGF enforces these at the `docker run` level to prevent noisy neighbor syndrome on single-host deployments.

## 2. Governance via JSON Contracts & Drivers
LGF is a **Refusal-Based System**. If it isn't in the contract, it doesn't exist.

- **JSON Contracts:** Define the "Intent." This includes image tags, environment variables, volume mounts, and network exposure.
- **Scripted Drivers:** Library-specific logic that translates JSON Intent into Host Execution. Drivers handle the "quirks" of complex apps (e.g., initializing MariaDB for ERPNext).
- **Authorized Sources:** LGF is seeded with an internal **GitLab instance**. 
  - All library drivers and container images are mirrored locally. 
  - The system is designed for **Air-Gapped resilience**; once seeded, it does not require external registry access to rebuild a bench.

## 3. Security & Networking (The Fortress Model)
- **Host Firewall:** LGF manages `firewalld` directly. 
  - It creates **Rich Rules** that REJECT all traffic to bench ports except from the designated Reverse Proxy IP (Internal or External).
- **Reverse Proxy:** - *Internal:* Automated Nginx/Caddy publishing at `[bench-name].[domain]`.
  - *External:* If an external RP is defined, LGF closes all host ports to everyone except that RP's specific IP.
- **Identity (Roadmap Q3/Q4 2026):** Keycloak library implementation. LGF will manage the Keycloak deployment but will remain "App-Data Unaware" to maintain architectural purity.

## 4. The "Repair" & Recovery Protocol
LGF replaces "Troubleshooting" with "Deterministic Reconciliation."

- **Repair Logic:** If a bench fails, `lgf repair` performs a checksum of the current Docker volumes, networks, and configs against the JSON Contract. It nukes and re-provisions non-compliant components.
- **Support Feedback Loop:** 1. If `repair` fails, LGF generates a `support-bundle.zip` (Manifest + State + Logs).
  2. Support Engineers update the **Library Driver** (the logic) rather than patching the bench (the instance).
  3. Client runs `lgf sync-libs` to pull the update to their internal GitLab.
  4. `lgf repair` is executed again, now with the hardened logic.

## 5. Backup & Portability
- **The Tarball:** A 100% atomic unit containing:
  - Original Repo/Image Sources.
  - All Docker Volumes (Data).
  - The LGF Manifest (Logic).
- **Reconciliation:** On restore, the LGF engine detects hardware changes (e.g., GPU availability) and port collisions on the new host, automatically re-mapping the bench to fit the new environment.

## 6. Storage Strategy (Experimental/Internal)
- **NAS Integration:** LGF supports moving the **Bench Root** and **Docker Root** to NAS (NFS/iSCSI).
- **Caching Logic:** To mitigate NAS latency, LGF is optimizing a **Local Write-Back Cache** on host NVMe for high-I/O workloads (Databases/AI Models).