Technical Documentation

System Architecture

QueueVIO is a cloud-native Universal Print API built on a four-layer architecture. Cloud intelligence handles AI and routing; an on-premise agent bridges physical devices; a Model Context Protocol server exposes operations to AI clients.

The Four Layers

Every job moves top-to-bottom through these layers. AI decisions flow cloud-down; device status and outcomes flow cloud-up.

Layer 1External Clients

MIS Systems, Prepress Tools & AI Agents

Any system that submits print jobs or subscribes to events. Connects over HTTPS REST or SSE. Authentication is JWT-based. AI agents connect via the MCP server using the Model Context Protocol.

REST API ClientMIS / ERPPrepress SoftwareClaude / Cursor (MCP)Custom Webhook ConsumerSSE Dashboard
HTTPS / SSE
Layer 2Cloud

QueueVIO Cloud API

The core intelligence layer. Handles all business logic, AI inference, routing decisions, and persistent storage. Exposes a full OpenAPI 3.1 REST surface plus a Server-Sent Events stream for real-time updates.

AI Intake Service
NL → structured job via AI-powered extraction
Routing Engine
Hard veto → AI scoring → selection
Job Service
Production chain management
Device Registry
Capability envelopes + AI signals
Event Emitter
Tenant-scoped SSE broadcast
Connector Registry
Heartbeat + job dispatch queue
Poll / Heartbeat (HTTP)
Layer 3On-Premise

Connector Agent

A lightweight Node.js daemon running inside the print facility. It polls the cloud API for queued jobs, translates them into device-native formats (IPP, JDF, hot folder, vendor REST), submits to physical devices, and reports status back. No inbound firewall rules required — all communication is outbound HTTPS initiated by the agent.

Poller
Fetches assigned jobs every 5 s (configurable)
Heartbeat
Sends CPU, memory, queue depth every 30 s
Adapter Registry
24+ device-specific translation drivers
SNMP Monitor
Polls device counters and health metrics
IPP · JDF · Hot Folder · Vendor REST · LPR · SNMP
Layer 4Physical Devices

Print Devices & Finishing Equipment

The physical production floor — digital presses, offset presses, RIP servers, wide-format printers, label/packaging systems, and finishing equipment. QueueVIO never requires changes to existing device firmware or configuration; the connector adapter speaks the device's native protocol.

EFI Fiery DFEHP IndigoHeidelberg PressRicoh TotalFlowXerox FreeFlowONYX RIPRoland Wide-FormatZebra LabelDuplo FinisherHorizon JDF Folder

Cloud API Components

The cloud API exposes a REST interface and a Server-Sent Events endpoint. All data is persisted with strict per-tenant isolation.

AI Intake Service

  • ›Receives POST /api/intents with nlText payload
  • ›Calls an AI model with a structured tool definition
  • ›Model extracts: quantity, substrate, gsm, color space, finishing ops, due date
  • ›Returns per-field confidence scores (0–1) and ambiguity flags
  • ›If overall confidence ≥ autoApproveThreshold (default 0.80) and no ambiguities → auto-approved
  • ›Below threshold → status: pending_review; operator sees the draft with confidence annotations

Routing Engine

  • ›Triggered when a job enters routed state
  • ›Decomposes job into production stages (print, binding, finishing, laminating, coating)
  • ›For each stage: applies hard vetoes — eliminates offline devices, substrate mismatch, missing capabilities
  • ›Remaining candidates scored by an AI model across multiple dimensions
  • ›Scores: capabilityFit, queueFit, slaRisk, historicalWaste, gangOpportunity, maintenanceRisk
  • ›Top-ranked device selected; full RoutingDecision record persisted with all scores + reasoning

Device Registry

  • ›Stores device records with full capability envelopes (substrate range, color spaces, finishing ops)
  • ›Per-device AI signals updated by connector: queue depth, historical waste %, SLA compliance rate, maintenance risk score
  • ›Status machine: online → error → maintenance → offline
  • ›Capability envelope queried by routing engine as the veto data source
  • ›GET /api/devices/:id/capabilities returns the full machine envelope

