Documentation / Getting Started

Architecture

How Nexus by Stingray runs entirely inside your own Azure subscription — the per-tenant Azure footprint, the request and data flow, the control-plane boundary, and the execution substrate — and why Stingray never sits in your data path.

Nexus by Stingray deploys as an Azure Marketplace managed application directly into your own Azure subscription. This page is for architects, security reviewers, and operators who need to understand exactly where Nexus runs, what each component does, how a request flows from a caller to a source and back, and why the tenant-isolation model keeps your data — and your credentials — inside your tenant.

The core principle: single-tenant, tenant-owned

Nexus is single-tenant by design. Every component that touches your data — the application server, its state database, your secrets, your file/version storage, and your network egress controls — runs inside your Azure subscription, under your managed identity and your network policy. Stingray operates a small, shared control plane used only for software updates, the connector catalog, and licensing. The control plane never receives your business data, your query results, or your source credentials.

The practical consequence for a security review: the vendor is not a data processor in the traditional sense. There is no Stingray-hosted data plane where your records could be logged, breached, or compelled. What Stingray ships is signed software and a license; what runs it is your Azure tenant.

Per-tenant Azure footprint

When you deploy the managed application, it provisions a self-contained footprint in your subscription:

Resource	Azure service	Role
Nexus server	Azure Container Apps	The application: REST API, UQL engine, pipeline runtime, reports, RBAC, and the embedded MCP server. Runs under a managed identity; no standing passwords.
State database	Azure Database for PostgreSQL Flexible Server	Stores reports, pipelines, configuration, RBAC, run queue, and run history. Reached with managed-identity tokens — password auth is disabled — over a private endpoint.
Internal workspace DB	Azure Database for PostgreSQL	A separate per-tenant scratch database with its own managed identity, structurally isolated from the operational tables (see below).
Secrets	Azure Key Vault	Holds every connection credential and the request-signing keys. Accessed by the server's managed identity; Stingray has no path to it.
Network	VNet + NSG	An egress allowlist (application-layer) plus network-layer NSG rules bound the server's outbound reach; a private endpoint keeps database traffic off the public internet.
File & version storage	Azure Files	Pipeline working files and the per-tenant git repository that version-controls pipelines, reports, Sites, and skills.
Identity	Microsoft Entra ID	Users sign in with OAuth2 + PKCE; automation uses scoped app tokens or API keys. The server's managed identity authenticates to Postgres, Key Vault, and storage.

Two isolation properties matter to reviewers. First, there are no database passwords anywhere in this footprint — Postgres and Key Vault are reached with managed-identity tokens, so there is no long-lived credential to leak. Second, the internal workspace runs on a separate database with a separate managed identity from the operational tables. UQL executed against the workspace literally cannot reach Nexus's own operational tables — the isolation is structural (separate DB + separate MI), not a query filter. See Internal Workspace.

Request and data flow

A caller reaches Nexus, is authenticated at the edge, authorized by RBAC, and then Nexus executes against your source using credentials it resolves from your Key Vault. Results return directly to the caller. The only traffic to Stingray is operational metadata.

   Users (browser / Desktop / Excel add-in)          AI agents (Claude, Copilot, ...)
        │  OAuth2 PKCE                                     │  identity-bound MCP session
        │  app tokens / API keys (automation)              │
        ▼                                                  ▼
 ┌───────────────────────────────────────────────────────────────────────┐
 │   NEXUS SERVER   (Azure Container Apps — your subscription)            │
 │   REST API · UQL engine · pipeline runtime · reports · RBAC · MCP     │
 └───────────────────────────────────────────────────────────────────────┘
        │ managed identity              │ bridge (creds from your Key Vault)
        │ (token auth, no passwords)    │ SSRF-checked, egress-allowlisted
        ├──────────────► PostgreSQL Flexible Server  (reports, pipelines, run state)
        ├──────────────► Key Vault                   (secrets + signing keys)
        ├──────────────► Azure Files                 (pipeline files + git repo)
        ├──────────────► Workspace Postgres (sep. MI) (staging / scratch)
        │
        └──────────────► YOUR DATA SOURCES  (SQL Server, NetSuite, Monday, QBO,
                                             any REST via generic HTTP, any DB via JDBC)

        ┅┅┅ HTTPS, metadata only ┅┅┅►  STINGRAY CONTROL PLANE
                                       (update checks · connector catalog · license leases)
                                       never your data, results, or credentials

Walking one request end to end:

Authenticate. A user request carries an Entra OAuth2 + PKCE token; an automation request carries a scoped app token or API key; an agent request arrives over an identity-bound MCP session. The server validates it at the edge.
Authorize. RBAC checks the caller's roles and per-resource grants for the exact action (for example, run this report, write to this bridge). Denials fail closed.
Resolve credentials. For any source access, the server resolves the source credential from Key Vault for the authenticated identity only, honoring the artifact's bridge_mode (service vs. user credentials). There is no request parameter to borrow another identity's secrets.
Execute. The UQL engine or a pipeline runs the work — pushing filters and aggregation down to the source where the adapter supports it, and otherwise finishing in-engine (see UQL Introduction). Outbound HTTP is SSRF-checked and egress-allowlisted.
Return and record. Results go directly back to the caller. Run history, structured logs, and — on failure — the complete traceback are persisted per run, with before/after audit snapshots. See Audit & Telemetry.

