Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/azfar-imtiaz/PayPulse-Cloud/llms.txt

Use this file to discover all available pages before exploring further.

PayPulse Cloud uses 13 Lambda functions written in Python 3.12. They are organized into three groups: auth, users, and invoices.

​
Function reference

FunctionFunction nameTriggerDescriptionDeployment
Loginlogin_userAPI GatewayAuthenticates an existing user and returns a JWT access token.Zip to S3
Sign upsignup_userAPI GatewayRegisters a new user in PayPulse.Zip to S3
Get user profileget_user_profileAPI GatewayReturns the authenticated user’s profile: name, email, creation date, and Gmail connection status.Zip to S3
Store Gmail tokensgmail_store_tokensAPI GatewayPersists OAuth 2.0 tokens received from the iOS app into AWS Secrets Manager for Gmail API access.Zip to S3
Ingest all rental invoicesfetch_invoicesAPI GatewayFetches all rental invoice PDFs from the user’s Gmail inbox and uploads them to S3.Zip to S3
Ingest latest rental invoicefetch_latest_invoiceEventBridge (weekday 08:30)Checks Gmail for the current month’s rental invoice and uploads it to S3 if not already ingested.Zip to S3
Ingest retail invoicesfetch_retail_invoicesAPI Gateway + EventBridge (weekly)Fetches retail invoice HTML files from Gmail using VendorConfig-driven search. Supports custom date ranges.Zip to S3
Parse invoiceparse_invoiceS3 (s3:ObjectCreated on .pdf)Downloads a newly uploaded rental invoice PDF, parses it with HyresaviParser, and writes the result to DynamoDB.Docker image to ECR
Get invoicesget_invoicesAPI GatewayReturns rental or retail invoices for the authenticated user. Supports sub-type filtering, detail lookup by invoice ID, and invoice counts via query parameters.Zip to S3
Get invoiceget_rental_invoiceAPI GatewayReturns full details for a single invoice by ID. Not currently used by the iOS app.Zip to S3
Delete userdelete_userAPI GatewayDeletes all data for a given user from PayPulse Cloud.Zip to S3
Parse retail invoiceparse_retail_invoiceS3 (s3:ObjectCreated on .html)Downloads a newly uploaded retail invoice HTML file, extracts structured data using the Gemini Flash API, and writes the result to the RetailInvoices base table and the corresponding category detail table.Zip to S3
Send invoice notificationsend_invoice_notificationDynamoDB stream (RentalInvoices)Publishes an SNS notification (email + iOS push) whenever a new rental invoice record is inserted.Zip to S3
get_rental_invoice is deployed and reachable at GET /v1/invoices/{type}/{invoice_id} but is not currently called by the iOS app.

​
Lambda layers

Shared dependencies are distributed as Lambda layers so each function only packages its own logic.

​
utils-layer

The common utilities layer contains all shared Python modules used across multiple functions:
ModulePurpose
auth_utils.pyRequest authentication helpers
dynamodb_utils.pyDynamoDB read/write helpers
jwt_utils.pyJWT token creation and validation
s3_utils.pyS3 download and upload helpers
secretsmanager_utils.pySecrets Manager access, including OAuth token storage and retrieval
oauth_utils.pyOAuth 2.0 token validation and refresh logic
gmail_api_utils.pyGmail API service creation, email search, and attachment processing
error_handling.pyCentralized error handling
responses.pyStandardized HTTP response builders
exceptions.pyCustom exception classes
To update the layer, regenerate lambda_layers/common/utils_layer.zip and run terraform apply.

​
pyjwt-layer

Contains the PyJWT package. Attached to functions that issue or validate JWT tokens.

​
bcrypt-layer

Sourced from Klayers — a community-maintained repository of pre-built Lambda layer ARNs. Attached to signup_user and login_user for password hashing.

​
google-api-layer

Contains the Google API Python client library. Attached to functions that call the Gmail API (fetch_invoices, fetch_latest_invoice, fetch_retail_invoices, gmail_store_tokens).

​
gemini-parsers-layer

Contains Google Gemini client libraries and per-category parser classes used by parse_retail_invoice for AI-assisted retail invoice parsing. Parsers are available for: food delivery, clothing, technology, subscriptions, grocery, utility, miscellaneous, and travel sub-types.

​
Deployment methods

​
Zip upload to S3

Most functions are packaged as ZIP archives and stored in the Lambda functions S3 bucket. Terraform reads the object version from S3 and updates the Lambda function when a new version is uploaded. 
resource "aws_lambda_function" "fetch_latest_invoice" {
  s3_bucket         = var.lambda_bucket_id
  s3_key            = "fetch_latest_invoice.zip"
  s3_object_version = data.aws_s3_bucket_object.fetch_latest_invoice_zip.version_id
  ...
}
To redeploy a ZIP-based function:
  1. Update the source code.
  2. Rebuild the ZIP and upload it to the Lambda functions S3 bucket.
  3. Run terraform apply — Terraform detects the new S3 object version and updates the function.

​
Docker image to ECR (parse_invoice only)

parse_invoice uses a Docker image published to Amazon ECR. This is because its PDF parsing dependency (HyresaviParser) and its transitive requirements exceed the 250 MB unzipped Lambda limit. 
resource "aws_lambda_function" "parse_invoice" {
  package_type = "Image"
  image_uri    = "<account_id>.dkr.ecr.<region>.amazonaws.com/wallenstam/invoice-parser:<tag>"
  timeout      = 60
  ...
}
To redeploy parse_invoice:
  1. Build a new Docker image from lambdas/invoices/parse_invoice/Dockerfile.
  2. Tag and push to ECR.
  3. Update image_uri in lambda_parse_invoice.tf with the new tag.
  4. Run terraform apply.
The ECR image tag in lambda_parse_invoice.tf must be updated manually on every build. Forgetting this step means Terraform will not re-deploy the function.

Build docs developers (and LLMs) love

Get started for freeTalk to us