Skip to main content

​
What is PayPulse Cloud?

PayPulse Cloud is the serverless AWS backend that powers the PayPulse iOS app. It fetches rental and retail invoices from a Gmail inbox using OAuth 2.0, parses them, stores the extracted data in DynamoDB, and exposes a REST API consumed by the mobile app. The entire infrastructure is defined and managed as code using Terraform, with modular organization for IAM, Lambda functions, DynamoDB tables, API Gateway, S3 buckets, EventBridge, SNS, and CloudWatch.

​
Key features

Serverless Lambda functions

13 Lambda functions handle everything from user auth to invoice ingestion, parsing, and notifications — no servers to manage.

Gmail OAuth 2.0

Secure Gmail access using OAuth 2.0 tokens stored in AWS Secrets Manager. Tokens are automatically refreshed as needed.

Automated invoice ingestion

EventBridge triggers the rental invoice fetch every weekday morning. Retail invoices are fetched on demand via API.

Multi-category retail support

Retail invoices are classified across 8 categories: food delivery, clothing, technology, subscriptions, grocery, utility, travel, and miscellaneous.

Terraform infrastructure

Modular Terraform setup with separate IAM and Lambda modules — reproducible, version-controlled infrastructure.

JWT authentication

All API endpoints (except signup) require a Bearer JWT token returned on login. Tokens encode user ID and email.

iOS push notifications

SNS delivers push notifications to the iOS device whenever a new rental invoice is parsed and stored.

Vendor-driven fetching

Retail invoice fetching is driven by a VendorConfig DynamoDB table — add new vendors without code changes.

​
Architecture at a glance

iOS App
  │
  ├── POST /v1/auth/signup|login          → signup_user / login_user Lambda
  ├── POST /v1/auth/gmail/store-tokens    → gmail_store_tokens Lambda
  ├── GET  /v1/invoices/{type}            → get_invoices Lambda → DynamoDB
  ├── POST /v1/invoices/{type}/ingest     → fetch_invoices Lambda → Gmail API → S3
  └── POST /v1/invoices/retail/ingest     → fetch_retail_invoices Lambda → Gmail API → S3

EventBridge (weekday 08:30)
  └── fetch_latest_invoice Lambda → Gmail API → S3
        └── S3 event → parse_invoice Lambda → DynamoDB
              └── DynamoDB stream → send_invoice_notification Lambda → SNS → iOS

​
Repository structure

PayPulse-Cloud/
├── lambdas/
│   ├── auth/          # gmail_store_tokens
│   ├── invoices/      # fetch, parse, get, ingest lambdas
│   └── users/         # signup, login, get_user_profile, delete_user
├── lambda_layers/
│   ├── common/python/utils/        # shared utilities (auth, JWT, DynamoDB, S3, OAuth, Gmail)
│   └── gemini_parsers/python/      # Gemini-based retail invoice parsers per category
├── aws-infra-terraform/
│   ├── iam/           # IAM roles and policies per Lambda
│   ├── lambdas/       # Lambda function Terraform definitions
│   ├── api_gateway.tf
│   ├── dynamodb.tf
│   ├── s3.tf
│   ├── eventbridge.tf
│   ├── sns.tf
│   ├── cognito.tf
│   └── cloudwatch.tf
└── vendor_configs/    # JSON configs for retail invoice vendors

​
Get started

Quickstart

Deploy the infrastructure and make your first API call in minutes.

Architecture overview

Understand how the components fit together.

Terraform setup

Configure and apply the Terraform modules.

API Reference

Explore the full REST API surface.