DaemonX - Hardware Integration Platform Guide

System: Nyxzie DaemonX Hardware & POS Infrastructure
Architecture: Two-Tier Hybrid (Cloud Orchestration + Local Hardware Bridge)
Current Version: v1.0.2
Status: Production Active

1. Executive Summary & The Two-Tier Architecture

DaemonX provides sub-15ms, zero-dialog physical hardware spooling (ESC/POS thermal receipt printers, laser/inkjet A4 invoice printers, cash drawers, scales, and customer displays) for modern web-based Point of Sale (POS) applications.

To deliver hardware speed without compromising security, DaemonX separates operations into two distinct tiers:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 DAEMONX ARCHITECTURE                                   │
└───────────────────────────────────────────┬────────────────────────────────────────────┘
                                            │
                ┌───────────────────────────┴───────────────────────────┐
                ▼                                                       ▼
 ┌─────────────────────────────────────────┐             ┌─────────────────────────────────────────┐
 │       TIER 1: NYXZIE CLOUD CORE         │             │      TIER 2: LOCAL DESKTOP DAEMON       │
 │            (core/ directory)            │             │           (bridge/ directory)           │
 ├─────────────────────────────────────────┤             ├─────────────────────────────────────────┤
 │ • Base URL: https://api.nyxzie.com      │             │ • Base URL: http://127.0.0.1:9123       │
 │ • Network: Public Cloud (HTTPS)         │             │ • Network: OS Loopback Only             │
 │ • Caller: Your Backend Server           │             │ • Caller: Cashier Web Browser (POS)     │
 │ • Auth: Developer API Bearer Token      │             │ • Auth: X-Bridge-Counter-Id + Secret    │
 │ • Role: Provisioning, Fleet, Pairing,   │             │ • Role: Raw USB/LAN Byte Spooling,      │
 │   Telemetry & Webhook Outbox            │             │   RJ11 Solenoid Kick, Printer Discovery │
 └─────────────────────────────────────────┘             └─────────────────────────────────────────┘

2. Global Data Flow Diagram

