AWS-Reference Architecture

What this page covers

Unique AI supports multiple network topologies and deployment profiles. The platform can deploy behind internal-only access (Direct Connect / Transit Gateway), internet-facing access (CloudFront), or a dual model combining both. Data services can run as PaaS (managed by the cloud provider) or cloud-native (self-hosted on Kubernetes). Monitoring and artifact management follow the same pattern — AWS managed services or bring-your-own tooling.

This page documents the Unique AI AWS reference architecture: hub-and-spoke accounts, internal access via Direct Connect and Transit Gateway, PaaS data services (Aurora, ElastiCache, S3), AWS-managed monitoring (CloudWatch, Managed Prometheus, Managed Grafana), AWS-managed artifact services (ECR), and Amazon Bedrock for model inference. The platform supports three account topologies and three network access models that can be combined to match different enterprise architectures — these are summarised in Adaptive Architecture at the end of this page.

The page is structured around five views that progressively increase in detail. Start with the high-level architecture for the full picture, then drill into whichever area is relevant to your environment.

High-Level Architecture

The Unique AI AWS reference architecture is based on the AWS Cloud Adoption Framework, the Well-Architected Framework, and each service's prescriptive guidance, which should map to your organisation's AWS landing zone.

The flexibility and configurability of Unique AI ensures that any discrepancies between these frameworks and your environment can be resolved with deployment and configuration adaptation.

The architecture follows a hub-and-spoke account model with two AWS accounts. This is the standard AWS landing zone layout — separating connectivity from workload accounts enforces centralised network ingress and egress, separation of concerns, and least-privilege principles.

Connectivity Account is the network hub. All traffic entering or leaving the AWS environment passes through this account. It provides centralised DNS via Route 53, internet egress through NAT Gateway and Network Firewall, inter-account routing via Transit Gateway, and private connectivity to the customer's on-premises network via Direct Connect. The Workload Account has no Internet Gateway and no NAT Gateways — all outbound traffic is forced through the Connectivity Account's inspection chain.

Workload Account hosts the entire Unique platform. Inside a single VPC with five subnet tiers, an EKS cluster runs all application workloads. PaaS data services — Aurora PostgreSQL, ElastiCache Redis, and S3 — sit outside the VPC but inside the account, accessed exclusively through VPC Endpoints. No traffic to AWS services crosses the public internet.

AWS Organisation spans both accounts with your organisation's governance and landing zone services. The ones shown — Control Tower, CloudTrail, AWS Config, IAM Identity Center, and optionally GuardDuty and Security Hub — are those that directly bear on the Unique AI workload account and solution.

Network paths

There are three distinct network paths:

Internal path carries all user traffic and on-premises data source access. Users on the customer's corporate network reach the platform via Direct Connect through Transit Gateway into the VPC. Traffic terminates TLS at an internal Application Load Balancer and is routed to Kong API Gateway pods in EKS. On-premises data sources accessed via MCP connectors use the same private path. No internet is involved.

Internet egress path handles all outbound internet traffic. This includes ArgoCD pulling charts from GitHub, MCP connectors calling SaaS APIs, Zitadel federating with the customer's identity provider, and ECR pull-through cache misses. All outbound traffic exits through Transit Gateway to the Connectivity Account, where Network Firewall inspects it before NAT Gateway provides the internet breakout.

VPC Endpoint path keeps all traffic to AWS managed services — S3, Aurora, Bedrock, KMS, ECR, CloudWatch, and others — on the AWS private network. This is the highest-volume path and carries zero internet exposure. No resources in the Workload Account have public endpoints or public IP addresses — all AWS service access is routed through VPC Endpoints.

EKS workload groups

The Unique AI workloads on the EKS cluster can be grouped into the following broad functional and capability groups:

AWS Service Inventory

AWS services deployed to the Workload Account by Unique's infrastructure-as-code.

Cross-Account Dependencies

Several services in the Workload Account depend on resources owned by the Connectivity Account. These dependencies follow the AWS multi-account strategy prescribed by AWS Organizations and Control Tower:

• Resource sharing over cross-account IAM — dependencies are resolved through AWS Resource Access Manager (RAM) and DNS delegation, not IAM trust relationships or credential sharing between accounts

