Network Architecture and Data Residency

Overview

This document describes the product's network architecture, data flow, and data residency model. The product is designed to run entirely within an API publisher's own network infrastructure, providing complete control over data locality and access.

All core components—the control-plane API, admin UI, conversion runtime, background worker, and PostgreSQL database—are deployed inside your network (e.g., your VPC). The product does not expose any public endpoints by default, and all ingress is handled through internal-only listeners. This means your API traffic, including SOAP request/response payloads and archived logs, never leaves your infrastructure. Consequently, data residency is determined by the region where you deploy the product.

The only outbound traffic from the product is a minimal, metadata-only signal sent over HTTPS to the Specaria platform for licensing, telemetry, and update notifications. No API payloads, PII, or other sensitive data is ever transmitted externally.

How It Works

The product's network security model is based on four key principles: in-VPC deployment, internal-only ingress, private database connectivity, and strictly limited outbound communication.

flowchart TD
    subgraph Your Network / VPC
        subgraph " "
            direction LR
            IAP[Identity-Aware Proxy]
            ILB[Internal Load Balancer]
        end

        subgraph Product Components
            direction TB
            Admin[Product Admin Services]
            Runtime[Product Runtime]
            DB[(PostgreSQL Database<br>Private IP)]
        end

        subgraph Network Traffic
            direction LR
            Consumer[API Consumer<br>(Internal)]
            Operator[Operator/Admin]
        end

        Consumer --> ILB --> Runtime
        Operator --> ILB --> IAP --> Admin
        Runtime --> DB
        Admin --> DB
    end

    subgraph Internet
        Specaria[Specaria Platform<br>api.specaria.io]
    end

    Admin -- "Outbound HTTPS (Metadata Only)" --> Specaria
    Runtime -- "Outbound HTTPS (Metadata Only)" --> Specaria

    style DB fill:#f9f,stroke:#333,stroke-width:2px
    style Specaria fill:#ccf,stroke:#333,stroke-width:2px

In-VPC Deployment

All product components run inside your own network. This includes:

• Control-plane API
• Admin UI
• Conversion runtime
• Background worker
• PostgreSQL database

Your SOAP traffic, request/response payloads, learned examples, and the entire metadata database reside within your infrastructure. Specaria never receives, stores, or proxies your runtime traffic. This ensures that data residency is dictated by your deployment choices.

Internal-Only Ingress

By default, the product exposes no public endpoints. Both the runtime and administrative services are configured with internal-only ingress.

• Runtime Access: API consumers access the REST↔SOAP conversion endpoint through your own internal network, typically via an internal load balancer. Inbound runtime access is governed by your existing network controls.
• Operator Access: Administrators access the admin UI and API through an internal HTTPS listener fronted by an identity-aware proxy.

On Google Cloud Platform, this is implemented using Cloud Run ingress set to internal-and-cloud-load-balancing, making the raw service URL unreachable from the public internet. Because all ingress paths are internal, trusted identity headers injected by the proxy (e.g., X-Goog-Authenticated-User-*) cannot be spoofed by external actors.

Private Database Connectivity

The product's services connect to the metadata database over a private network path, not a public IP address.

• On Google Cloud, the product uses a private-IP Cloud SQL for PostgreSQL instance, which is accessed over the VPC.
• Services like the runtime and worker connect using Direct VPC egress, which avoids the need for a separate network connector.

IAM Database Authentication on Google Cloud

On GCP-native deployments, services authenticate to the database using IAM database authentication instead of static passwords. Each service uses its unique service account identity to obtain a short-lived database authentication token, which is automatically refreshed. This eliminates the need to manage a long-lived static database password.

Outbound Communication

The product's only outbound communication is to the Specaria platform (api.specaria.io) over HTTPS (TCP port 443). This traffic is strictly limited to metadata for licensing, telemetry, update notifications, and feedback.

The product never sends the following data externally:

• SOAP payloads
• Backend hostnames
• Internal IP addresses
• API consumer identifiers
• Any personally identifiable information (PII)

Your VPC firewall must be configured to permit outbound TCP 443 traffic from the product's subnet to the endpoints listed in the egress allow-list.

Configuration Reference

The following environment variable is used for database authentication in specific environments.

Summary of Network Properties

Troubleshooting

Failed Connection to Specaria Platform

• Condition: The product fails to perform licensing checks, receive update notifications, or send heartbeat telemetry.
• Cause: This is typically caused by firewall rules that block outbound HTTPS traffic from the product's subnet.
• Resolution: Ensure that your firewall permits outbound traffic on TCP port 443 to api.specaria.io and other required domains as specified in the egress allow-list.

See Also

• Security Overview
• Authentication
• Licensing Egress Allow-list

All SOAP-to-REST docs