# aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk architecture

> Architecture diagram of the GitHub repository aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk
- Repository: https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk

## Overview

This sample deploys an authenticated jobs API for asynchronous work: a POST accepts job parameters and returns an identifier; a Fargate worker processes the queued job and stores its result; a GET retrieves it. Failed messages take a recovery path through a dead-letter queue and Lambda, which stores failure parameters for retrieval. The graph includes the CDK stack and construct definitions as the internal deployment layer. Runtime relationships follow the README and shown excerpts; the EventBridge archive/replay capability is documented but its wiring is not shown in the sampled source.

Main entry points: [`infrastructure/main.py`](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/main.py) (Infrastructure stack), [`infrastructure/jobs_api/main.py`](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/jobs_api/main.py) (Jobs API), [`infrastructure/event_processing/main.py`](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py) (Jobs queue), [`error_handling/main.py`](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/error_handling/main.py) (Error handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Jobs API"]
  node_api["Jobs API<br/>[main.py]"]
end

subgraph group_processing["Async Processing"]
  node_queue["Jobs queue<br/>[main.py]"]
  node_worker["Fargate worker<br/>[main.py]"]
  node_processor["Job processing<br/>[main.py]"]
  node_table[("Jobs table<br/>[main.py]")]
end

subgraph group_recovery["Failure Recovery"]
  node_dlq["Dead-letter queue<br/>[main.py]"]
  node_eventbridge["EventBridge"]
  node_error_lambda["Error handler<br/>[main.py]"]
  node_archive[("Event archive")]
end

subgraph group_deployment["CDK Deployment"]
  node_stack["Infrastructure stack<br/>[main.py]"]
  node_event_construct["Processing construct<br/>[main.py]"]
  node_api_construct["API construct<br/>[main.py]"]
end

node_user(("Authorized user"))

node_user -->|"submits jobs"| node_api
node_api -->|"enqueues parameters"| node_queue
node_queue -->|"feeds messages"| node_worker
node_worker -->|"runs"| node_processor
node_processor -->|"writes results"| node_table
node_user -->|"requests results"| node_api
node_api -->|"queries job"| node_table
node_queue -->|"routes failures"| node_dlq
node_dlq -->|"triggers"| node_error_lambda
node_eventbridge -.->|"triggers"| node_error_lambda
node_error_lambda -->|"writes failure data"| node_table
node_error_lambda -.->|"archives failures"| node_archive
node_user -.->|"replays events"| node_archive
node_stack -->|"creates"| node_event_construct
node_stack -->|"creates"| node_api_construct
node_stack -->|"configures routes"| node_api
node_stack -->|"grants send access"| node_queue
node_stack -->|"grants read access"| node_table

click node_api "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/jobs_api/main.py"
click node_queue "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py"
click node_worker "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py"
click node_processor "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/event_processing/main.py"
click node_table "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py"
click node_dlq "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py"
click node_error_lambda "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/error_handling/main.py"
click node_stack "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/main.py"
click node_event_construct "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py"
click node_api_construct "https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/jobs_api/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_user toneBlue
class node_queue,node_worker,node_processor,node_table toneAmber
class node_dlq,node_eventbridge,node_error_lambda,node_archive toneMint
class node_stack,node_event_construct,node_api_construct toneRose
```

## Components

### Jobs API

- [Jobs API](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/jobs_api/main.py): `infrastructure/jobs_api/main.py`

### Async Processing

- [Jobs queue](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py): `infrastructure/event_processing/main.py`
- [Fargate worker](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py): `infrastructure/event_processing/main.py`
- [Job processing](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/event_processing/main.py): `event_processing/main.py`
- [Jobs table](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py): `infrastructure/event_processing/main.py`

### Failure Recovery

- [Dead-letter queue](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py): `infrastructure/event_processing/main.py`
- **EventBridge**
- [Error handler](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/error_handling/main.py): `error_handling/main.py`
- **Event archive**

### CDK Deployment

- [Infrastructure stack](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/main.py): `infrastructure/main.py`
- [Processing construct](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/event_processing/main.py): `infrastructure/event_processing/main.py`
- [API construct](https://github.com/aws-samples/asynchronous-event-processing-api-gateway-sqs-cdk/blob/main/infrastructure/jobs_api/main.py): `infrastructure/jobs_api/main.py`

### Other components

- **Authorized user**

## Connections

- Authorized user → Jobs API: submits jobs (evidence: `README.md`)
- Jobs API → Jobs queue: enqueues parameters (evidence: `infrastructure/jobs_api/main.py`)
- Jobs queue → Fargate worker: feeds messages (evidence: `infrastructure/event_processing/main.py`)
- Fargate worker → Job processing: runs (evidence: `infrastructure/event_processing/main.py`)
- Job processing → Jobs table: writes results (evidence: `event_processing/main.py`)
- Authorized user → Jobs API: requests results (evidence: `README.md`)
- Jobs API → Jobs table: queries job (evidence: `infrastructure/jobs_api/main.py`)
- Jobs queue → Dead-letter queue: routes failures (evidence: `infrastructure/event_processing/main.py`)
- Dead-letter queue → Error handler: triggers (evidence: `infrastructure/event_processing/main.py`)
- EventBridge → Error handler: triggers (evidence: `README.md`)
- Error handler → Jobs table: writes failure data (evidence: `error_handling/main.py`)
- Error handler → Event archive: archives failures (evidence: `README.md`)
- Authorized user → Event archive: replays events (evidence: `README.md`)
- Infrastructure stack → Processing construct: creates (evidence: `infrastructure/main.py`)
- Infrastructure stack → API construct: creates (evidence: `infrastructure/main.py`)
- Infrastructure stack → Jobs API: configures routes (evidence: `infrastructure/main.py`)
- Infrastructure stack → Jobs queue: grants send access (evidence: `infrastructure/main.py`)
- Infrastructure stack → Jobs table: grants read access (evidence: `infrastructure/main.py`)