┌───────────────────────────────┐                  ┌──────────────────────────────────────────┐
│   Your Cloud Backend Server   │                  │          Nyxzie Cloud Core API           │
│   (SaaS / Retail Management)  │                  │     (https://api.nyxzie.com/api/v1)      │
└───────────────┬───────────────┘                  └────────────────────┬─────────────────────┘
                │                                                       │
                │ 1. POST /onboarding/sessions (Bearer nyx_daemonx_...) │
                ├──────────────────────────────────────────────────────>│
                │    Returns: 6-digit code ("842915") & session_id      │
                │<──────────────────────────────────────────────────────┤
                │                                                       │
                │                                                       │
┌───────────────┴───────────────┐                  ┌────────────────────┴─────────────────────┐
│    Cashier Browser (Web POS)  │                  │      DaemonX Local Desktop Bridge        │
│  (https://pos.yourdomain.com) │                  │         (http://127.0.0.1:9123)          │
└───────────────┬───────────────┘                  └────────────────────┬─────────────────────┘
                │                                                       │
                │ 2. Cashier enters 6-digit code into Desktop App GUI   │
                │    Desktop app connects to Core & securely saves creds│
                │    Core triggers webhook: daemonx.onboarding.completed│
                │                                                       │
                │ 3. Probe: GET http://127.0.0.1:9123/api/health        │
                ├──────────────────────────────────────────────────────>│
                │    Returns: { status: "ready", paired: true }         │
                │<──────────────────────────────────────────────────────┤
                │                                                       │
                │ 4. Print: POST http://127.0.0.1:9123/api/print/thermal│
                ├──────────────────────────────────────────────────────>│──┐ 5. USB/LAN
                │    Headers: X-Bridge-Counter-Id, Profile-Secret       │  │    Raw Bytes
                │    Response: { success: true, latency_ms: 11 }        │  ▼
                │<──────────────────────────────────────────────────────┤ ┌─────────────────┐
                │                                                       │ │ Physical ESC/POS│
                │                                                       │ │ Thermal Printer │
                │                                                       │ └─────────────────┘

3. The 5-Step Integration Lifecycle Pattern

When integrating DaemonX into your retail SaaS or web POS, implement the lifecycle across your backend and frontend in these 5 sequential stages:

Step 1: Session Creation (Backend Server → Core API)

Your backend initiates an onboarding session when a merchant clicks "Add Cash Register / Counter" in your portal:

• Request: POST https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions
• Headers: Authorization: Bearer nyx_daemonx_live_<your_token>
• Payload: { "counter_name": "Front Desk Lane 1", "external_customer_ref": "cust_99" }
• Result: Receives an ephemeral 6-digit pairing code (e.g. 842915) valid for 900 seconds (15 minutes).
• Doc: core/02a_POST_api_v1_daemonx_onboarding_sessions.md

Step 2: Workstation Activation (Cashier → Desktop App)

The cashier downloads and launches the DaemonX Windows Desktop App (.exe) on the physical register:

1. The app displays an activation prompt: "Enter 6-Digit Pairing Code".
2. Cashier types 842915.
3. The desktop app contacts Nyxzie Core, generates cryptographic machine credentials, and completes identity binding.
4. Core writes a completed counter row and locks the credentials locally inside secure encrypted storage.

Step 3: Completion Confirmation (Core API → Backend Server)

Your backend confirms pairing using one of two patterns:

• Webhook (Recommended): Core dispatches daemonx.onboarding.completed to your webhook URL containing the newly provisioned counter_id.
• Polling: Your frontend/backend polls GET https://api.nyxzie.com/api/v1/daemonx/onboarding/sessions/:id until status === "completed".
• Doc: core/02b_GET_api_v1_daemonx_onboarding_sessions_id.md

Step 4: Local Bridge Probing (Browser Web POS → Localhost)

When the cashier opens the web POS interface in Chrome, Edge, or Firefox:

1. The web application issues an HTTP request to GET http://127.0.0.1:9123/api/health.
2. DaemonX responds immediately with loopback status, connected printers, and paired counter info.
3. If the daemon is not running, the POS displays a friendly banner: "DaemonX bridge not detected. Please launch the desktop application."
4. Doc: bridge/01_GET_api_health.md

Step 5: Silent Printing & Drawer Control (Browser Web POS → Localhost)

Upon completing a sale:

1. Web POS constructs the receipt payload (raw text, ESC/POS formatting, barcode, cutter commands).
2. Sends POST http://127.0.0.1:9123/api/print/thermal directly to loopback.
3. DaemonX streams the raw bytes directly to the Windows print spooler in under 15ms without showing any print dialogue or prompt.
4. Doc: bridge/03_POST_api_print_thermal.md

4. Security & Credential Isolation Matrix

To prevent compromised browser tabs from tampering with fleet configurations or stealing developer tokens, DaemonX enforces strict credential separation:

Network & WAF Safeguards:

• Loopback-Only Binding: DaemonX rejects all non-loopback IPs (127.0.0.1, ::1) with 403 Forbidden. External LAN attacks cannot hit port 9123.
• CORS & Private Network Access (PNA): DaemonX honors Chrome/W3C PNA preflight standards and strictly validates the Origin header against the developer's registered POS domain.
• Token Scope Gating: Core developer tokens are gated by endpoint scope (/api/v1/daemonx/counters and /api/v1/daemonx/onboarding/sessions).

5. Master API Directory & Documentation Index

5.1. Tier 1: Cloud Core API Reference (./core/)

Full specification guide: core/README.md

5.2. Tier 2: Local Hardware Bridge API Reference (./bridge/)

Full specification guide: bridge/README.md

6. Implementation Checklist for Developers

• Store Developer Token Securely: Ensure nyx_daemonx_live_* is stored on your server and never bundled in client-side code.
• Listen for Webhooks: Register an HTTPS webhook endpoint for daemonx.onboarding.completed events and verify HMAC signatures.
• Handle Bridge Availability: Implement fallback UI in your POS frontend when GET http://127.0.0.1:9123/api/health returns offline.
• Configure Allowed Origins: Ensure your POS web domain (e.g. https://pos.yourdomain.com) is configured in your Developer Portal profile so CORS passes.
• Use Standard ESC/POS Commands: For thermal printing, pass standard byte sequences or formatted text strings as documented in bridge/03_POST_api_print_thermal.md.