From 9d6aa9a096f1394b2356ae12451f9441cadd8234 Mon Sep 17 00:00:00 2001 From: Mohamed Ali Jamaoui Date: Mon, 8 Jun 2026 20:30:26 +0100 Subject: [PATCH] docs(architecture): add standalone HTML architecture diagram and AWS icons --- architecture/architecture-diagram.html | 973 ++++++++++++++++++++++ architecture/assets/README.md | 32 + architecture/assets/amazon-location.svg | 12 + architecture/assets/api-gateway.svg | 10 + architecture/assets/bedrock-agentcore.svg | 11 + architecture/assets/bedrock.svg | 12 + architecture/assets/cloudfront.svg | 10 + architecture/assets/cloudwatch.svg | 10 + architecture/assets/cognito.svg | 10 + architecture/assets/ecs.svg | 10 + architecture/assets/elb.svg | 10 + architecture/assets/lambda.svg | 10 + architecture/assets/osm.svg | 7 + architecture/assets/s3.svg | 12 + architecture/assets/satellite.svg | 11 + architecture/assets/secrets-manager.svg | 10 + architecture/assets/users.svg | 7 + architecture/assets/waf.svg | 12 + architecture/index.html | 7 + 19 files changed, 1176 insertions(+) create mode 100644 architecture/architecture-diagram.html create mode 100644 architecture/assets/README.md create mode 100644 architecture/assets/amazon-location.svg create mode 100644 architecture/assets/api-gateway.svg create mode 100644 architecture/assets/bedrock-agentcore.svg create mode 100644 architecture/assets/bedrock.svg create mode 100644 architecture/assets/cloudfront.svg create mode 100644 architecture/assets/cloudwatch.svg create mode 100644 architecture/assets/cognito.svg create mode 100644 architecture/assets/ecs.svg create mode 100644 architecture/assets/elb.svg create mode 100644 architecture/assets/lambda.svg create mode 100644 architecture/assets/osm.svg create mode 100644 architecture/assets/s3.svg create mode 100644 architecture/assets/satellite.svg create mode 100644 architecture/assets/secrets-manager.svg create mode 100644 architecture/assets/users.svg create mode 100644 architecture/assets/waf.svg create mode 100644 architecture/index.html diff --git a/architecture/architecture-diagram.html b/architecture/architecture-diagram.html new file mode 100644 index 0000000..df1376a --- /dev/null +++ b/architecture/architecture-diagram.html @@ -0,0 +1,973 @@ + + + + + + +Geospatial Agent on AWS — Architecture + + + + + +
+
+

Geospatial Agent on AWS — Architecture