• Account boundary as security boundary — each account operates with its own IAM principals. No account assumes roles into another for runtime operations

• Centralised network, decentralised workloads — the Connectivity Account owns the network perimeter (ingress, egress, inspection), while the Workload Account owns everything inside its VPC. This aligns with the AWS Security Reference Architecture (SRA) network account pattern

The Connectivity Account resources — Transit Gateway, Network Firewall, NAT Gateways, Direct Connect — are prerequisites managed by the client's platform team. Unique's infrastructure-as-code consumes these as inputs (TGW ID, DNS delegation) but does not provision or modify them.

Pod Identity and IAM Policies

Every workload that accesses an AWS service receives its own Pod Identity association — a dedicated IAM role bound to a single Kubernetes ServiceAccount. There are no shared roles, no long-lived credentials, and no legacy IRSA bindings. The design follows three principles:

• Least-privilege per workload — each IAM policy grants only the actions and resources that specific workload requires. No role is reused across workloads.

• No static credentials — all AWS access uses short-lived tokens injected by the Pod Identity agent. No access keys are stored in Secrets Manager or environment variables for AWS service access.

• Resource-scoped policies — policies target specific ARNs (buckets, KMS keys, inference profiles) rather than wildcards wherever the AWS service supports resource-level permissions.

There are 14 Pod Identity associations in the reference architecture.

AI Services

Platform Services

