Orbit Multi-App Parameterized Desktop Container & Native IPC API Proxy Architecture

1. Unified Container Architecture & Packaging Strategy

Enterprise operators utilize specialized point-of-sale and back-office workstations tailored to their specific vertical:

• Orbit Commerce POS: Retail checkouts requiring barcode scale integration and 1280x800 display geometry.
• Orbit Dine POS: Restaurant dining rooms and kitchen prep stations requiring dual-monitor customer-facing displays.
• Orbit Health Station: Diagnostic laboratories and clinics requiring 1440x900 high-density pathology broadsheets.
• Orbit Edu Counter: School bursar desks and campus gates requiring 1440x900 fee challan registers and continuous RFID readers.

Rather than maintaining four separate native runtime repositories, the desktop engine in apps/desktop/build-desktop.mjs parameterizes a single compiled native container across all product profiles:

+-------------------------------------------------------------------------+
|                  ORBIT PARAMETERIZED DESKTOP BUILDER                    |
|                        (build-desktop.mjs)                              |
+-------------------------------------------------------------------------+
                                    |
      +-----------------------------+-----------------------------+
      |                             |                             |
      v                             v                             v
[--app=commerce]              [--app=dine]                  [--app=health]
Bundle: com.frontorbit.orbit.commerce   Bundle: com.frontorbit.orbit.dine   Bundle: com.frontorbit.orbit.health
Window: 1280 x 800            Window: 1280 x 800            Window: 1440 x 900

2. Interactive Desktop Container Interface

The administrative container console provides real-time visibility into active compilation targets, native bridge endpoints, and window parameters:

3. Parameterized Multi-App Compilation Profiles

The build automation script apps/desktop/build-desktop.mjs defines dedicated configuration profiles for each vertical:

{
  "commerce": {
    "bundleId": "com.frontorbit.orbit.commerce",
    "productName": "Orbit Commerce POS",
    "title": "Orbit Commerce — Retail POS & Back-Office",
    "frontendDist": "../../commerce/out",
    "width": 1280,
    "height": 800
  },
  "dine": {
    "bundleId": "com.frontorbit.orbit.dine",
    "productName": "Orbit Dine POS",
    "title": "Orbit Dine — Restaurant POS & Kitchen Display",
    "frontendDist": "../../dine/out",
    "width": 1280,
    "height": 800
  },
  "health": {
    "bundleId": "com.frontorbit.orbit.health",
    "productName": "Orbit Health Station",
    "title": "Orbit Health — Diagnostic Lab & Clinic Counter",
    "frontendDist": "../../health/out",
    "width": 1440,
    "height": 900
  },
  "edu": {
    "bundleId": "com.frontorbit.orbit.edu",
    "productName": "Orbit Edu Counter",
    "title": "Orbit Edu — Fee Counter & Gate Attendance Workstation",
    "frontendDist": "../../edu/out",
    "width": 1440,
    "height": 900
  }
}

3.1 Dynamic Manifest Injection

During compilation, build-desktop.mjs:

1. Reads the target parameter (such as node build-desktop.mjs --app=health).
2. Generates a tailored native manifest specifying the unique bundleId, productName, window dimensions, and isolated web distribution assets.
3. Compiles the native systems binary with full link-time optimization (LTO) and anti-tamper security symbols.

This enables independent deployment packages (.deb, .msi, .dmg) for each industry vertical while maintaining a single core systems crate.

4. Native IPC API Network Bridge

Webview user interfaces running inside desktop wrappers typically communicate with remote servers using standard browser HTTP fetch requests. However, this introduces several operational challenges:

• CORS Preflight Latency: Browser security engines dispatch preliminary OPTIONS requests before POST and PUT calls, introducing 50 to 150 milliseconds of latency.
• Header Injection Vulnerabilities: Web code cannot reliably append operating system-level hardware fingerprints without exposing the raw fingerprint logic to client-side inspection.
• Strict Network Sandboxing: Browser wrappers restrict direct socket connections and low-level protocol calls.

To resolve these limitations, Orbit Desktop introduces a native IPC network bridge in apps/desktop/crates/orbit-desktop-core/src/network/api_proxy.rs.

4.1 Implementation Mechanics

The client webview invokes proxy_api_request() via IPC. The native driver processes the request using an optimized asynchronous HTTP client:

pub async fn proxy_api_request(req: ProxyRequest) -> Result<ProxyResponse, String> {
    let client = reqwest::Client::builder()
        .timeout(std::time::Duration::from_secs(30))
        .build()
        .map_err(|e| e.to_string())?;

    let method = match req.method.to_uppercase().as_str() {
        "GET" => reqwest::Method::GET,
        "POST" => reqwest::Method::POST,
        "PUT" => reqwest::Method::PUT,
        "PATCH" => reqwest::Method::PATCH,
        "DELETE" => reqwest::Method::DELETE,
        other => return Err(format!("Unsupported HTTP method: {}", other)),
    };

    let mut request_builder = client.request(method, &req.url);

    // 1. Forward existing application headers
    let mut header_map = HeaderMap::new();
    if let Some(hdrs) = req.headers {
        for (k, v) in hdrs {
            if let (Ok(name), Ok(val)) = (
                HeaderName::from_bytes(k.as_bytes()),
                HeaderValue::from_str(&v),
            ) {
                header_map.insert(name, val);
            }
        }
    }

    // 2. Inject cryptographic hardware identification headers
    let hw_hash = generate_hardware_fingerprint();
    let now = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();

    if let Ok(val) = HeaderValue::from_str(&hw_hash) {
        header_map.insert(HeaderName::from_static("x-orbit-hw-hash"), val);
    }
    if let Ok(val) = HeaderValue::from_str(&now.to_string()) {
        header_map.insert(HeaderName::from_static("x-orbit-client-ts"), val);
    }

    request_builder = request_builder.headers(header_map);
    // ... send and return ProxyResponse
}

Because requests originate from the native systems runtime, the browser security sandbox is bypassed, eliminating CORS preflight handshakes and enabling the server to verify the physical origin of the request.

5. Performance & Network Telemetry

The native IPC proxy improves network throughput and decreases checkout latency:

6. Failure Modes & Recovery SOP

The following operational contingency protocols resolve desktop container and proxy anomalies:

7. Cross-Vertical Internal Linkages

The parameterized container and native IPC proxy bridge unify client applications across all domains:

• Split-Tender Cashiering & Offline Resilience — Dispatches high-speed cashier checkout requests through the native IPC proxy.
• Customer-Facing Display & Table Canvas — Coordinates dual-screen window geometry across dining room counters.
• ASTM & HL7 Analyzer Edge Gateway Integration — Connects physical diagnostic analyzers with cloud databases via the native proxy.
• RFID Turnstile Gate Kiosk & Tardiness Escalation — Operates fullscreen kiosk attendance stations with hardware-stamped request streams.
• Hardened Native Anti-Tamper Core — Enforces runtime security and clock watermarking across all containerized profiles.