https://github.com/localstack-samples/sample-loan-broker-stepfunctions-lambda
Loan Broker application using Step Functions, DynamoDB, Lambda, SQS, and SNS.
https://github.com/localstack-samples/sample-loan-broker-stepfunctions-lambda
aws developer-hub dynamodb lambda localstack localstack-developer-hub sns sqs step-functions
Last synced: 9 months ago
JSON representation
Loan Broker application using Step Functions, DynamoDB, Lambda, SQS, and SNS.
- Host: GitHub
- URL: https://github.com/localstack-samples/sample-loan-broker-stepfunctions-lambda
- Owner: localstack-samples
- License: apache-2.0
- Created: 2023-04-24T13:29:27.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-14T12:44:42.000Z (12 months ago)
- Last Synced: 2025-03-24T18:06:35.730Z (9 months ago)
- Topics: aws, developer-hub, dynamodb, lambda, localstack, localstack-developer-hub, sns, sqs, step-functions
- Language: TypeScript
- Homepage:
- Size: 1.97 MB
- Stars: 5
- Watchers: 18
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Loan Broker application with AWS Step Functions, DynamoDB, Lambda, SQS, and SNS
| Key | Value |
| ------------ | ------------------------------------------------------------------------------------- |
| Environment | 
|
| Services | Step Functions, SQS, SNS, Lambda, DynamoDB, EventBridge |
| Integrations | CDK, AWS CLI |
| Categories | Serverless; Event-Driven architecture |
| Level | Intermediate |
| GitHub | [Repository link](https://github.com/localstack/loan-broker-stepfunctions-lambda-app) |
## Introduction
The Loan Broker application with AWS Step Functions, DynamoDB, Lambda, SQS, and SNS demonstrates Gregor Hohpe's [Loan Broker example](https://www.enterpriseintegrationpatterns.com/ramblings/loanbroker_stepfunctions.html). The sample application implements a [Recipient List](https://www.enterpriseintegrationpatterns.com/patterns/messaging/RecipientList.html) pattern and a [Scatter Gather](https://www.enterpriseintegrationpatterns.com/patterns/messaging/BroadcastAggregate.html) pattern to retrieve a list of banks and dynamically route loan application to multiple banks respectively. The sample application implements the following integration among the various AWS services:
- User submits a loan application with personal data, desired terms, loan amount, and duration.
- Loan Broker fetches information from Credit Bureau and adds it to the loan application submitted earlier.
- Loan Broker routes the application to multiple banks, and the banks reply if they are willing to offer.
- Loan Broker aggregates all the result(s) and returns the result(s) to the user.
Users can deploy this application on LocalStack and AWS with no changes using Cloud Development Kit (CDK). To test this application sample, we will demonstrate how you use LocalStack to deploy the infrastructure on your developer machine and your CI environment.
## Architecture diagram
The following diagram shows the architecture that this sample application builds and deploys:
- [Step Functions](https://docs.localstack.cloud/user-guide/aws/stepfunctions/) to controls the sequence of activities and transfer data between components for the Loan Broker.
- [Lambda](https://docs.localstack.cloud/user-guide/aws/lambda/) functions to implement the business logic for the Loan Broker, Banks and Aggregator in the application.
- [SNS](https://docs.localstack.cloud/user-guide/aws/sns/) to publish messages and broadcasts loan quote requests to any subscribing banks.
- [SQS](https://docs.localstack.cloud/user-guide/aws/sqs/) to ferry loan quotes from the banks to the Aggregator.
- [DynamoDB](https://docs.localstack.cloud/user-guide/aws/dynamodb/) as a key-value and document database to persist the Aggregator's state.
## Prerequisites
- LocalStack Pro with the [`localstack` CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli).
- [Cloud Development Kit](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) with the [`cdklocal`](https://www.npmjs.com/package/aws-cdk-local) installed.
- [AWS CLI](https://docs.localstack.cloud/user-guide/integrations/aws-cli/) with the [`awslocal` wrapper](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal).
- [Node.js](https://nodejs.org/en/download), and [`yarn`](https://yarnpkg.com/).
Start LocalStack Community edition:
```shell
DEBUG=1 localstack start
```
We specified DEBUG=1 to get the printed LocalStack logs directly in the terminal to help us see the event-driven architecture in action. If you prefer running LocalStack in detached mode, you can add the `-d` flag to the `localstack start` command, and use Docker Desktop to view the logs.
## Instructions
You can build and deploy the sample application on LocalStack by running our `Makefile` commands. To deploy the infrastructure, you can run `make deploy` after installing the application dependencies, and run the test steps manually. Here are instructions to deploy and test it manually step-by-step.
### Deploying the application
To create the AWS infrastructure locally, you can use CDK and our `cdklocal` wrapper. Before you can deploy the infrastructure, you need to install the application dependencies:
```sh
yarn
```
To deploy the infrastructure, you can run the following command:
```sh
cdklocal bootstrap
cdklocal deploy --all
```
This will deploy the `LoanBroker-RecipientList-Stack` and `LoanBroker-PubSub-Stack` stacks. You will see the following output:
```sh
Outputs:
LoanBroker-RecipientList-Stack.LoanBrokerArn = arn:aws:states:us-east-1:000000000000:stateMachine:LoanBroker-RecipientList-Stack-LoanBroker641FC9A8-dd79232c
Stack ARN:
arn:aws:cloudformation:us-east-1:000000000000:stack/LoanBroker-RecipientList-Stack/e7929928
```
Take a note of the `LoanBroker-RecipientList-Stack.LoanBrokerArn` output. You will need it to test the application.
## Testing the application
Before you can test the application, you need to pre-populate the `LoanBrokerBanksTable` for the `RecipientsList` stack:
```sh
awslocal dynamodb put-item \
--table-name=LoanBrokerBanksTable \
--item='{ "Type": { "S": "Home" }, "BankAddress": {"L": [ { "S": "BankRecipientPremium" }, { "S": "BankRecipientUniversal" }, { "S": "BankRecipientPawnshop" } ] } }'
```
We can start the State Machine execution to get quotes from the banks after submitting a loan application. Run the following command:
```sh
awslocal stepfunctions start-execution \
--name=cli-test-run \
--state-machine-arn= \
--input="{\"SSN\": \"123-45-6789\", \"Amount\": 500000, \"Term\": 30 }"
```
Replace `` with the `LoanBroker-RecipientList-Stack.LoanBrokerArn` output from the previous step. The result will contain the Execution ARN and the start date:
```sh
{
"executionArn": "arn:aws:states:us-east-1:000000000000:execution:LoanBroker-RecipientList-Stack-LoanBroker641FC9A8-dd79232c:cli-test-run",
"startDate": "2023-04-24T21:08:35.434000+05:30"
}
```
You can use the Execution ARN to see the output of the State Machine execution:
```sh
awslocal stepfunctions describe-execution \
--execution-arn= \
--query="output" | jq -r '. | fromjson'
```
Replace the `` with the `executionArn` output from the previous step. The result will contain the output of the State Machine execution:
```json
{
"SSN": "123-45-6789",
"Amount": 500000,
"Term": 30,
"Credit": {
"Score": 861,
"History": 15
},
"Banks": {
"BankAddress": [
"BankRecipientPremium",
"BankRecipientUniversal",
"BankRecipientPawnshop"
]
},
"Quotes": [
{
"Quote": {
"rate": 3.881919225968371,
"bankId": "Premium"
}
},
{
"Quote": {
"rate": 5.032719931679686,
"bankId": "Universal"
}
},
{
"Quote": {
"rate": 6.019381689166033,
"bankId": "PawnShop"
}
}
]
}
```
## GitHub Action
This application sample hosts an example GitHub Action workflow that starts up LocalStack, builds the Lambda functions, and deploys the infrastructure on the runner. You can find the workflow in the `.github/workflows/main.yml` file. To run the workflow, you can fork this repository and push a commit to the `main` branch.
Users can adapt this example workflow to run in their own CI environment. LocalStack supports various CI environments, including GitHub Actions, CircleCI, Jenkins, Travis CI, and more. You can find more information about the CI integration in the [LocalStack documentation](https://docs.localstack.cloud/user-guide/ci/).
## Contributing
We appreciate your interest in contributing to our project and are always looking for new ways to improve the developer experience. We welcome feedback, bug reports, and even feature ideas from the community.
Please refer to the [contributing file](CONTRIBUTING.md) for more details on how to get started.