# Architecture overview


This document describes the technical architecture of Spatial Data Management on AWS, including the AWS services used and how they interact.

## High-Level Architecture


![\[High-level architecture diagram showing the three main layers of Spatial Data Management on AWS\]](http://docs.aws.amazon.com/solutions/latest/spatial-data-management-on-aws/images/high_level_architecture_interfaces.svg)


The Spatial Data Management on AWS solution is deployed entirely within your AWS account. The architecture consists of three main layers:

### Client Layer


Users and external applications access the solution through multiple interfaces:
+  **Spatial Data Portal** – Web application (Amazon CloudFront and React) and desktop application (Tauri and Rust)
+  **REST APIs** – Programmatic access via Amazon API Gateway
+  **CLI Tools** – Python-based command-line interface
+  **Direct S3 Access** – Temporary credentials for large file uploads and downloads

### SDMA Deployment (Your AWS Account)


The core solution includes:
+  **Control Plane** – Amazon API Gateway and AWS Lambda functions for business logic and orchestration
+  **Data Plane** – Amazon S3 for spatial asset storage with content-addressable architecture
+  **Metadata Layer** – Amazon DynamoDB for resource metadata and Amazon OpenSearch Serverless for full-text search
+  **Integration Layer** – Amazon EventBridge, Amazon SQS, and connectors for external system integration
+  **Security Layer** – Amazon Cognito for authentication and Amazon Verified Permissions for authorization

### External Applications


Third-party systems integrate through:
+  **REST APIs** – Standard HTTP/HTTPS endpoints
+  **S3 APIs** – Direct access to spatial assets with temporary credentials
+  **Webhooks** – Event notifications for asset changes
+  **Connectors** – Pre-built integrations for common platforms (Digital Twin, Geographic Information Systems (GIS), and Computer-Aided Design (CAD) tools)

# Architectural Principles


The solution follows AWS Well-Architected Framework principles:

## Separation of Concerns


The architecture separates data storage (Amazon S3), business logic (Amazon API Gateway and AWS Lambda), and metadata management (Amazon DynamoDB and Amazon OpenSearch Serverless) into distinct layers for independent scaling and maintenance.

## Content-Addressable Storage


Files are stored by content hash with automatic deduplication across assets, ensuring efficient storage and immutable file references.

## Event-Driven Architecture


Amazon EventBridge routes events to Amazon SQS and AWS Lambda for asynchronous, scalable processing of asset changes and system events.

## Security by Design


The solution uses VPC isolation, private VPC endpoints, encryption at rest and in transit, fine-grained access control, and audit logging to protect data and operations.

# AWS Services



| Service | Purpose | 
| --- | --- | 
|  Amazon S3  |  Primary storage for spatial asset files with versioning and lifecycle management  | 
|  Amazon DynamoDB  |  Metadata storage using on-demand billing and point-in-time recovery  | 
|  Amazon OpenSearch Serverless  |  Full-text search and geospatial queries with serverless auto-scaling  | 
|  Amazon API Gateway  |  RESTful API interface with Cognito and IAM authorization  | 
|  AWS Lambda  |  Serverless compute for API handlers and event processing  | 
|  Amazon Cognito  |  User authentication and identity management with user pools  | 
|  Amazon Verified Permissions  |  Fine-grained access control using Cedar policy language  | 
|  AWS Key Management Service (AWS KMS)  |  Customer-managed encryption keys with automatic rotation  | 
|  AWS Secrets Manager  |  Secure storage for sensitive configuration values and credentials  | 
|  Amazon EventBridge  |  Event bus for workflow orchestration and asset change notifications  | 
|  Amazon SQS  |  Asynchronous message processing with queues and dead letter queues  | 
|  Amazon CloudFront  |  Content delivery for web portal with signed URLs for secure access  | 
|  AWS Certificate Manager (ACM)  |  SSL/TLS certificate management for API Gateway and CloudFront  | 
|  Amazon VPC  |  Network isolation with VPC endpoints for private AWS service access  | 
|  AWS CloudFormation  |  Infrastructure deployment and management using nested stacks  | 
|  AWS Deadline Cloud  |  Optional rendering and batch processing for content derivation  | 
|  Amazon CloudWatch  |  Metrics, logs, and dashboards for operational visibility  | 
|  AWS CloudTrail  |  API activity logging for security and compliance auditing  | 
|  AWS X-Ray  |  Distributed tracing for performance analysis and debugging  | 

# Network Architecture


## VPC Configuration



| Component | Configuration | 
| --- | --- | 
|  Subnets  |  Public, private (with NAT gateway), and isolated (no internet)  | 
|  Availability Zones  |  Two Availability Zones for high availability  | 
|  NAT Gateways  |  One NAT gateway per Availability Zone for redundancy  | 
|  VPC Endpoints  |  Eight VPC endpoints for private AWS service access  | 

## Lambda Placement



| Function | Subnet Type | Purpose | 
| --- | --- | --- | 
|  Resource Operation Function  |  Private subnets  |  Requires internet access for external APIs  | 
|  Asset Watcher Function  |  Isolated subnets  |  No internet access required  | 
|  Other Functions  |  Private subnets  |  Based on individual requirements  | 

## Security Groups



| Security Group | Rules | 
| --- | --- | 
|  Lambda Security Group  |  Outbound HTTPS to VPC endpoints and internet  | 
|  VPC Endpoint Security Group  |  Inbound HTTPS from Lambda  | 
|  OpenSearch Security Group  |  Inbound HTTPS from Lambda  | 

# Deployment Architecture


The solution is deployed using AWS CloudFormation with nested stacks:


| Stack | Components | 
| --- | --- | 
|  VPC Stack  |  Network infrastructure  | 
|  Auth Stack  |  Amazon Cognito and Amazon Verified Permissions  | 
|  Asset Management Stack  |  Core services (Lambda, DynamoDB, S3, API Gateway)  | 
|  OpenSearch Stack  |  Search infrastructure  | 
|  Portal Stack  |  Amazon CloudFront and web assets  | 
|  Deadline Stack  |  Rendering and batch processing services  | 
|  Monitoring Stack  |  Amazon CloudWatch, AWS CloudTrail, and AWS X-Ray  |