> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomadicml.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NomadicML on GCP

> Architecture, read and write paths, and private connectivity over Private Service Connect.

# NomadicML on GCP

This page describes how the video analysis platform is deployed in Google Cloud, how data moves through it on the read and write paths, and how client applications reach it privately over Private Service Connect.

<Note>
  Looking to run the whole stack inside your own project instead? See [Self-Hosted VPC Setup](/getting-started/vpc-setup), which is available today for both GCP and AWS. For the AWS equivalent of this page, see [NomadicML on AWS](/deployment/aws).
</Note>

## General Architecture

The platform runs inside a NomadicML-managed VPC network. Client applications never reach it over the public internet. They create a Private Service Connect endpoint in their own VPC, which resolves to an internal IP address and connects to a service attachment we publish. Everything behind that service attachment (load balancer, application tier, storage and inference) runs in private subnets with no external IP address.

```mermaid theme={null}
flowchart TB
    subgraph client["Client VPC network"]
        A["Client applications"]
        B["PSC endpoint<br/>forwarding rule, internal IP"]
        A --> B
    end

    subgraph nml["NomadicML VPC network"]
        C["Service attachment<br/>plus PSC NAT subnet"]
        D["Internal load balancer<br/>no external IP"]
        E["API service"]
        F["Analysis workers"]
        G[("Cloud Storage<br/>video and artifacts")]
        H[("Firestore<br/>metadata")]
        I[("Memorystore Redis<br/>progress streams")]
        J["Vertex AI<br/>model inference"]
    end

    B -->|"Private Service Connect"| C
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    F --> G
    F --> H
    F --> I
    F --> J
```

### Key Components

<CardGroup cols={2}>
  <Card title="Service attachment" icon="shield-halved">
    The published service a client connects to. It carries a consumer accept list naming which projects may connect, and a dedicated NAT subnet that translates consumer traffic inside our network.
  </Card>

  <Card title="Internal load balancer" icon="scale-balanced">
    No external IP. Fronts the application tier and is the backend the service attachment targets.
  </Card>

  <Card title="Application tier" icon="server">
    Compute Engine backends in managed instance groups. The API service handles authentication, upload and result retrieval. Analysis workers claim queued jobs on a lease and run the analysis out of band.
  </Card>

  <Card title="Data services" icon="database">
    Cloud Storage for video and derived artifacts, Firestore for job and analysis metadata, Memorystore for progress streams, Vertex AI for model inference. Reached over private paths, so no traffic traverses the public internet.
  </Card>
</CardGroup>

## Read Path

A client asks for job status, analysis results, or the media behind them. The request enters through the PSC endpoint and is served from the two data stores inside the VPC network.

```mermaid theme={null}
flowchart LR
    subgraph client["Client VPC network"]
        A["Client application<br/>status, results, media"]
    end

    subgraph nml["NomadicML VPC network"]
        B["Service attachment"]
        C["API service<br/>authenticates API key"]
        D[("Firestore")]
        E[("Cloud Storage")]
    end

    A <-->|"Private Service Connect"| B
    B <--> C
    C <-->|"analysis document"| D
    C <-->|"video and artifacts"| E
```

### Read Path Flow

1. **Client application** sends the request to the PSC endpoint in its own subnet, reached by an internal IP address and the DNS name created in its Cloud DNS zone.
2. **Service attachment** accepts the connection from a project on the accept list and forwards it to the internal load balancer.
3. **API service** authenticates the API key and resolves what was asked for: job status, an analysis document, or media.
4. **Firestore and Cloud Storage** return the analysis document and the video or derived artifacts behind it. Results travel back on the connection the client already opened.

## Write Path

Upload and analysis are decoupled, so a long-running analysis never holds a client connection open.

```mermaid theme={null}
flowchart LR
    subgraph client["Client VPC network"]
        A["Client application"]
    end

    subgraph nml["NomadicML VPC network"]
        B["API service"]
        C["Analysis workers"]
        D[("Cloud Storage")]
        E[("Firestore")]
        F["Vertex AI"]
        G["Memorystore Redis<br/>progress stream"]
    end

    A -->|"video upload via PSC"| B
    B -->|"video, sync write"| D
    B -->|"queued job"| C
    C -->|"artifacts"| D
    C -->|"results"| E
    C <-->|"frames and prompts"| F
    C -->|"progress events"| G
    G -->|"SSE progress"| A
```