The control-plane boundary

The shared control plane (Azure Functions, operated by Stingray) exists so you don't have to hand-manage software supply chain and licensing. It is deliberately narrow.

What the control plane does:

Answers update checks and serves signed container-image and connector-bundle references. You choose when to apply an update; see Updates.
Serves the connector catalog — the signed adapter bundles and their manifests. Bundles are dual-signed (ES256) by two separate Key Vaults and verified fail-closed before your server loads them.
Issues short-lived, signed license leases that your server verifies locally against a baked-in public key, so licensing works without phoning home on every request.
Optionally receives aggregate telemetry, which you can disable.

What the control plane does not do: it never holds or sees your business data, your query results, your source credentials, your Key Vault contents, or your run logs. It is not in the request path for any data operation. Server-to-control-plane calls are HMAC-authenticated and carry metadata only. For government-cloud tenants, the same managed-application contract deploys into Azure Government, with the server pulling its image cross-cloud from the commercial registry — a path proven on the live Delva (GCC-High) tenant.

Bridges and credential isolation

A bridge is a named connection to a source — for example (mssql, "production"). A bridge exists because its secrets exist in your Key Vault; credentials are never inlined into a report or pipeline. Bridges have two scopes:

Service bridges — owned by the tenant, managed by admins, usable by anyone whose RBAC permits the report or pipeline that uses them.
User bridges — owned by one user and usable only by that user, so a person can supply their own keys without an admin ever seeing them.

Credential resolution is enforced in a single server-side function. There is no request parameter, anywhere, by which a caller can name whose credentials to use — the resolver only ever returns the secrets of the authenticated identity, and it fails closed when no eligible identity is present. A report or pipeline declares a bridge_mode (service_only, user_only, or user_then_service) that governs which scope is eligible. See Connections & Bridges.

Adapters, connectors, and pipelines

Adapters are the signed connector packages that integrate a source. Each implements a typed read / write / discover contract and declares its capabilities (which operators and pushdown it supports) so the UQL engine knows what to push down versus finish in-engine. Pure configuration — endpoints, auth type, column maps — lives in JSON alongside the code. Beyond native adapters, a generic HTTP/REST connector and a generic JDBC connector let you reach arbitrary REST APIs and JDBC databases without a native adapter. See the Connectors Overview.

Pipelines are Python modules. Each exports a single async def run(ctx) and uses typed handles on the context object:

async def run(ctx):
    rows = await ctx.adapters.netsuite.read(...)
    await ctx.adapters.monday.write(rows, op="upsert")
    ctx.logger.info("synced %d records", len(rows))

ctx exposes ctx.adapters.<name>, ctx.secrets, ctx.http (allowlisted, SSRF-checked), ctx.workspace, ctx.variables, ctx.files, ctx.logger, and ctx.nexus for child runs. Pipeline code is compiled under a sandbox with an import allowlist: exec/eval, file I/O, and unrestricted network are stripped at the AST level before the module runs. See the Pipeline SDK.

Execution substrate

Automation runs on a durable, governed substrate rather than best-effort background threads:

Durable run queue — runs are claimed from a Postgres run_queue using FOR UPDATE SKIP LOCKED with LISTEN/NOTIFY dispatch; run state is persisted in pipeline_runs, so a replica restart does not lose work.
Cron scheduling with exactly-once firing — schedules fire on wall-clock-aligned ticks, and a compare-and-swap claim plus cross-replica Postgres advisory locks ensure a given tick fires once even across multiple replicas. (Exactly-once applies to firing; queue dispatch itself is at-least-once at the claim boundary, and there is no end-to-end exactly-once execution.)
Per-run wall-clock timeouts — a default of 3600s with a hard 6-hour ceiling, overridable per pipeline, enforced by the worker wrapper. Defense-in-depth pipeline constraints cap rows read/created/updated/deleted.
Concurrency controls — a global semaphore queue (default 5 concurrent), a worker cap, and a per-tenant rate cap; a bridge connection governor caps per-replica database connections and reaps orphans. These are queues that add delay under load, not rejecting limiters.

The execution model — run lifecycle, cancellation semantics (best-effort, not guaranteed termination), what retry/idempotency behavior does and does not exist, scheduling guarantees, and backup/disaster-recovery patterns — is documented in depth in Reliability & Operations.

Updates, licensing, and authentication

Updates ship as new container images referenced through the control plane; you control when to apply them. See Updates.
Licensing uses short-lived signed leases verified locally against a baked-in public key — no per-request call home.
Authentication is OAuth2 + PKCE for users and app tokens or API keys for automation; server-to-control-plane calls use HMAC. Identity is Microsoft Entra ID throughout. See Identity.

The result is a platform you run, not a SaaS that runs your data: Stingray ships and licenses the software and operates a metadata-only control plane, while your data, secrets, and execution stay inside your Azure subscription.