+
Natural-language Sentinel-2 analysis · Strands · AgentCore · Claude Sonnet · MapLibre
+
+
+ + + ● Demo + us-east-1 +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + Edge Layer + + 1 + + + + VPC — Public ALB · Private ECS Fargate + + 2 + + + + Bedrock AgentCore Runtime + + 3 + + + + External Data Sources + + 4 + + + + Shared Storage — S3 Bucket + + 5 + + + + TiTiler Tile Server + + 6 + + + + + +
+
+
+ Browser +
+
Browser
+
React + MapLibre
+
Cognito SDK
+
+
+
+
+ Cognito +
+
Cognito
+
User Pool · MFA · JWT
+
+
+
+
+ WAF +
WAF v2
+
+
+ CloudFront +
+
CloudFront
+
+ X-CF-Secret hdr
+
+
+
+
+
+
+ + + + +
+
+
+ ALB +
+
ALB
+
idle 120s · L7
+
+
+
+
+ ECS +
+
ECS Fargate · Express + React SPA
+
2× tasks · 1 vCPU · 2 GB · auto-scale 1–10
+
+
+
+
JWT verify
+
SSE proxy
+
Pre-signed URLs
+
/api/scenario
+
+
+
+
+ + + + +
+
+ +
AgentCore container · arm64 · Python 3.12
+
+
+ +
+
+
Strands Agent
+
@app.entrypoint loop
+
+
+
System prompt + cachePoint
+
SlidingWindowConvManager(3)
+
S3SessionManager (sessions/)
+
stream_async → SSE chunks
+
+
+ +
+
+
+ Bedrock +
Amazon Bedrock
+
+
Claude Sonnet 4.6
+
temp 0.1 · prompt caching
+
+
+
+ +
MCP Server (stdio)
+
+
awslabs.aws_location
+
tool: search_places
+
child process
+
+
+
+ +
@tool functions:
+
+
get_rasters
+
run_bandmath
+
display_visual
+
find_location_boundary
+
calc_environmental_impact
+
+
+
get_best_geometry
+
create_bbox_from_coords
+
list_session_assets
+
calculator
+
+
+ + + + +
+
+
+ Sentinel +
Sentinel-2 STAC
+
+
+
earth-search.aws.element84.com
+
Public COGs · L2A · 10/20m bands
+
red · green · nir · nir08 · swir2 · TCI
+
+
+
+
+ OSM +
OpenStreetMap
+
+
+
via osmnx
+
named-feature boundaries
+
+
+
+
+ Bedrock +
Bedrock Foundation Models
+
+
+
us.anthropic.claude-sonnet-4-6
+
cross-region inference profile
+
+
+
+
+ Amazon Location +
Amazon Location Service
+
+
+
via bundled MCP server
+
geocoding (search_places)
+
+
+
+
Langfuse (optional)
+
+
OTLP traces · LLM observability
+
enabled by deploy_with_langfuse.sh
+
+
+
+
+ CloudWatch +
CloudWatch + ADOT
+
+
+
opentelemetry-instrument
+
logs + traces · default path
+
+
+
+ + + + +
+
+
+
+
+ S3 +
+
S3 Bucket
+
private · TLS only
+
+
+
+
+ Secrets +
+
Secrets Manager
+
CF custom-header ref
+
+
+
+
+
PREFIXES
+
sessions/<sid>/ — Strands history
+
session_data/<sid>/rasters/ — TCI · NDVI · NDWI · NBR (COGs)
+
session_data/<sid>/geometries/ — AOI GeoJSON
+
use-cases/<id>/ — pre-baked scenarios
+
+
+
+ IAM (scoped): + ECS task → bedrock + agentcore + S3 (this bucket) · + Agent role → bedrock + S3 + logs +
+
+ + + + +
+
+ API Key (rate-limit only): 100 rps · 200 burst · 20K/day +
+
+
+ API GW +
+
API Gateway
+
x-api-key required
+
+
+
+ Lambda +
+
Lambda + Web Adapter
+
3008 MB · 30s · x86_64
+
FastAPI · TiTiler 0.24
+
+
+
+
+ Browser: + 1) ask backend for pre-signed URL of COG  ·  + 2) GET /cog/tiles/.../{z}/{x}/{y}.png?url=<presigned>  ·  + 3) MapLibre renders PNG layer  ·  + 4) CORS allows S3 GET/HEAD from CloudFront origin +
+
+ + + + + + + + +
+
3
Deployable Components
+
~15min
Full Deploy
+
1
Shared S3 Bucket
+
60d
Sentinel-2 Search Window
+
3
Spectral Indices · NDVI · NDWI · NBR
+
3
Pre-baked Scenarios
+
+ + +
+
Request Flow (HTTPS)
+
Agent Loop · Bedrock · MCP
+
Auth (JWT) / S3 Reads & Writes
+
Tile Rendering Path
+
External APIs (STAC · OSM · Location)
+
Edge / Static Assets
+
+ Strands · AgentCore · Claude Sonnet · MapLibre · TiTiler · us-east-1 +
+
+ +
+ + + + + + diff --git a/architecture/assets/README.md b/architecture/assets/README.md new file mode 100644 index 0000000..cb436e7 --- /dev/null +++ b/architecture/assets/README.md @@ -0,0 +1,32 @@ +# Diagram icons + +The architecture diagram (`../architecture-diagram.html`) references SVG icons from this folder. The folder is self-contained — no external paths. + +## Inventory + +| File | Source | Used for | +| --- | --- | --- | +| `users.svg` | (provided) | Browser / end user | +| `cognito.svg` | (provided) | Amazon Cognito User Pool | +| `waf.svg` | (provided) | AWS WAF v2 | +| `cloudfront.svg` | (provided) | Amazon CloudFront | +| `elb.svg` | (provided) | Application Load Balancer | +| `ecs.svg` | (provided) | ECS Fargate service | +| `s3.svg` | (provided) | S3 bucket | +| `secrets-manager.svg` | (provided) | Secrets Manager (CF custom-header reference) | +| `bedrock.svg` | (provided) | Bedrock foundation models | +| `bedrock-agentcore.svg` | (provided) | Bedrock AgentCore Runtime container header | +| `lambda.svg` | (provided) | TiTiler Lambda function | +| `api-gateway.svg` | (provided) | API Gateway in front of TiTiler | +| `amazon-location.svg` | AWS pack — `Arch_Front-End-Web-Mobile/64/Arch_Amazon-Location-Service_64.svg` | Amazon Location Service (via bundled MCP server) | +| `satellite.svg` | AWS pack — `Category-Icons_04302026/Arch-Category_64/Arch-Category_Satellite_64.svg` | Sentinel-2 / STAC catalog node (generic Satellite category icon) | +| `osm.svg` | AWS pack — `Resource-Icons_04302026/Res_General-Icons/Res_48_Dark/Res_Globe_48_Dark.svg` | OpenStreetMap (generic globe icon as a stand-in) | +| `cloudwatch.svg` | AWS pack — `Arch_Management-Tools/64/Arch_Amazon-CloudWatch_64.svg` | CloudWatch + ADOT observability node | + +## Style + +If you swap any icon, keep: + +- SVG, square viewBox (32 × 32 or 64 × 64 work best at the diagram's render size). +- AWS-canonical brand colors against a transparent background. +- Roughly the same visual weight as the existing icons (the diagram doesn't normalize size beyond the `width` / `height` on each ``). diff --git a/architecture/assets/amazon-location.svg b/architecture/assets/amazon-location.svg new file mode 100644 index 0000000..e71f9c2 --- /dev/null +++ b/architecture/assets/amazon-location.svg @@ -0,0 +1,12 @@ + + + Icon-Architecture/64/Arch_Amazon-Location-Service_64 + + + + + + + + + \ No newline at end of file diff --git a/architecture/assets/api-gateway.svg b/architecture/assets/api-gateway.svg new file mode 100644 index 0000000..734804c --- /dev/null +++ b/architecture/assets/api-gateway.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/architecture/assets/bedrock-agentcore.svg b/architecture/assets/bedrock-agentcore.svg new file mode 100644 index 0000000..a1e9373 --- /dev/null +++ b/architecture/assets/bedrock-agentcore.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/architecture/assets/bedrock.svg b/architecture/assets/bedrock.svg new file mode 100644 index 0000000..41fe7b5 --- /dev/null +++ b/architecture/assets/bedrock.svg @@ -0,0 +1,12 @@ + + + Icon-Architecture/48/Arch_Amazon-Bedrock_48 + + + + + + + + + \ No newline at end of file diff --git a/architecture/assets/cloudfront.svg b/architecture/assets/cloudfront.svg new file mode 100644 index 0000000..96b38fe --- /dev/null +++ b/architecture/assets/cloudfront.svg @@ -0,0 +1,10 @@ + + + Icon-Architecture/64/Arch_Amazon-CloudFront_64 + + + + + + + \ No newline at end of file diff --git a/architecture/assets/cloudwatch.svg b/architecture/assets/cloudwatch.svg new file mode 100644 index 0000000..97a7e5f --- /dev/null +++ b/architecture/assets/cloudwatch.svg @@ -0,0 +1,10 @@ + + + Icon-Architecture/64/Arch_Amazon-CloudWatch_64 + + + + + + + \ No newline at end of file diff --git a/architecture/assets/cognito.svg b/architecture/assets/cognito.svg new file mode 100644 index 0000000..06141d9 --- /dev/null +++ b/architecture/assets/cognito.svg @@ -0,0 +1,10 @@ + + + Icon-Architecture/64/Arch_Amazon-Cognito_64 + + + + + + + \ No newline at end of file diff --git a/architecture/assets/ecs.svg b/architecture/assets/ecs.svg new file mode 100644 index 0000000..b7c3191 --- /dev/null +++ b/architecture/assets/ecs.svg @@ -0,0 +1,10 @@ + + + Icon-Architecture/64/Arch_Amazon-Elastic-Container-Service_64 + + + + + + + \ No newline at end of file diff --git a/architecture/assets/elb.svg b/architecture/assets/elb.svg new file mode 100644 index 0000000..76c495b --- /dev/null +++ b/architecture/assets/elb.svg @@ -0,0 +1,10 @@ + + + Icon-Architecture/64/Arch_Elastic-Load-Balancing_64 + + + + + + + \ No newline at end of file diff --git a/architecture/assets/lambda.svg b/architecture/assets/lambda.svg new file mode 100644 index 0000000..232385c --- /dev/null +++ b/architecture/assets/lambda.svg @@ -0,0 +1,10 @@ + + + Icon-Architecture/48/Arch_AWS-Lambda_48 + + + + + + + \ No newline at end of file diff --git a/architecture/assets/osm.svg b/architecture/assets/osm.svg new file mode 100644 index 0000000..6f5ae02 --- /dev/null +++ b/architecture/assets/osm.svg @@ -0,0 +1,7 @@ + + + Icon-Resource/General-Resource/Res_Globe_48_Dark + + + + \ No newline at end of file diff --git a/architecture/assets/s3.svg b/architecture/assets/s3.svg new file mode 100644 index 0000000..a562fe1 --- /dev/null +++ b/architecture/assets/s3.svg @@ -0,0 +1,12 @@ + + + Icon-Architecture/64/Arch_Amazon-Simple-Storage-Service_64 + + + + + + + + + \ No newline at end of file diff --git a/architecture/assets/satellite.svg b/architecture/assets/satellite.svg new file mode 100644 index 0000000..3a6a92a --- /dev/null +++ b/architecture/assets/satellite.svg @@ -0,0 +1,11 @@ + + + Icon-Architecture-Category/64/Satellite_64 + + + + + + + + \ No newline at end of file diff --git a/architecture/assets/secrets-manager.svg b/architecture/assets/secrets-manager.svg new file mode 100644 index 0000000..469564a --- /dev/null +++ b/architecture/assets/secrets-manager.svg @@ -0,0 +1,10 @@ + + + Icon-Architecture/64/Arch_AWS-Secrets-Manager_64 + + + + + + + \ No newline at end of file diff --git a/architecture/assets/users.svg b/architecture/assets/users.svg new file mode 100644 index 0000000..b08a4eb --- /dev/null +++ b/architecture/assets/users.svg @@ -0,0 +1,7 @@ + + + Icon-Resource/General-Resource/Res_Users_48_Dark + + + + \ No newline at end of file diff --git a/architecture/assets/waf.svg b/architecture/assets/waf.svg new file mode 100644 index 0000000..8c96961 --- /dev/null +++ b/architecture/assets/waf.svg @@ -0,0 +1,12 @@ + + + Icon-Architecture/64/Arch_AWS-WAF_64 + + + + + + + + + \ No newline at end of file diff --git a/architecture/index.html b/architecture/index.html new file mode 100644 index 0000000..2673ba0 --- /dev/null +++ b/architecture/index.html @@ -0,0 +1,7 @@ + + + + + + +