Pecuniary

Getting Started | Architecture | Development | Trello | Resources

An event-driven serverless microservices application built with Node.js
⚠️ NOTE ⚠️ The Event Sourcing and CQRS version is no longer maintained. Please see branch and CQRS Architecture for the last release.

Getting Started

This quick start guide describes how to get the application running. An AWS account is required to deploy the infrastructure required for this project.

Configure the app

1. Clone the project

   $ git clone https://github.com/eric-bach/pecuniary.git

2. Install dependencies for CDK

   $ cd ./infrastructure
   $ npm install

3. Install dependencies for the rest of the application using the recursive-install script

   $ cd ./infrastructure
   $ npm cinstall-all

4. Copy the ./infrastructure/.env.example file to ./infrastructure/.env and fill in the parameter values (if the app has not been deployed to AWS yet, the ARN will be empty for now):

   DLQ_NOTIFICATIONS - email address to send failed event message notifications to.
   

5. Copy the ./frontend/app/aws-exports.js.example file to ./frontend/app/aws-exports.js and fill in the parameter values from the CDK stack outputs in step 2:

   const awsmobile = {
     aws_project_region: 'AWS_REGION',
     aws_cognito_region: 'AWS_REGION',
     aws_user_pools_id: 'USER_POOL_ID',
     aws_user_pools_web_client_id: 'USER_POOL_CLIENT_ID',
     mandatorySignIn: true,
     aws_appsync_graphqlEndpoint: 'APPSYNC_ENDPOINT',
     aws_appsync_region: 'AWS_REGION',
     aws_appsync_authenticationType: 'AMAZON_COGNITO_USER_POOLS',
   };
   export default awsmobile;
   

6. Copy the ./frontend/prod.config.example file to ./frontend/prod.config and fill in the parameter values from existing Certificate and Route53 resources. If these do not exist from a prior app, create new instances.

   {
     "certificateArn": "",
     "hostedZoneId": "",
     "hostedZoneName": ""
   }
   

Deploy the app

1. Follow the steps in Deployment with CDK CLI

Running the app locally

1. Start the frontend:

   $ cd frontend
   $ npm run dev

Deployment

Deployment with CDK CLI

The Pecuniary application consists of the CDK backend and React frontend, each of which has an independent method of deploying. The backend is deployed via CDK where the frontend is deployed via SST.

Deploy backend via CDK script

1. Bootstrap CDK (one-time only)

   $ cdk bootstrap aws://{ACCOUNT_ID}/{REGION} --profile {PROFILE_NAME}}
   

2. Ensure AWS credentials are up to date. If using AWS SSO, authorize a set of temporary credentials

   aws sso login --profile PROFILE_NAME

3. Deploy the backend and frontend

   $ npm run deploy dev PROFILE_NAME
   

Deployment via GitHub Actions

1. Create an AWS role that can be assumed by GitHub Actions

   $ npm run deploy-cicd prod PROFILE_NAME
   

2. Add the following GitHub Secrets to the repository

   Common

   CDK_DEFAULT_REGION - AWS default region for all resources to be created
   

   Dev environment

   CLOUDFRONT_DOMAIN_DEV - AWS CloudFront Distribution domain name
   COGNITO_USERPOOL_ID_DEV - Cognito User Pool Id
   COGNITO_WEB_CLIENT_ID_DEV - Cognito User Pool Client Id
   APPSYNC_ENDPOINT_DEV - AWS AppSync GraphQL endpoint URL
   CYPRESS_USERNAME - A valid Cognito username for Cypress integration testing
   CYPRESS_PASSWORD - The Cognito password for Cypress integration testing
   

   Production environment

   AWS_SERVICE_ROLE_PROD - AWS ARN of the GitHub Actions Role to Assume (from step 1)
   CERTIFICATE_ARN - ARN to ACM certificate for CloudFront Distribution
   HOSTED_ZONE_ID - Route53 Hosted Zone ID
   HOSTED_ZONE_NAME - Route53 Hosted Zone Name
   DLQ_NOTIFICATIONS - email address to send DLQ messages to
   CLOUDFRONT_DOMAIN_PROD - AWS CloudFront Distribution domain name
   COGNITO_USERPOOL_ID_PROD - Cognito User Pool Id
   COGNITO_WEB_CLIENT_ID_PROD - Cognito User Pool Client Id
   APPSYNC_ENDPOINT_PROD - AWS AppSync GraphQL endpoint URL
   

Testing

Jest

To be added

Cypress

To be added

Locally

Test the frontend using cypress

$ npm run cypress:open

or headless,

$ npm run cypress:run

GitHub Actions

Ensure to configure the GitHub Secrets to include:

```
CYPRESS_USERNAME - A valid Cognito username for Cypress integration testing
CYPRESS_PASSWORD - The Cognito password for Cypress integration testing
```

Event Sourcing and CQRS Architecture

For more detailed information about the event-driven nature of the Pecuniary application and it's architecture, please see the Architecture.md

Projects References

Links to additional documentation specific to the Application

AppSync

• Saved GraphQL queries/mutations for GraphiQl
• How to add a new GraphQL API/Command Handler
• How to call an authenticated AppSync GraphQL API with Apollo Client

Resources

Various links to additional articles/tutorials used to build this application.

AppSync

• How to build an authenticated GraphQL AppSync API with CDK
• How to perform a GraphQL Query with Apollo using React hooks
• How to perform a GraphQL Mutation with Apollo using React hooks

Cognito

• How to add a protected route to React
• How to authenticate with Cognito using React hooks
• How to add a user to a Cognito User Group

License

This project is licensed under the terms of the MIT license.