Five of the Platform associations (prometheus, grafana-pod, loki, tempo) are conditional — they are only created when the observability infrastructure outputs are present.
Two associations intentionally carry broader scope: external-secrets (delivers secrets cluster-wide, so it reads all Secrets Manager values — access is CloudTrail-logged and can be narrowed to a naming prefix on request) and aws-load-balancer-controller (AWS's published policy, constrained by IAM conditions).

VPC and Network Layout

The VPC design follows the AWS VPC security best practices and the Well-Architected Framework networking pillar:

• Defence in depth — five subnet tiers with distinct isolation levels, security groups enforcing least-privilege at layer 4, and no default route from the isolated data tier

• No public exposure — no Internet Gateway, no public subnets, no public IP addresses in the Workload Account. All external connectivity routes through the Connectivity Account's inspection chain

• Private-first AWS access — all AWS service traffic stays on the AWS network via VPC Endpoints. Standard SDK calls resolve to private endpoints automatically via private DNS

Subnet tiers

The VPC uses a five-tier subnet model distributed across three Availability Zones. Each tier has a distinct isolation level and routing profile. There are no public subnets and no Internet Gateway in the Workload Account.

Cluster subnets are separated from Node subnets per AWS EKS best practices — during cluster upgrades, AWS provisions additional ENIs that would compete for IP space with worker nodes. The Isolated tier has no outbound route, ensuring Aurora and ElastiCache are network-isolated from anything outside the VPC.

Security groups

Security groups enforce layer-4 access control between components. Each security group is scoped to a specific function and follows a deny-all-except pattern.

DNS and Ingress

The platform domain resolves privately within the VPC via a Route 53 Private Hosted Zone. The VPC has DNS resolution and DNS hostnames enabled, and the hosted zone is associated at the VPC level. All internal service endpoints resolve to private IP addresses — there is no public DNS exposure for any workload account resource.

TLS certificates are managed by AWS Certificate Manager, which handles issuance, renewal, and rotation automatically via DNS validation against the delegated Route 53 zone. This eliminates outbound ACME requests to external certificate authorities, keeping the TLS lifecycle entirely within the AWS trust boundary and removing a dependency on internet egress for certificate renewal.

Inbound traffic from users on the customer's corporate network enters through Direct Connect and Transit Gateway into the VPC, where it terminates TLS at the internal Application Load Balancer using the ACM-managed certificate. The ALB forwards traffic to Kong API Gateway pods running in EKS, which handles API routing, rate limiting, and authentication forwarding to backend services. Kong is the single entry point for all application traffic — no service is directly exposed to the load balancer.

VPC Endpoints

All AWS service access from the Workload Account uses VPC Endpoints — 19 in total. Interface endpoints place ENIs in the Node subnets with a shared security group allowing HTTPS from the VPC CIDR. S3 uses a Gateway endpoint attached to all route tables. Private DNS is enabled on all Interface endpoints so that standard AWS SDK calls resolve to the private endpoint automatically.

Connectivity Account dependencies

The VPC does not operate in isolation — it depends on the Connectivity Account for all external connectivity:

Network Firewall egress rules

All outbound internet traffic from the Workload Account passes through the Connectivity Account's Network Firewall. The following destinations must be allowed for the platform to operate:

All rules are outbound HTTPS (443) only. No inbound internet rules are required — inbound user traffic arrives via Direct Connect and Transit Gateway, not from the internet. Customer-specific SaaS domains are added during the Foundation phase based on the data integration scope.

Data and Integration

The platform has seven external integration boundaries. Each has a distinct direction, authentication model, and network path.

MCP Hub and Connectors

The MCP Hub is a gateway that aggregates tools from multiple downstream MCP connectors into a single OAuth-protected endpoint. External MCP clients — such as Claude Desktop or custom integrations — connect to the Hub rather than to individual connectors. The Hub brokers authentication via Zitadel (OAuth2 with PKCE), namespaces tools by connector, and enforces per-virtual-server access control. It runs as its own deployment, routed through Kong.

Downstream connectors run as individual pods, each integrating with a specific data source (SaaS API or on-premises system). Connectors authenticate to their target systems using credentials provided during the Foundation phase. Data flow is synchronous: tool calls route through the Hub to the appropriate connector, which fetches from the target API and returns the result. Document connectors additionally push content into the ingestion pipeline.

SharePoint and Document Connectors

For the purpose of explaining the connectors the SharePoint Connector is used as a demonstrative example:

SharePoint integration combines scheduled sync with real-time change notifications. A scheduled job polls SharePoint via the Microsoft Graph API and uses change detection to re-ingest only modified or new content. An inbound webhook listener receives real-time notifications from Microsoft Graph, triggering incremental sync for affected items. Both paths feed into the ingestion pipeline, which extracts text, generates embeddings, and stores results in the vector database. SharePoint access control lists are mapped to platform scopes, preserving document-level permissions.

The customer provides an Azure AD app registration with the required Graph API permissions, the tenant ID, and the SharePoint site IDs to sync.

Zitadel Identity Federation

Zitadel is the platform's identity provider, federating with the customer's IdP via SAML or OIDC. Login traffic is browser-mediated — redirects flow between the user's browser, Zitadel, and the customer IdP without traversing the platform network. Zitadel makes pod-to-IdP calls only for token validation and user info retrieval, exiting via TGW internet egress.

User provisioning follows a SCIM-first model: the SCIM connector pre-creates users, and Zitadel links them on first login. Group claims from the IdP drive scope-based access control.

The customer registers Unique as an application in their IdP, provides federation metadata, maps a groups claim, and optionally configures a SCIM client pointing to the Zitadel SCIM endpoint.

LiteLLM (LLM Proxy)

LiteLLM is the platform's LLM gateway, routing all inference and embedding requests to the configured provider — Amazon Bedrock, Azure OpenAI, or a self-hosted vLLM instance. It connects to providers via VPC Endpoint, keeping model traffic on private network paths with no internet exposure.

Authentication is provider-dependent: Bedrock uses Pod Identity (no stored credentials), while Azure OpenAI and other providers use OIDC or API key credentials managed through Secrets Manager. LiteLLM abstracts provider differences so the application layer uses a single interface regardless of the backend.

The customer provides model access grants or endpoint details during the Foundation phase. Provider selection is configuration-driven and can be changed without application changes.

Ingestion Pipeline (Textract)

The ingestion pipeline processes uploaded and synced documents through text extraction, chunking, and embedding generation. AWS Textract handles text extraction from scanned documents, PDFs, and images. Ingestion workers connect to Textract via VPC Endpoint, keeping all document processing on the private network.

Pod Identity provides authentication — two IAM role associations cover the document processor and the ingestion worker, scoped to Textract, the S3 data bucket, and Bedrock inference for embedding generation. Extracted and chunked text flows into the Qdrant vector store for retrieval.

No customer configuration is required for Textract — it is consumed as a managed AWS service within the deployment region.

Public API and Unique SDK

The platform exposes a REST API under the same Kong ingress as the web UI. API consumers authenticate via JWT bearer token (issued by Zitadel) or API key. Tokens are scoped by type (user, service, or integration), and multi-tenancy is enforced via a company ID header. Rate limiting applies at the Kong layer.

TypeScript and Python SDKs provide programmatic access. The API supports capabilities beyond the web UI including file upload with ingestion triggers and OAuth2 token exchange for third-party integrations.

Apps (Webhooks)

The platform delivers outbound event notifications to customer-provided HTTPS endpoints. Payloads are signed with HMAC-SHA256, and verification helpers are included in the SDKs. Delivery uses exponential backoff retry for resilience.

The network path depends on the endpoint address — public endpoints route through TGW internet egress, while internal endpoints route via Direct Connect. The customer provides an endpoint URL and a shared secret; subscriptions are managed via the API.

Availability, Capacity and Costs

The sizing and availability model follows AWS Well-Architected reliability and cost optimisation pillars:

• Multi-AZ by default — all stateful services deploy across Availability Zones with automatic failover. Single-AZ is available as a cost optimisation lever but removes resilience guarantees.

• Right-size during Foundation — the reference baseline provides a starting point. Production sizing is adjusted based on user count, document volume, and query concurrency during the Foundation phase.

• Separate steady and burst capacity — persistent workloads run on a fixed node pool. Ingestion and batch workloads scale independently on a dedicated burst pool, avoiding contention.

Availability model

The availability model follows the AWS Well-Architected Reliability Pillar, specifically the design principles of automatic recovery from failure, horizontal scaling, and eliminating single points of failure. The platform uses multi-AZ deployments as the primary resilience mechanism, aligned with the AWS Resilience Lifecycle Framework's guidance on fault isolation boundaries at the Availability Zone level.

The platform deploys across three Availability Zones within a single AWS region. All stateful services are multi-AZ with automatic failover. Stateless compute recovers through Kubernetes rescheduling across surviving nodes. There is no cross-region replication by default — the single-region, multi-AZ model provides the resilience target for the reference architecture. Cross-region active-passive or pilot-light patterns can be added if the client's recovery requirements demand it.

Capacity and performance

EKS compute is split into two managed node groups to isolate steady-state workloads from unpredictable burst demand. This separation prevents a large ingestion job from starving the chat or API services of resources, and allows each pool to be sized and scaled independently.

Steady pool runs all persistent workloads — application services, AI services, and platform services. Nodes are distributed across three Availability Zones for resilience. The pool is sized during Foundation based on the number of concurrent users, active integrations, and baseline query load. The steady pool size is set during Foundation and adjusted through planned capacity changes, keeping compute costs predictable.

Rapid pool handles burst workloads — document ingestion, batch embedding, and scheduled sync jobs. The pool starts at zero nodes and scales out on demand. KEDA scales pods based on queue depth and workload metrics, and Karpenter provisions nodes to match. When demand subsides, pods and nodes scale back down.

Every workload has explicit CPU and memory requests and limits. Kubernetes resource quotas prevent any single namespace from consuming more than its allocation. Pod disruption budgets are set on all critical services to maintain minimum replica counts during node drains, upgrades, and AZ failovers.

The reference architecture includes Karpenter for automatic node scaling and consolidation of the steady pool.

Zero-Downtime Maintenance

AWS managed services require periodic maintenance — engine patches, minor version upgrades, and security fixes. The multi-AZ architecture ensures these maintenance events do not cause application downtime.

Aurora PostgreSQL applies patches to the reader instance first, promotes it, then patches the old writer. The cluster endpoint follows the promotion automatically, so application connections are uninterrupted. ElastiCache Redis follows the same pattern — the replica is patched, promoted, and the old primary is patched in turn. In both cases, failover completes in seconds and is transparent to the application.

EKS control plane upgrades are managed by AWS and are rolling by design — API server availability is maintained throughout. Node group upgrades are coordinated by Unique: a new node group is launched with the updated AMI, workloads are drained from the old nodes, and the old group is terminated. Pod disruption budgets ensure minimum replica counts are maintained during the drain.

Maintenance windows for Aurora and ElastiCache are configured during the Foundation phase, typically scheduled during low-traffic hours. EKS node group upgrades are planned and executed by Unique as part of the regular release cycle, with timing agreed with the client.

The key design point: multi-AZ redundancy is not just for failure scenarios — it is what makes zero-downtime maintenance possible. Single-AZ deployments would require scheduled downtime for every patch cycle.

SLA boundaries

The reference architecture is based on Unique AI engineering best practices and lessons learned operating the platform across multiple customer environments, designed to maintain 99.5% availability (a figure that is indicative, at the time of writing, and provided for reference only; binding commitments are defined per engagement in the service agreement).

Unique does not commit to a composite SLA for the self-hosted platform. The deployment runs in the client's AWS account, and availability depends on infrastructure choices made by the client — AZ configuration, Direct Connect resilience, Transit Gateway redundancy — as much as on Unique's application layer.

What Unique provides: recommended SLOs for the application tier as defined on the Target Operating Model page, monitoring and alerting to detect degradation, and L3 incident response for platform-level issues. The underlying AWS service SLAs apply to the client's account and are between the client and AWS. Unique's observability stack surfaces breaches against both the recommended SLOs and AWS service health indicators.

Dependencies and Scope

This section defines what must exist before deployment begins and where the responsibility boundary sits between Unique and the client. The prerequisites follow the AWS shared responsibility model extended to the platform layer — the client owns the landing zone and network perimeter, Unique owns everything inside the workload account.

Prerequisites

These are the client-side dependencies that must be in place before Unique's infrastructure-as-code can execute. Each prerequisite is owned by the client's platform or cloud team and blocks a specific phase of the deployment.

The Pre-Installation Checklist page provides the detailed configuration values, naming conventions, and validation steps for each prerequisite.

Governance considerations

Enterprise AWS environments typically enforce governance controls that can affect the deployment. These should be reviewed during the Evaluate phase and resolved before Foundation begins.

Service Control Policies are the most common source of deployment friction. The Unique platform provisions resources across a broad set of AWS services, and the workload account must be enrolled in an OU whose SCPs permit them. Unique provides a full list of required IAM actions during the Evaluate phase so the client's cloud team can validate SCP compatibility before deployment begins.

Beyond permitting the required services, Unique recommends the following SCPs on the workload account to enforce the architecture's security posture. These align with AWS Security Reference Architecture guardrails and Control Tower best practices.

Network and egress controls

Data protection and residency

Identity and privilege controls

Audit trail protection

IAM Identity Center (AWS SSO) is the recommended mechanism for human access to the workload account. Unique's deployment engineers require federated access with sufficient permissions to execute Terraform plans and inspect resources. The client controls which permission sets are granted and can scope access to specific roles and session durations. No long-lived IAM user credentials are required for deployment or operations.

Tag policies enforced at the organisation level must be accommodated in the infrastructure-as-code. Unique's Terraform modules support configurable tag maps — mandatory tags such as cost centre, environment, owner, and application are injected at the module level. Tag requirements should be provided during Foundation so they are applied from the first deployment.

AWS Config rules and conformance packs may flag resources that deviate from the organisation's baseline. Common findings include security groups with broad CIDR ranges, S3 buckets without object lock, or KMS keys without automatic rotation. Unique's reference architecture addresses most CIS and Well-Architected benchmarks by default, but organisation-specific Config rules should be reviewed during Foundation to resolve any conflicts before they generate compliance findings.

Service quotas should be validated before deployment. The platform consumes a significant number of VPC endpoints, ENIs, security groups, and EKS-managed resources. Default AWS quotas are sufficient for most deployments, but accounts with existing workloads or restrictive custom quotas may need increases. Unique provides a service quota checklist as part of the Pre-Installation Checklist.

Scope boundary

Unique's infrastructure-as-code provisions everything inside the workload account: VPC, subnets, security groups, EKS cluster, data services, KMS keys, Secrets Manager entries, load balancers, all Kubernetes workloads, and the observability stack. The Terraform codebase is structured into layered modules that execute sequentially, supporting split execution — the client's platform team can run the infrastructure layers while Unique manages the application layers, or Unique can run the full stack. The engagement model is agreed during Foundation.

The client provisions everything outside the workload account: AWS Organisation, account enrolment, network connectivity (Transit Gateway, Direct Connect, Network Firewall, NAT Gateway), CIDR allocation, DNS delegation, identity provider, and Bedrock model access.

The operational responsibilities — who responds to incidents, who approves maintenance windows, how upgrades are coordinated — are defined on the Target Operating Model page.

Adaptive Architecture

The Unique AI platform adapts to your existing infrastructure strategy and enterprise architecture. Whether your organisation runs a mature multi-account landing zone with centralised network services, or needs a lightweight single-account deployment for evaluation, the same infrastructure-as-code adapts to your environment through configuration rather than custom engineering.

This flexibility is structured around three independent dimensions: AWS account topology (how accounts and network services are organised), network access model (how users and external consumers reach the platform), and data service hosting (managed PaaS or cloud-native on EKS). These dimensions are orthogonal — any combination produces a valid deployment profile that matches your enterprise architecture without compromising the platform's security posture or operational model.

The reference architecture described on this page follows the most common enterprise profile: hub-and-spoke accounts, internal-only access via Direct Connect, and PaaS data services. The sections below summarise what changes when your requirements differ.

AWS account topologies

The AWS account topology determines the account structure and where network, governance, and shared services live relative to the workload.

Hub-and-spoke is the standard model documented throughout this page. The connectivity account owns the network perimeter, and the workload account owns everything inside the VPC. Topology selection is configuration-driven: providing Transit Gateway and connectivity account identifiers activates hub-and-spoke; omitting them produces standalone.

Hub-and-spoke with shared services extends the standard model by placing shared infrastructure — such as a centralised ECR registry, Route 53 parent zones, or organisation-wide logging — in a dedicated shared services account. The workload account references these shared resources via cross-account identifiers. This model aligns with the AWS multi-account strategy for organisations that centralise common services rather than replicating them per workload.

Standalone removes the connectivity account dependency entirely. A single account hosts both the platform and its own internet egress via NAT Gateway. There is no centralised network inspection, no separation of concerns between network and workload, and the security posture is significantly reduced. It is intended as a fast path to get the platform running for evaluation or development, with the expectation of migrating to hub-and-spoke for production.

Network access models

The network access model determines how users and external consumers reach the platform. It is independent of account topology — any access model can be combined with any account topology.

Internal is the standard model documented throughout this page. All user traffic arrives via Direct Connect through Transit Gateway. No public DNS records, no public ALB, no internet-facing endpoints.

CloudFront adds a public ingress path via a CloudFront distribution with AWS WAF. This model is required when users access the platform from the internet — either because there is no Direct Connect, or because the user population includes external parties. The workload account internals are unchanged; Kong routes traffic identically regardless of origin.

Dual combines both paths. Internal users access via Direct Connect for lowest latency and network locality; external users access via CloudFront. A dedicated public WebSocket ALB handles real-time connections through CloudFront. WAF rules on the public path and Network Firewall on egress provide defence in depth.

The dual and CloudFront models do not change the workload account internals — the same EKS cluster, data services, and integration boundaries serve all paths. The additional attack surface introduced by public ingress is mitigated by WAF rules and CloudFront origin access controls.

Data service hosting

The data service hosting model determines whether stateful services run as AWS-managed PaaS or as cloud-native services on the EKS cluster. This choice affects operational responsibility, cost structure, and how the client's platform team interacts with the data layer.

PaaS is the standard model documented throughout this page. Aurora, ElastiCache, and OpenSearch run as AWS-managed services in isolated subnets, accessed via VPC Endpoints. AWS handles engine patching, automated backups, multi-AZ failover, and scaling. This model offers the lowest operational overhead and is recommended for most deployments.

Cloud-native replaces the managed services with Kubernetes-native operators running on the EKS cluster. The database, cache, and search services are deployed and managed through the same infrastructure-as-code and GitOps pipeline as the application workloads. This model gives the platform team full control over versioning, configuration, and upgrade timing, but shifts operational responsibility for backups, failover, and patching to the EKS layer. Compute and storage costs move from PaaS pricing to EKS node and EBS volume costs.

The choice does not affect the application layer — connection strings and endpoints are abstracted, so the platform workloads are agnostic to the hosting model. The decision is typically driven by the client's cloud governance policies and operational preferences rather than technical constraints.