Event System (SSE)

  • ›All internal state changes emit events via a tenant-scoped emitter
  • ›GET /api/events opens a persistent SSE connection (requires X-Tenant-Id header)
  • ›Event envelope: { tenantId, eventType, source, payload, timestamp }
  • ›Types: job.submitted, job.routed, job.queued, job.completed, device.online, device.error, ai.intent.extracted, alert.sla_breach
  • ›Each SSE connection is isolated to the requesting tenant — no cross-tenant leakage

Connector Registry

  • ›Connector agents self-register on first start via POST /api/connectors
  • ›Connector ID persisted locally in connector-id.txt; reused on restart
  • ›Heartbeat PATCH every 30 s: cpu%, memory%, active jobs, queue depth
  • ›GET /api/jobs/dispatch?connectorId=X returns jobs where productionChain[].connectorId matches
  • ›Cloud marks jobs as dispatched once connector confirms submission

Multi-Tenant Isolation

  • ›Every record is stamped with tenantId at write time
  • ›All queries include { tenantId } filter — no cross-tenant data visible
  • ›Tenant settings store: timezone, autoApproveThreshold, aiRoutingEnabled, featureFlags
  • ›API key / JWT scoped to one tenant; cannot escalate to another
  • ›SSE streams isolated per tenant on server side
MCP Server

AI Agent Integration

The MCP (Model Context Protocol) server exposes QueueVIO's operations as structured tools that any MCP-compatible AI agent — Claude, Cursor, or custom agents — can call. The server speaks the standard MCP protocol over HTTP with Server-Sent Events for bidirectional messaging.

list_jobs
(status?: string)

Returns all jobs for the tenant, optionally filtered by status.

get_job
(id: uuid)

Full job detail including production chain and stage assignments.

get_routing_decisions
(jobId: uuid)

Complete routing audit trail — hard vetoes, AI scores, selected device, outcome.

list_devices
()

All registered devices with current status and AI signals.

get_capabilities
(deviceId: uuid)

Full capability envelope: substrate range, color spaces, finishing ops, AI signals.

create_device
(name, deviceType, connectorId, adapterType, config?, ...)

Register a new print device under an existing connector, with its own adapter type and host/port/etc config.

create_intent
(nlText, contextHints?)

Submit a natural-language job brief; returns intent with extraction result. Emits progress notifications during AI processing.

list_connectors
()

All connector agents with last-heartbeat status and metrics.

create_connector
(name, version?)

Register a new connector agent — the on-prem router for a site. Devices under it each carry their own adapter type and config.

list_adapters
()

Supported adapter types and the config fields each one requires.

list_logs
(limit?: number)

Tenant activity log — plain-language entries for routing failures, AI flags, device status changes.

MCP Tool Call — create_intent
{
  "method": "tools/call",
  "params": {
    "name": "create_intent",
    "arguments": {
      "nlText": "500 A3 posters, UV gloss,
        full bleed, needed by Thursday",
      "contextHints": {
        "priority": "high"
      }
    }
  }
}
Tool Result
{
  "id": "int_01j9xm...",
  "status": "auto_approved",
  "confidence": 0.91,
  "jobDraft": {
    "quantity": { "ordered": 500 },
    "substrate": {
      "type": "coated",
      "weightGsm": 170
    },
    "colorSpace": "CMYK",
    "finishing": ["uv_gloss"],
    "status": "routed",
    "selectedDevice": "Roland VersaWorks (Bay 2)"
  }
}

The MCP server authenticates via JWT Bearer token in production or a dev-modeX-Tenant-Id header. Session IDs are used to correlate tool calls with their SSE notification channels.

Core Data Schemas

Eleven JSON schemas define the canonical shape of all data in QueueVIO. Every stored record conforms to one of these schemas. The OpenAPI spec is generated from them.

job.schema.json
  • id (uuid)
  • tenantId
  • status
  • productionChain[]
  • quantity
  • substrate
  • colorSpace
  • finishing[]
  • dueDate
ai-intent.schema.json
  • id
  • nlText
  • status
  • confidence
  • jobDraft
  • ambiguities[]
  • extractedAt
routing-decision.schema.json
  • id
  • jobId
  • stage
  • selectedBy
  • selectedDeviceId
  • connectorId
  • hardVetoes[]
  • candidates[]
  • outcome
