# basmao9/aws-order-notification-system architecture

> Architecture diagram of the GitHub repository basmao9/aws-order-notification-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/basmao9/aws-order-notification-system
- Repository: https://github.com/basmao9/aws-order-notification-system

## Overview

##### Project Type and Purpose
- This is a serverless, event-driven order-processing backend built on AWS.
- It ingests order messages, buffers them, processes them via Lambda, persists to DynamoDB, and handles failures via an SQS DLQ.

##### File Structure
- Top level:
- `README.md` – overall description and flow
- `cloudformation-template.yaml` – infrastructure as code (SNS, SQS queues, DLQ, Lambda, DynamoDB)
- `lambda.js` – the Lambda handler that parses events and writes to DynamoDB
- `DLQ-visibility-timeout.md` – notes on tuning the DLQ and visibility timeout
- There are no separate “frontend” or “microservice” directories; all logic lives in one Lambda function and supporting infra.

##### README for Additional Insights
- Core services: SNS Topic (`OrderTopic`), SQS Queue (`OrderQueue`), DLQ (`OrderDLQ`), Lambda (`ProcessOrderFunction`), DynamoDB table (`Orders`).
- Message format, error-handling strategy (maxReceiveCount=3 before DLQ), and attribute definitions are all specified.

##### Main Components
a. Publisher (could be a user, API Gateway, or another service)
b. SNS Topic (“OrderTopic”)
c. Primary SQS Queue (“OrderQueue”)
d. Dead-Letter Queue (“OrderDLQ”)
e. AWS Lambda Function (“ProcessOrderFunction”)
f. DynamoDB Table (“Orders”)
g. (Optionally) CloudFormation stack as the deployment orchestration layer

##### Relationships and Data Flows
- (Optionally) CloudFormation Template deploys all resources in one stack

##### Architectural Patterns and Design Principles
- Event-driven decoupling: SNS publishes asynchronously, SQS buffers, Lambda processes
- Resilience: DLQ for poison messages, visibility-timeout tuning
- Serverless: no servers to manage, infra defined in CloudFormation
- Single responsibility: Lambda only processes and persists orders

##### Capturing Essential Details
- Visibility-timeout tuning from `DLQ-visibility-timeout.md`.
- Optional: annotate the CloudFormation template as the “Infrastructure as Code” layer that provisions all services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingestion Layer
    subgraph "Ingestion"
        direction TB
        Publisher["Publisher"]:::external
        OrderTopic["OrderTopic (SNS)"]:::sns
    end

    %% Buffering Layer
    subgraph "Buffering"
        direction TB
        OrderQueue["OrderQueue (SQS)"]:::sqs
    end

    %% Processing Layer
    subgraph "Processing"
        direction TB
        ProcessOrderFunction["ProcessOrderFunction (Lambda)"]:::lambda
    end

    %% Storage Layer
    subgraph "Storage"
        direction TB
        Orders["Orders (DynamoDB)"]:::dynamo
    end

    %% Error Handling Layer
    subgraph "Error handling"
        direction TB
        OrderDLQ["OrderDLQ (SQS DLQ)"]:::sqsdlq
        DLQNote["maxReceiveCount=3\nvisibilityTimeout tuned"]:::note
    end

    %% Infrastructure as Code
    subgraph "Infrastructure as Code (CloudFormation)" 
        direction TB
        IaC["cloudformation-template.yaml"]:::infra
    end

    %% Architecture Reference
    ArchitectureRef["Existing architecture diagram"]:::external

    %% Connections
    Publisher -->|"Publish JSON message"| OrderTopic
    OrderTopic -->|"Fanout to queue"| OrderQueue
    OrderQueue -->|"Trigger on new message"| ProcessOrderFunction
    ProcessOrderFunction -->|"PutItem"| Orders
    ProcessOrderFunction -- After 3 retries --> OrderDLQ
    OrderDLQ --> DLQNote
    IaC -. provisions .-> OrderTopic
    IaC -. provisions .-> OrderQueue
    IaC -. provisions .-> OrderDLQ
    IaC -. provisions .-> ProcessOrderFunction
    IaC -. provisions .-> Orders

    %% References
    ArchitectureRef --> IaC

    %% Click Events
    click Publisher "https://github.com/basmao9/aws-order-notification-system/blob/main/README.md"
    click OrderTopic "https://github.com/basmao9/aws-order-notification-system/blob/main/cloudformation-template.yaml"
    click OrderQueue "https://github.com/basmao9/aws-order-notification-system/blob/main/cloudformation-template.yaml"
    click OrderDLQ "https://github.com/basmao9/aws-order-notification-system/blob/main/cloudformation-template.yaml"
    click ProcessOrderFunction "https://github.com/basmao9/aws-order-notification-system/blob/main/lambda.js"
    click Orders "https://github.com/basmao9/aws-order-notification-system/blob/main/cloudformation-template.yaml"
    click DLQNote "https://github.com/basmao9/aws-order-notification-system/blob/main/DLQ-visibility-timeout.md"
    click ArchitectureRef "https://github.com/basmao9/aws-order-notification-system/blob/main/screenshots/architecture-diagram.png"
    click IaC "https://github.com/basmao9/aws-order-notification-system/blob/main/cloudformation-template.yaml"

    %% Styles
    classDef external fill:#f0f0f0,stroke:#999,stroke-width:1px
    classDef sns fill:#FF9900,stroke:#cc7700,stroke-width:2px
    classDef sqs fill:#FFCC66,stroke:#cc9900,stroke-width:2px
    classDef sqsdlq fill:#FFCC66,stroke:#cc9900,stroke-width:2px,stroke-dasharray: 5 5
    classDef lambda fill:#00CCFF,stroke:#0099cc,stroke-width:2px
    classDef dynamo fill:#99CC00,stroke:#669900,stroke-width:2px
    classDef infra fill:#CC99FF,stroke:#9966cc,stroke-width:2px
    classDef note fill:#FFFFFF,stroke:#000000,stroke-dasharray: 2 2,fontsize:10px,align:center
```
