Skip to content
Engineering

ADR-010: Local Edge Hardware Integration, Hybrid Printing Architecture, and Serverless Real-Time Strategy

Status

Section titled “Status”

ACCEPTED  2026-10-11

Context

Section titled “Context”

The initial architectural design for bench hardware telemetry (analytical balances, thermal label printers) and push notifications (Push-to-Sign) envisioned centralized SignalR WebSockets running inside Gercia.Server on Google Cloud Run, alongside experimental FastMCP AI host routing. While conceptually straightforward, rigorous operational analysis, cloud economics, and compounding pharmacy cleanroom ergonomics revealed three critical architectural bottlenecks:

  1. Cloud Run Serverless Impedance Mismatch & Fixed Cost Inflaters:

    • Google Cloud Run is architecturally engineered as a stateless, ephemeral compute tier with automatic scale-to-zero. Persistent WebSockets keep request streams continuously open, forcing Cloud Run to allocate dedicated CPU 24/7 without scaling to zero. Maintaining continuous active instances in southamerica-east1 (São Paulo) incurs ~$50 to $70 USD/month per instance.
    • The Backplane Dilemma: When Cloud Run scales out to multiple horizontal container revisions, broadcasting WebSocket messages across instances requires an external Redis backplane (e.g., Google Cloud Memorystore for Redis), which cannot scale to zero and adds a minimum of ~$35 to $50 USD/month in fixed cloud spend, plus VPC peering latency.

  2. The “Curitiba-to-São Paulo” Hairpinning Anti-Pattern:

    • In a compounding cleanroom (sala limpa), the analytical balance (Toledo, Gehaka) is plugged via RS-232/USB into the local workstation PC, and the cleanroom technician operates the web interface on that exact same workstation.
    • Routing high-frequency serial readings (10–20 readings/sec) from the local machine in Curitiba to Cloud Run in São Paulo, only to broadcast them back via WebSocket to the browser on the same desk, introduces unnecessary network latency (50–150ms), consumes cloud bandwidth, and creates a catastrophic dependency: a 2-second internet flicker prevents the pharmacist from weighing regulated substances.

  3. Label Printing Ergonomics & Print Spooler Latency:

    • Printing thermal prescription labels (Zebra, Elgin, Argox) on 100x50mm adhesive media requires silent, instant printing (< 50ms) without browser print dialogs (Ctrl+P).
    • Relying on naive asynchronous cloud polling (every 3 to 5 seconds) causes intolerable delays at the bench: the operator clicks “Print”, waits 3 seconds, assumes the system hung, and clicks again, generating duplicate labels and violating ANVISA RDC 67/2007 batch integrity controls.
    • Conversely, corporate network topologies require central print servers where a single physical machine in a pharmacy branch manages multiple network thermal printers across different compounding rooms.

  4. Terminology Drift (“FastMCP” vs. Sovereign .NET Architecture):

    • “FastMCP” is a Python/TypeScript framework from Anthropic’s open-source ecosystem. In C# and .NET 10, Model Context Protocol (MCP) servers are implemented natively via standard Minimal API endpoints over HTTP/SSE and JSON-RPC. Labeling .NET endpoints as “FastMCP” introduced conceptual confusion across engineering documentation.

Decision

Section titled “Decision”

The GERCIA Platform officially decommissions cloud-hosted SignalR WebSockets and Python “FastMCP” terminology, establishing a Three-Tier Local Edge, Hybrid Printing, and Serverless Real-Time Architecture:

flowchart TD
    subgraph CLEANROOM ["1. Local Cleanroom Workstation (Physical Bench)"]
        SCALE["Precision Analytical Balance<br>(Gehaka / Toledo / Marte)"] -->|"RS-232 / USB Serial"| EDGE_LOCAL["<b>Gercia.Edge Daemon (GERCIA Hub)</b><br>Runs locally on station PC (127.0.0.1:5050)<br>Raw ZPL Spooler & Serial Streamer"]
        EDGE_LOCAL <== "Local WebSocket / HTTP (< 1ms)<br>100% Offline-First • Zero Cloud Latency" ==> SPA["Angular Enterprise SPA (@gercia/app)<br>Assisted Cleanroom Weighing UI"]
        EDGE_LOCAL -->|"Raw ZPL Direct Spooling (< 50ms)"| LOCAL_PRINTER["Zebra / Elgin Thermal Printer"]
    end

    subgraph BRANCH_NETWORK ["2. Branch Central Print Server (Optional Enterprise LAN)"]
        LAN_EDGE["<b>Gercia.Edge (LAN Server Mode)</b><br>Dedicated Branch Server (e.g. 192.168.1.50:5050)"]
        LAN_EDGE -->|"Raw TCP (Port 9100 / JetDirect)"| NET_PRINTER["Network Thermal Printers<br>(Expedition & Packaging Rooms)"]
    end

    subgraph CLOUD_SERVERLESS ["3. Stateless Cloud Tier (Google Cloud Run & Cloudflare)"]
        SERVER["<b>Gercia.Server (.NET 10 Minimal APIs)</b><br>Stateless • 100% Scale-to-Zero • Zero Redis Backplane<br>REST Gateway • Sovereign OpenIddict STS • Native MCP"]
        DB[(Google Cloud SQL PostgreSQL 18<br>core.print_jobs • clinical • pharmacy)]
    end

    SPA -. "1. Remote Batch Dispatch (HTTP POST)" .-> SERVER
    SERVER --> DB
    DB -. "2. Long-Polling Stream (< 200ms Latency)" .-> LAN_EDGE
    EDGE_LOCAL -. "3. Background Audit Confirmation (Fire-and-Forget)" .-> SERVER

1. Local Edge Hardware Orchestration (Gercia.Edge at 127.0.0.1:5050)