### Write Path Flow

The API service writes video to Cloud Storage synchronously and records a job document in Firestore, then returns. The upload is complete at that point. Analysis workers claim the queued job on a lease, marking it in progress so no two workers take the same job, and call Vertex AI for inference. As they run they publish progress events to a Memorystore stream, which the API service relays to the client as server-sent events. Finished results are written back to Firestore and derived artifacts to Cloud Storage, where the read path picks them up.

## Private Connectivity

Private Service Connect is two resources, one in each project. NomadicML publishes the service attachment; the client creates an endpoint in their own VPC network. Traffic between them stays on Google's network.

* **The connection is one-way.** The client initiates. NomadicML cannot reach back into the client network, so exposure is limited to the single published service rather than a route between two networks.
* **Consumption is controlled by an accept list.** The service attachment names which consumer projects may connect. With manual acceptance, each connection request is approved individually.
* **No address-space coordination.** A dedicated NAT subnet in our network translates consumer traffic, so the two networks are IP independent and overlapping ranges are irrelevant.
* **DNS is created for you.** Where we publish a DNS domain with the attachment, the endpoint's DNS records are created automatically in your Cloud DNS zone, so your SDK resolves it without configuration changes.
* **Nothing needs an external IP.** Your side needs no Cloud NAT or external address for this path, and our load balancer is internal.

The equivalent primitive on AWS is [PrivateLink](/deployment/aws) and on Azure is Private Link Service. All three follow the same publish-and-consume shape.

<Warning>
  The managed platform runs in Google Cloud today. What is still in development is publishing it as a Private Service Connect service attachment, so the private connectivity path described above is not yet available for self-service. Talk to us about timelines. The [self-hosted VPC deployment](/getting-started/vpc-setup) is available now.
</Warning>

## Deployment Models

Three options, differing in whose project holds the application and whose holds the data.

<CardGroup cols={3}>
  <Card title="Fully managed" icon="cloud">
    NomadicML runs both the application and the data services in our GCP project. Clients connect over Private Service Connect. Lowest operational burden.
  </Card>

  <Card title="In your VPC" icon="lock">
    The entire stack deploys into your GCP project, with Compute Engine backends, private subnets, and no public ingress. Video never leaves your project and we hold no credentials into it.
  </Card>

  <Card title="Hybrid" icon="shuffle">
    We run the application; you supply the Cloud Storage buckets. Access is granted by workload identity federation rather than stored service account keys.
  </Card>
</CardGroup>

|                             | Fully managed           | In your VPC               | Hybrid                      |
| --------------------------- | ----------------------- | ------------------------- | --------------------------- |
| **Application runs in**     | NomadicML project       | Your project              | NomadicML project           |
| **Video at rest in**        | NomadicML project       | Your project              | Your project                |
| **Metadata at rest in**     | NomadicML project       | Your project              | NomadicML project           |
| **Reached over**            | Private Service Connect | Internal load balancer    | Private Service Connect     |
| **Credentials we hold**     | None                    | None                      | Federated identity, no keys |
| **Your operational burden** | None                    | Project, quotas, upgrades | Buckets and IAM bindings    |
| **Available today**         | In development          | Yes                       | In development              |

Setup steps for the in-VPC model are covered in [Self-Hosted VPC Setup](/getting-started/vpc-setup).

## What You Provide

For a Private Service Connect connection to the managed service, the client side needs very little.

| Item                                     | Detail                                                                                                                                   |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Project ID and region**                | The consumer project, and the region your endpoint will live in. Tell us the region and we will publish the attachment there.            |
| **Consumer project for the accept list** | The project allowed to connect to the service attachment. We add it before you create the endpoint.                                      |
| **PSC endpoint**                         | A forwarding rule in your VPC network targeting the service attachment we provide, with an internal IP address from one of your subnets. |
| **Subnet and firewall rules**            | A subnet in the target region for the endpoint IP, and egress rules allowing your application to reach it on TCP 443.                    |
| **Cloud DNS zone**                       | Optional. If you prefer your own naming, we can publish without a DNS domain and you point a private zone at the endpoint IP yourself.   |

<Note>
  Deployments are configured per customer. Contact your NomadicML representative with your GCP project ID, target region, and preferred deployment model, and we will publish the service attachment and share its URI.
</Note>