# anomalyinnovations/serverless-stack-demo-api architecture

> Architecture diagram of the GitHub repository anomalyinnovations/serverless-stack-demo-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anomalyinnovations/serverless-stack-demo-api
- Repository: https://github.com/anomalyinnovations/serverless-stack-demo-api

## Overview

##### Project type and purpose
- This is a serverless backend API (built with the Serverless Framework) that supports a note-taking application.
- It exposes REST endpoints for CRUD operations on notes (create, list, get, update, delete) plus a billing endpoint.
- It relies on AWS Lambda functions, DynamoDB for persistence, Cognito for authentication/authorization, S3 (for attachments), and integrates with an external billing provider.

##### File structure
- Top-level Lambda handlers:
– billing.js, create.js, delete.js, get.js, list.js, update.js
- libs/: common utility code used by all handlers (dynamodb-lib.js, handler-lib.js, response-lib.js, billing-lib.js, debug-lib.js)
- resources/: standalone CloudFormation/YAML fragments (API Gateway error mappings, Cognito user & identity pools, DynamoDB table, S3 bucket)
- serverless.yml: ties it all together, defining functions, events (HTTP, authorizers), permissions, environment variables
- mocks/ & tests/: local function invocation events and Jest test cases
- package.json / .env reference: Node.js runtime, npm dependencies, secret config

##### README for additional insights
- Confirms use of Serverless Framework for deploying AWS resources
- Shows local invocation via `serverless invoke local --function <name>`
- Mentions a separate React frontend that calls this API
- Notes use of Cognito authorizer in API Gateway

a. Main components to represent
- React Frontend (external client)
- API Gateway
– HTTP endpoints for /notes (GET, POST, PUT, DELETE) and /billing
– Cognito User Pool authorizer
- AWS Lambda Functions
– Note CRUD handlers
– Billing handler
– Shared libs (DynamoDB helper, response helper, billing helper, etc.)
- Cognito
– User Pool (authentication)
– Identity Pool (temporary credentials)
- DynamoDB Table (notes)
- S3 Bucket (note attachments)
- External Billing Service (e.g., Stripe)
- Deployment layer: Serverless Framework / CloudFormation

b. Relationships & data flow
1. Frontend → HTTP request → API Gateway
2. API Gateway → Cognito authorizer (validate JWT)
3. API Gateway → invokes the corresponding Lambda function
4. Lambda function reads/writes DynamoDB and/or S3
5. Billing function → calls external billing provider API
6. Lambdas emit logs to CloudWatch Logs

c. Architectural patterns & principles
- Serverless / FaaS: each handler is a single-purpose Lambda
- Shared utility library to enforce common patterns (error handling, DynamoDB access)
- Infrastructure as Code: resources defined in serverless.yml and YAML fragments
- Event-driven: HTTP requests trigger events processed by functions

d. Technologies & frameworks
- Node.js Lambdas
- Serverless Framework (serverless.yml)
- AWS API Gateway
- AWS Lambda
- Amazon DynamoDB
- Amazon S3
- Amazon Cognito (User + Identity Pools)
- External billing SDK (stripe or similar)
- Jest for unit testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    FE["React Frontend"]:::frontend

    %% API Layer
    APIGW["API Gateway"]:::api
    Authorizer["Cognito Authorizer"]:::auth

    %% Compute Layer
    subgraph "Lambda Functions"
        Create["Create Note Lambda"]:::lambda
        GetF["Get Note Lambda"]:::lambda
        Update["Update Note Lambda"]:::lambda
        DeleteF["Delete Note Lambda"]:::lambda
        ListF["List Notes Lambda"]:::lambda
        Billing["Billing Lambda"]:::lambda
    end

    subgraph "Shared Utilities"
        DynLib["DynamoDB Helper"]:::lib
        RespLib["Response Helper"]:::lib
        HandlerLib["Handler Wrapper"]:::lib
        BillLib["Billing Helper"]:::lib
        DebugLib["Debug Helper"]:::lib
    end

    %% Security Layer
    CognUser["Cognito User Pool"]:::auth
    CognID["Cognito Identity Pool"]:::auth

    %% Data Layer
    DB["DynamoDB Table"]:::storage
    S3["S3 Bucket"]:::storage

    %% External Services
    External["External Billing Service"]:::external

    %% Deployment
    Deploy["Serverless Framework / CloudFormation"]:::infra

    %% Connections
    FE -->|HTTP/JSON| APIGW
    APIGW -->|Validate JWT| Authorizer
    Authorizer --> APIGW
    APIGW -->|Invoke| Create
    APIGW -->|Invoke| GetF
    APIGW -->|Invoke| Update
    APIGW -->|Invoke| DeleteF
    APIGW -->|Invoke| ListF
    APIGW -->|Invoke| Billing

    Create -->|Reads/Writes| DB
    GetF -->|Reads| DB
    Update -->|Writes| DB
    DeleteF -->|Deletes| DB
    ListF -->|Scans| DB
    Create -->|Uploads/Downloads| S3

    Billing -->|Calls| External

    Create --> DynLib
    GetF --> DynLib
    Update --> DynLib
    DeleteF --> DynLib
    ListF --> DynLib
    Billing --> BillLib
    Create --> RespLib
    GetF --> RespLib
    Update --> RespLib
    DeleteF --> RespLib
    ListF --> RespLib
    Billing --> RespLib
    Create --> HandlerLib
    GetF --> HandlerLib
    Update --> HandlerLib
    DeleteF --> HandlerLib
    ListF --> HandlerLib
    Billing --> HandlerLib
    Create --> DebugLib
    GetF --> DebugLib
    Update --> DebugLib
    DeleteF --> DebugLib
    ListF --> DebugLib
    Billing --> DebugLib

    FE -->|Deploy| Deploy
    Deploy --> APIGW
    Deploy --> CognUser
    Deploy --> CognID
    Deploy --> DB
    Deploy --> S3
    Deploy --> Create
    Deploy --> GetF
    Deploy --> Update
    Deploy --> DeleteF
    Deploy --> ListF
    Deploy --> Billing

    %% Click Events
    click Create "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/create.js"
    click GetF "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/get.js"
    click Update "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/update.js"
    click DeleteF "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/delete.js"
    click ListF "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/list.js"
    click Billing "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/billing.js"
    click DynLib "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/libs/dynamodb-lib.js"
    click RespLib "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/libs/response-lib.js"
    click HandlerLib "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/libs/handler-lib.js"
    click BillLib "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/libs/billing-lib.js"
    click DebugLib "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/libs/debug-lib.js"
    click Deploy "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/serverless.yml"
    click API_GATEWAY_ERRORS "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/resources/api-gateway-errors.yml"
    click CognUser "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/resources/cognito-user-pool.yml"
    click CognID "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/resources/cognito-identity-pool.yml"
    click DB "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/resources/dynamodb-table.yml"
    click S3 "https://github.com/anomalyinnovations/serverless-stack-demo-api/blob/master/resources/s3-bucket.yml"
    click Mocks "https://github.com/anomalyinnovations/serverless-stack-demo-api/tree/master/mocks/"
    click Tests "https://github.com/anomalyinnovations/serverless-stack-demo-api/tree/master/tests/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef api fill:#FFD580,stroke:#333,stroke-width:1px
    classDef lambda fill:#FFCC99,stroke:#333,stroke-width:1px
    classDef lib fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef storage fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef auth fill:#C6E0B4,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef infra fill:#CCCCCC,stroke:#333,stroke-width:1px
```