Section titled “1. Local Edge Hardware Orchestration (Gercia.Edge at 127.0.0.1:5050)”
  • Local Loopback Communication: Gercia.Edge runs as a lightweight Windows/Linux service on the local workstation, exposing a local Kestrel endpoint bound to http://127.0.0.1:5050 (and WebSocket at ws://127.0.0.1:5050/ws/scale).
  • Instantaneous Telemetry & Zero Cloud Dependency: Serial balance streams (Gehaka, Toledo, Marte, Shimadzu) flow directly from the physical COM port into the local browser session with < 1ms latency. If the facility’s internet connection drops, the cleanroom technician continues weighing and compounding without interruption.
  • Security Model: The local edge API enforces strict CORS origins restricted to app.gercia.com.br, app.gercia.vet.br, and local developer loopbacks (app.gercia.dev, vet.gercia.dev), authenticated with a machine-bound station token.

2. Hybrid Printing Topology: Direct Local (< 50ms) vs. Remote Cloud Outbox (< 200ms)

Section titled “2. Hybrid Printing Topology: Direct Local (< 50ms) vs. Remote Cloud Outbox (< 200ms)”

To guarantee zero operator latency while supporting multi-room enterprise print servers:

  1. Path A — Interactive Bench Printing (< 50ms):
    • When an operator clicks “Print Label”, the Angular SPA sends the raw ZPL/EPL payload directly to the local agent: POST http://127.0.0.1:5050/api/print.
    • Gercia.Edge dispatches raw bytes directly to the Windows Print Spooler (winspool.drv / RawPrinterHelper) or raw TCP port 9100.
    • Result: The physical label begins printing in < 50 milliseconds. The edge daemon then confirms completion to Gercia.Server asynchronously for regulatory auditing (ANVISA RDC 67/2007).
  2. Path B — Branch Network & Remote Cloud Outbox (< 200ms):
    • For enterprise pharmacies with central print servers in shipping rooms, or when a remote headquarters dispatches print jobs to a branch laboratory:
    • The job is staged to core.print_jobs in PostgreSQL with status = 'pending'.
    • Gercia.Edge maintains an outbound HTTP Long-Polling stream (GET /v1/branches/{id}/print-jobs/listen). The connection is suspended on Cloud Run without CPU billing; when a new job arrives, Cloud Run flushes the response immediately.
    • Result: The remote printer fires in < 200 milliseconds (bounded only by WAN ping), eliminating polling delay while avoiding 24/7 WebSocket backplanes.

3. Serverless Real-Time Notifications (Push-to-Sign)

Section titled “3. Serverless Real-Time Notifications (Push-to-Sign)”
  • In the digital prescription workflow (CFM Res. 2.314/2022), the desktop web client displays an authorization modal for a maximum 60-second window while the clinician confirms biometric FaceID on their smartphone.
  • Rather than maintaining persistent WebSockets 24/7, the desktop modal executes lightweight Smart Short-Polling (GET /v1/prescriptions/{id}/status every 1.5 seconds) or native Server-Sent Events (SSE) during the active modal.
  • When the clinician authorizes on their phone (POST /v1/signatures/verify), the database updates atomically. The next poll immediately receives the Signed state, closing the modal.
  • Result: Cloud Run preserves complete scale-to-zero when no prescriptions are being signed, eliminating Redis backplanes and saving >$100 USD/month in cloud infrastructure.

4. Native Model Context Protocol (MCP) Standardization

Section titled “4. Native Model Context Protocol (MCP) Standardization”
  • All references to “FastMCP” are permanently retired.
  • AI agent tool execution and clinical copilots are exposed as Sovereign MCP Endpoints implemented natively via ASP.NET Core Minimal APIs inside Gercia.Server (mapped under /mcp or host-routed via mcp.gercia.com.br).
  • Endpoints adhere to the official JSON-RPC 2.0 MCP specification over HTTP with Server-Sent Events (SSE), directly leveraging EF Core, Row-Level Security (RLS), and pgvector semantic search in the ai schema.

Consequences & Trade-offs

Section titled “Consequences & Trade-offs”

Positive:

Section titled “Positive:”
  • True Scale-to-Zero & 90% Cloud Cost Reduction: Eliminating persistent cloud WebSockets and Redis backplanes allows Google Cloud Run to scale to zero instances during off-peak hours, reducing monthly backend hosting costs to near-zero ($0 to $5 USD/month on base tiers).
  • Zero Bench Latency (< 50ms): Operators experience instantaneous physical label printing and smooth 60fps balance weight displays directly through local loopback.
  • Offline-First Cleanroom Resilience: Compounding weighing and local label printing operate uninterrupted even during regional ISP outages or fiber cuts.
  • Simplified Infrastructure: Zero Redis clusters to patch, monitor, or size in Google Cloud Platform.
  • Architectural Purity: Model Context Protocol (MCP) is implemented in clean, idiomatic C# .NET 10 without mixing Python package naming.

Trade-offs & Mitigations:

Section titled “Trade-offs & Mitigations:”
  • Local Daemon Prerequisite: Station PCs must run Gercia.Edge to communicate with USB balances and printers.
    • Mitigation: Gercia.Edge is packaged as an automated single-file Windows installer/daemon that registers as a lightweight Windows Service, automatically starting on boot with zero operator intervention.
  • Mixed-Content Browser Restrictions: Modern browsers accessing HTTPS sites (app.gercia.com.br) restrict plaintext HTTP calls to localhost in certain contexts.
    • Mitigation: Chromium and modern browsers explicitly permit loopback exceptions for http://127.0.0.1 and http://localhost (RFC 6761). For advanced enterprise setups, Gercia.Edge binds a local self-signed certificate or leverages local domain resolution (station.local.gercia.dev).