> ## 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 AWS

> Architecture, read and write paths, and private connectivity over AWS PrivateLink.

# NomadicML on AWS

This page describes how the video analysis platform is deployed in AWS, how data moves through it on the read and write paths, and how client applications reach it privately over AWS PrivateLink.

<Note>
  Looking to run the whole stack inside your own account instead? See [Self-Hosted VPC Setup](/getting-started/vpc-setup), which is available today for both AWS and GCP.
</Note>

## General Architecture

The platform runs inside a NomadicML-managed VPC. Client applications never reach it over the public internet. They connect through an interface VPC endpoint in their own VPC, which AWS PrivateLink joins to a VPC endpoint service we publish. Everything behind that endpoint service (load balancer, application tier, storage and inference) runs in private subnets with no public IP address.

```mermaid theme={null}
flowchart TB
    subgraph client["Client VPC"]
        A["Client applications"]
    end

    subgraph nml["NomadicML VPC"]
        B["VPC endpoint service"]
        C["Network load balancer<br/>internal, no public IP"]
        D["API service"]
        E["Analysis workers"]
        F[("Amazon S3<br/>video and artifacts")]
        G[("DocumentDB<br/>metadata")]
        H[("ElastiCache<br/>progress streams")]
        I["Amazon Bedrock<br/>model inference"]
    end

    A -->|"AWS PrivateLink"| B
    B --> C
    C --> D
    D --> E
    D --> F
    D --> G
    E --> F
    E --> G
    E --> H
    E --> I
```

### Key Components

<CardGroup cols={2}>
  <Card title="VPC endpoint service" icon="shield-halved">
    The published service a client consumes. It names exactly which AWS principals may connect, and each connection request is accepted individually.
  </Card>

  <Card title="Network load balancer" icon="scale-balanced">
    Internal, no public IP. Backs the endpoint service and distributes traffic across the application tier.
  </Card>

  <Card title="Application tier" icon="server">
    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">
    Amazon S3 for video and derived artifacts, DocumentDB for job and analysis metadata, ElastiCache for progress streams, Amazon Bedrock for model inference. All are reached through VPC endpoints.
  </Card>
</CardGroup>

## Read Path

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

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

    subgraph nml["NomadicML VPC"]
        B["Endpoint service"]
        C["API service<br/>authenticates API key"]
        D[("DocumentDB")]
        E[("Amazon S3")]
    end

    A <-->|"AWS PrivateLink"| B
    B <--> C
    C <-->|"analysis document"| D
    C <-->|"video and artifacts"| E
```

### Read Path Flow

1. **Client application** sends the request through AWS PrivateLink, resolving a private DNS name to the interface endpoint in its own subnet.
2. **Endpoint service** accepts the connection from an allow-listed principal and passes 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. **DocumentDB and Amazon S3** 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"]
        A["Client application"]
    end

    subgraph nml["NomadicML VPC"]
        B["API service"]
        C["Analysis workers"]
        D[("Amazon S3")]
        E[("DocumentDB")]
        F["Amazon Bedrock"]
        G["ElastiCache<br/>progress stream"]
    end

    A -->|"video upload via PrivateLink"| 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 Amazon S3 synchronously and records a job document in DocumentDB, 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 Amazon Bedrock for inference. As they run they publish progress events to an ElastiCache stream, which the API service relays to the client as server-sent events. Finished results are written back to DocumentDB and derived artifacts to S3, where the read path picks them up.

## Private Connectivity

AWS PrivateLink is two resources, one in each account. NomadicML publishes the VPC endpoint service; the client creates an interface VPC endpoint in their own VPC. Traffic between them rides the AWS backbone.

* **The connection is one-way.** The client initiates. NomadicML cannot reach back into the client VPC, so exposure is limited to the single published service rather than a route between two networks.
* **Consumption is allow-listed.** The endpoint service names which AWS principals may create an endpoint against it, and each connection request is accepted individually.
* **No address-space coordination.** Traffic terminates on an interface in the client's own subnet, so overlapping CIDR ranges are irrelevant.
* **Nothing needs a public IP.** The client side needs no internet gateway or NAT for this path, and the load balancer is internal.

The equivalent primitive on GCP is Private Service Connect and on Azure is Private Link Service. All three follow the same publish-and-consume shape.

<Warning>
  The PrivateLink endpoint service for the managed offering is in development. The managed platform currently runs in GCP, so it requires an AWS-hosted deployment. Talk to us about timelines before planning against it. The [self-hosted VPC deployment](/getting-started/vpc-setup) is available today.
</Warning>

## Deployment Models

Three options, differing in whose account 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 AWS account. Clients connect over PrivateLink. Lowest operational burden.
  </Card>

  <Card title="In your VPC" icon="lock">
    The entire stack deploys into your AWS account, in a VPC with no internet gateway and no NAT. Video never leaves your account and we hold no credentials into it.
  </Card>

  <Card title="Hybrid" icon="shuffle">
    We run the application; you supply the S3 buckets. Access is granted by a cross-account IAM role rather than stored credentials.
  </Card>
</CardGroup>

|                             | Fully managed     | In your VPC               | Hybrid                  |
| --------------------------- | ----------------- | ------------------------- | ----------------------- |
| **Application runs in**     | NomadicML account | Your account              | NomadicML account       |
| **Video at rest in**        | NomadicML account | Your account              | Your account            |
| **Metadata at rest in**     | NomadicML account | Your account              | NomadicML account       |
| **Reached over**            | PrivateLink       | Internal load balancer    | PrivateLink             |
| **Credentials we hold**     | None              | None                      | Assumed IAM role        |
| **Your operational burden** | None              | Account, quotas, upgrades | S3 buckets and IAM role |
| **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 PrivateLink connection to the managed service, the client side needs very little.

| Item                           | Detail                                                                                                                              |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **AWS account and region**     | Must be in the same region as the endpoint service. Tell us the region and we will publish there.                                   |
| **AWS principal ARN**          | The account or role that will create the interface endpoint. We add it to the endpoint service allow list.                          |
| **Interface VPC endpoint**     | Created in your VPC against the service name we provide. Enable private DNS so your SDK resolves it without configuration changes.  |
| **Subnets and security group** | Two or more private subnets across availability zones, and a security group allowing TCP 443 from your application.                 |
| **Object storage endpoint**    | Recommended. Where results reference media by presigned URL, an S3 interface endpoint keeps that fetch off the public internet too. |

<Note>
  Deployments are configured per customer. Contact your NomadicML representative with your AWS account ID, target region, and preferred deployment model, and we will provision the endpoint service and share the service name.
</Note>