Skip to content
Engineering

Hardware Integration & GERCIA Hub Architecture (Gercia.Edge)

Physical operations across Healthcare Verticals (Verticais de Saúde) require direct integration with bench hardware, precision sensors, and specialized medical/laboratory peripherals. In compounding pharmacies (farmácias de manipulação), regulatory standards governed by ANVISA RDC 67/2007 mandate sub-milligram precision analytical balances and high-density thermal label printers. In diagnostic centers and clinical analysis laboratories (LAC), ANVISA RDC 786/2023 demands automated specimen barcode tube labeling, while clinical practices require silent prescription printing.

The platform coordinates physical hardware via GERCIA Hub (internally codebase Gercia.Edge), a lightweight, high-reliability .NET 10 background worker service running locally on workstation PCs in healthcare facilities. In accordance with ADR-010, GERCIA Hub eliminates cloud WebSocket hairpinning, bridging raw physical interfaces (RS-232, USB Virtual COM, Network/RAW TCP sockets, Bluetooth LE) directly with the web application (@gercia/app) through high-performance local loopback (http://127.0.0.1:5050) and hybrid cloud print queues.

1. Physical Lab Workstation Topology

Section titled “1. Physical Lab Workstation Topology”

Each compounding station (e.g., solid weighing, liquid measuring, encapsulation, labeling) operates as an autonomous, offline-first edge node:

flowchart LR
    subgraph LAB ["Pharmacy Compounding Workstation (Cleanroom)"]
        subgraph HARDWARE ["Physical Devices"]
            SCALE["Precision Analytical Balance<br>(Toledo / Gehaka / Shimadzu / Ohaus)"]
            PRINTER["Thermal Label Printer<br>(Zebra ZPL / TSC TSPL / Argox)"]
        end

        subgraph WORKSTATION ["Station PC / Terminal"]
            EDGE["<b>Gercia.Edge (.NET 10 Daemon)</b><br>Runs on 127.0.0.1:5050<br>SerialPort & Local Raw Spooler"]
            UI["<b>@gercia/app (Angular 22 SPA)</b><br>Assisted Weighing UI"]
        end

        SCALE -- "RS-232 / USB Serial (9600-8-N-1)" --> EDGE
        EDGE -- "Local RAW Spooling (< 50ms)" --> PRINTER
        EDGE <== "Local WebSocket / HTTP (< 1ms)<br>100% Offline-First" ==> UI
    end

    subgraph CLOUD ["GERCIA Cloud SaaS Platform (GCP & Cloudflare)"]
        SERVER["<b>Gercia.Server (Cloud Run)</b><br>Stateless Minimal APIs • Scale-to-Zero<br>Zero Persistent WebSockets"]
        DB[(Google Cloud SQL PostgreSQL<br>core.print_jobs • Audit History)]
    end

    UI -. "1. Remote Batch Dispatch (HTTP POST)" .-> SERVER
    SERVER --> DB
    EDGE -. "2. Background Audit Confirmation (Fire-and-Forget)" .-> SERVER

2. Station Identity & Security Model

Section titled “2. Station Identity & Security Model”

Workstations in compounding laboratories are cryptographically paired with specific pharmacy branches and physical rooms to prevent cross-contamination of compounding records:

  1. Station Tokens (API Keys): Each laboratory station is provisioned with a high-entropy station secret generated during station registration in @gercia/app. The token is stored securely on the local edge machine using Windows DPAPI or encrypted configuration files.
  2. Local Loopback Security: Gercia.Edge binds locally to http://127.0.0.1:5050. The HTTP and WebSocket server enforces strict CORS Origin Validation restricted exclusively to https://app.gercia.com.br, https://app.gercia.vet.br, local development loopbacks (https://app.gercia.dev, https://vet.gercia.dev), and authenticated station token headers (X-Station-Token).
  3. Outbound Cloud Authentication: When communicating with Gercia.Server for audit confirmations or cloud outbox polling, Gercia.Edge executes standard outbound HTTPS requests over TLS 1.3. No inbound ports are ever opened on the pharmacy’s local internet router.

3. Precision Analytical Balance Protocol

Section titled “3. Precision Analytical Balance Protocol”

Compounding operations require sub-milligram accuracy (often 4 decimal places: 0.0001 g or 0.1 mg). The Gercia.Edge serial engine communicates with analytical and semi-analytical balances via RS-232 or USB-to-UART bridge controllers.

Supported Manufacturer Protocols

Section titled “Supported Manufacturer Protocols”
Manufacturer Sample Models Standard Baud Rate Framing Protocol Flavor
Gehaka BK, BG, AG series 9600 / 4800 8-N-1 / 7-E-1 Continuous & Stable P-Cont
Toledo / Mettler Toledo Prix 3, 3400, AB-S, XP 9600 8-N-1 MT-SICS (Command/Response) & Toledo Continuous
Shimadzu ATX, AUW, AUX, BL 1200 / 9600 7-E-1 / 8-N-1 Standard Unidirectional Stream
Ohaus Adventurer, Pioneer, Explorer 9600 8-N-1 Ohaus Continuous / Auto-Print
Filizola BP, CS, Platina 2400 / 9600 8-N-1 Standard Filizola Frame (STX...ETX)

Data Frame Parsing & Weight Normalization

Section titled “Data Frame Parsing & Weight Normalization”

Balances transmit frames either in Continuous Mode (streaming 10-20 times per second) or Stable-Only Mode (streaming only after the mechanical oscillation dampens). Gercia.Edge continuously normalizes these divergent protocols into a unified internal model:

public sealed record ScaleWeightReading(
    Guid StationId,
    decimal NetWeightGrams,
    decimal TareWeightGrams,
    bool IsStable,
    bool IsNegative,
    bool IsOverloaded,
    string UnitOfMeasure,
    DateTimeOffset Timestamp
);

Frame Parsing State Machine

Section titled “Frame Parsing State Machine”
flowchart TD
    RAW["Raw Byte Buffer (System.IO.Ports)"] --> DELIM["Detect Delimiter (CR / LF / ETX)"]
    DELIM --> VALIDATE["Checksum & Frame Boundary Validation"]
    VALIDATE --> CLEAN["Strip Polarity & Unit Characters (+, -, g, mg, kg)"]
    CLEAN --> STABILITY{"Stability Flag<br>('ST' vs 'US')"}
    STABILITY -- "Stable ('ST')" --> EMIT_STABLE["Emit ScaleWeightReading<br>(IsStable = true)"]
    STABILITY -- "Unstable ('US')" --> EMIT_DYNAMIC["Emit Dynamic Reading<br>(IsStable = false)"]
    EMIT_STABLE --> DISPATCH["Stream via Local WebSocket (ws://127.0.0.1:5050/ws/scale)"]
    EMIT_DYNAMIC --> DISPATCH

4. Assisted Weighing Lifecycle (Pesagem Assistida)

Section titled “4. Assisted Weighing Lifecycle (Pesagem Assistida)”

To guarantee 100% compliance with ANVISA RDC 67/2007, operators cannot manually type raw weights into the web system. All weights are captured directly from the physical scale through local loopback, preserving complete functionality even if the internet drops:

sequenceDiagram
    autonumber
    actor OP as Compounding Operator
    participant UI as @gercia/app (Angular SPA)
    participant EDGE as Gercia.Edge (127.0.0.1:5050)
    participant BALANCE as Analytical Balance
    participant Server as Gercia.Server (Cloud Run)

    OP->>UI: Selects Compounding Order #OM-2026-0881
    UI->>UI: Displays target active ingredient (e.g., Minoxidil 5.000g)
    UI->>EDGE: Connects to local scale stream (ws://127.0.0.1:5050/ws/scale)
    OP->>BALANCE: Places weighing boat / capsule
    BALANCE-->>EDGE: Raw streaming bytes: "ST,GS,+000.4125g"
    EDGE-->>UI: Real-time weight updates (< 1ms latency)
    OP->>BALANCE: Presses TARE button on physical scale
    BALANCE-->>EDGE: "ST,NT,+000.0000g"
    EDGE-->>UI: Weight zeroed. Displays target range: 4.950g - 5.050g (±1%)
    OP->>BALANCE: Adds chemical substance onto weighing boat
    BALANCE-->>EDGE: "US,NT,+004.8210g" (Operator adding powder)
    EDGE-->>UI: Live progress bar: Yellow (Under target)
    OP->>BALANCE: Final powder tap, withdraws spatula
    BALANCE-->>EDGE: "ST,NT,+005.0012g" (Stable reading locked)
    EDGE-->>UI: Green highlight (Within ±1% tolerance)
    UI->>Server: ConfirmWeighing(componentId, actualWeight: 5.0012g)
    Server->>Server: Records immutable audit trail in clinical/pharmacy schema

5. Hybrid Thermal Label Printing Architecture

Section titled “5. Hybrid Thermal Label Printing Architecture”

Compounding pharmacies generate labels for active formulas, stock fractions, and final patient packaging. Gercia.Edge handles physical thermal printing using printer-native command languages to guarantee barcode and micro-text sharpness without anti-aliasing blur.

Supported Command Languages

Section titled “Supported Command Languages”
  • ZPL II (Zebra Programming Language): Standard for industrial and desktop Zebra printers (ZD220, ZD230, GK420t).
  • TSPL / TSPL2: Standard for TSC, Argox, and Godex printers (TSC TE200, TTP-244 Pro).
  • ESC/POS: Standard for thermal receipt printers (Epson TM-T20, Elgin i9) used for internal routing vouchers.

The Two Printing Delivery Paths (ADR-010)

Section titled “The Two Printing Delivery Paths (ADR-010)”
flowchart TD
    subgraph BENCH ["1. Interactive Bench Printing (< 50ms)"]
        SPA1["Angular SPA (@gercia/app)"] == "Direct HTTP POST (127.0.0.1:5050)<br>Raw ZPL Payload" ==> EDGE1["Gercia.Edge Local"]
        EDGE1 -->|"Windows Spooler (RAW)"| PRT1["Local Zebra / Elgin Printer"]
    end

    subgraph CLOUD_SPOOL ["2. Enterprise Branch Print Server (< 200ms)"]
        SPA2["Headquarters / Remote User"] -->|"Stage Print Job"| CLOUD["Gercia.Server (Cloud Run)"]
        CLOUD -->|"INSERT"| DB[("core.print_jobs")]
        DB -.->|"Long-Polling Stream"| EDGE2["Gercia.Edge (Branch Server)"]
        EDGE2 -->|"Raw TCP (Port 9100)"| PRT2["Expedition Room Printers"]
    end
  1. Interactive Bench Printing (< 50ms):
    • Dispatched directly from the browser to Gercia.Edge on the same machine.
    • Uses the Windows Print Spooler (winspool.drv / RawPrinterHelper) for silent, instantaneous printing without browser print dialogs.
  2. Enterprise Cloud Outbox Printing (< 200ms):
    • For centralized print servers or multi-branch batch orders.
    • Jobs are enqueued in core.print_jobs and consumed by Gercia.Edge via HTTP Long-Polling streams.

Anvisa RDC 67/2007 Label Requirements

Section titled “Anvisa RDC 67/2007 Label Requirements”

Every compounded product label generated strictly incorporates:

  1. Patient full name and unique medical chart number.
  2. Prescribing healthcare professional full name and CRM/CRO/CRMV registration.
  3. Complete quantitative composition (active ingredients with exact metric dosages and excipient vehicle).
  4. Compounding order internal number (Ordem de Manipulação - OM) and internal batch number (Lote Magistral).
  5. Exact compounding date, expiration date (Data de Validade), and storage conditions (e.g., Conservar em geladeira entre 2°C e 8°C).
  6. Supervising Responsible Pharmacist full name and Regional Pharmacy Council (CRF) number.
  7. Mandatory legal warnings for controlled substances (Portaria 344/98 - e.g., Venda sob Prescrição Médica - Retenção de Receita).
  8. High-density GS1 DataMatrix or QR Code encoding the prescription verification URL (https://app.gercia.com.br/v/{prescriptionId}).

ZPL II Label Generation Template

Section titled “ZPL II Label Generation Template”
^XA
^PW640
^LL480
^PON
^FO30,30^A0N,28,28^FDGERCIA PHARMACY - LAB 01^FS
^FO30,65^A0N,22,22^FDPaciente: JOAO DA SILVA ROCHA^FS
^FO30,95^A0N,20,20^FDDr(a): DRA. MARIANA SOUZA (CRM/SP 184920)^FS
^FO30,130^GB580,2,2^FS
^FO30,145^A0N,22,22^FDMINOXIDIL 5% / FINASTERIDA 0.1%^FS
^FO30,175^A0N,18,18^FDSolucao Capilar Hidroalcoolica q.s.p. 100 mL^FS
^FO30,205^A0N,18,18^FDUso: Aplicar 1 mL no couro cabeludo a noite^FS
^FO30,240^GB580,2,2^FS
^FO30,255^A0N,18,18^FDOM: 2026-0881 | Lote: LMAG-260906^FS
^FO30,285^A0N,18,18^FDManipulado em: 06/09/2026 | Validade: 06/03/2027^FS
^FO30,315^A0N,18,18^FDFarm. Resp.: Dra. Camila Duarte CRF/SP 42.109^FS
^FO460,345^BXN,6,200^FDhttps://app.gercia.com.br/v/0191c784-0a32-7210-9031-1f9e2b1049c1^FS
^FO30,380^A0N,20,20^FDUso Externo | Agite Antes de Usar^FS
^XZ

6. Offline Spooling & Fault Tolerance

Section titled “6. Offline Spooling & Fault Tolerance”

Compounding cleanrooms cannot halt operations during transient network blips. Gercia.Edge incorporates autonomous offline resilience:

  1. Local SQLite Ledger: If the facility’s internet connection drops, Gercia.Edge buffers completed weighing sessions and audit confirmations in a local encrypted SQLite database (edge_spool.db).
  2. Autonomous Bench Continuity: Assisted weighing and physical thermal label printing continue uninterrupted at the local workstation.
  3. Queue Drain & Reconciliation: Upon link restoration, buffered records are flushed to Gercia.Server via outbound HTTPS with original hardware-generated UTC timestamps for immutable auditing.