device.schema.json
  • id
  • name
  • type
  • adapter
  • status
  • capabilities (ref)
  • aiSignals (ref)
  • connectorId
capabilities.schema.json
  • deviceId
  • substrates[]
  • colorSpaces[]
  • finishing[]
  • maxSpeedSph
  • maxSubstrateGsm
  • minSubstrateGsm
connector.schema.json
  • id
  • name
  • tenantId
  • status
  • lastHeartbeat
  • cpuPercent
  • memoryPercent
  • activeJobs
event.schema.json
  • tenantId
  • eventType
  • source
  • payload
  • timestamp
tenant.schema.json
  • id
  • name
  • settings
  • featureFlags
  • autoApproveThreshold
  • aiRoutingEnabled
user.schema.json
  • id
  • tenantId
  • email
  • role
  • createdAt
webhook.schema.json
  • id
  • url
  • eventTypes[]
  • secret
  • retryPolicy
die-registry.schema.json
  • id
  • name
  • type
  • dimensions
  • deviceCompatibility[]

Supported Connectors

The full connector catalog — every device, DFE, RIP, and MIS platform the connector agent can dispatch to today, with the integration path each one uses.

Transport Protocols

  • IPP / IPPSInternet Printing Protocol (RFC 8010/8011), TLS via IPPS
  • LPRLine Printer Remote — RFC 1179 legacy queue protocol
  • RAW / JetDirectRaw TCP port 9100 (AppSocket)
  • Hot FolderFile-drop watched directory
  • JDF / JMFCIP4 Job Definition/Messaging Format over HTTP

Digital Press / DFE

  • EFI FieryJMF (port 8080) or IPP passthrough
  • HP IndigoSmartStream Director REST, hot folder, or JMF
  • HP SmartStream Director / Production CenterREST API (port 7182 / 7080)
  • HP PageWideNative IPP
  • Ricoh TotalFlow Print / Batch ManagerREST API (port 10010 / 10080)
  • Konica Minolta IC-308 / 310 / 418JMF (port 9200) or IPP (631)
  • Xerox FreeFlow Print ManagerJMF (port 7788)
  • Canon PRISMAsync / PRISMsyncJMF (port 9100) or IPP
  • Canon VarioPrint i-seriesPRISMAsync DFE (JDF / IPP)
  • Screen TruePressJDF via SmartClient
  • Landa Nanographic PressesJDF-based prepress integration

Prepress / RIP

  • ONYX Thrive / RIPCenterHot folder + JT sidecar, or REST (ONYX Hub)
  • Caldera Grand RIP+ / CalderaCareHot folder, or REST (v15+)
  • Harlequin RIPHot folder or JDF
  • EFI RIPHot folder

Offset Press

  • Heidelberg Prinect Integration ManagerJMF (port 7781)
  • manroland PrintNetJDF / JMF
  • KBA DCOSJDF
  • Komori KP-ConnectJDF

Wide Format

  • Roland VersaWorksHot folder
  • Mimaki RasterLinkHot folder
  • Epson Garment / SureColorHot folder

Label & Packaging

  • Zebra ZPL / ZBI printersRaw TCP (port 9100)
  • NiceLabel CloudREST
  • Loftware SpectrumREST
  • BarTenderHot folder / COM API
  • Esko Automation EngineHot folder
  • BOBST ConnectREST + OAuth 2.0 client credentials

Finishing

  • Duplo DCC SeriesJMF (port 9000)
  • Horizon SmartControllerJMF (port 8080)
  • Müller Martini ConnexJMF (port 4000)
  • KolbusJDF / JMF
  • Polar CompuCutJDF via CtrlCut
  • Highcon BeamREST

MIS / VDP

  • XMPiE uProduce / PersonalEffectREST (VDP)
  • EFI PACEREST (MIS)
  • PressWiseREST / API
  • PrintSmith VisionREST
  • TharsternREST

Generic Fallback

  • Generic REST device / MISConfigurable HTTP API
  • SNMP-only monitoringStatus polling, no job dispatch

Ready to integrate?

Full OpenAPI spec available in the API reference. Connector agent ships as a single npm package.

API Reference →Connector Guide →