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.

​
Prerequisites

Before you begin, make sure you have the following installed and configured:
  • AWS CLI — authenticated with credentials that have permissions to create IAM roles, Lambda functions, API Gateway, DynamoDB tables, S3 buckets, Secrets Manager secrets, SNS topics, EventBridge rules, CloudWatch log groups, and Cognito identity pools
  • Terraform >= 1.5.0
  • Python 3.12 (matches the Lambda runtime)
  • An AWS account with sufficient service limits for the resources above
The infrastructure deploys to eu-west-1 by default. You can override this by setting aws_region in your terraform.tfvars.

​
Steps

1

Clone the repository

Clone the PayPulse Cloud repository and navigate into the Terraform directory:
git clone https://github.com/azfar-imtiaz/PayPulse-Cloud.git
cd PayPulse-Cloud/aws-infra-terraform
2

Configure terraform.tfvars

Create a terraform.tfvars file in the aws-infra-terraform/ directory. This file is gitignored and must never be committed.
terraform.tfvars contains sensitive secrets. Confirm that .gitignore excludes it before adding any values.
The following variables have no default and must be provided in terraform.tfvars:
VariableTypeDescription
gmail_secret_credentialsstring (JSON)Gmail access credentials stored in Secrets Manager
google_oauth_client_idstringGoogle OAuth client ID for Gmail API access via the iOS app
gemini_api_keystringAPI key for the Gemini Flash API used in retail invoice parsing
A minimal terraform.tfvars looks like this:
terraform.tfvars
gmail_secret_credentials = "{\"access_token\": \"...\", \"refresh_token\": \"...\"}"
google_oauth_client_id   = "YOUR_GOOGLE_OAUTH_CLIENT_ID"
gemini_api_key           = "YOUR_GEMINI_API_KEY"
All other variables have sensible defaults (for example, aws_region = "eu-west-1", python_runtime = "python3.12"). You can override any of them here if needed.
Before applying Terraform, create the PayPulseAppJWTSecret secret manually in AWS Secrets Manager. Terraform reads this secret with a data source — it does not create it.
3

Initialize and apply Terraform

Run the standard Terraform workflow from inside aws-infra-terraform/:
terraform init
Review the planned changes before applying:
terraform plan
Apply the infrastructure:
terraform apply
When the apply completes, Terraform prints the API Gateway invoke URL:
Outputs:

paypulse_api_url = "https://<id>.execute-api.eu-west-1.amazonaws.com"
Export this URL for use in the steps below:
export API_URL="https://<id>.execute-api.eu-west-1.amazonaws.com"
4

Sign up

Create a new user account by sending a POST request to /v1/auth/signup. The request body must include email, name, and password:
curl -X POST "$API_URL/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "name": "Your Name",
    "password": "your-secure-password"
  }'
A successful response returns HTTP 201 with a JWT access token:
{
  "message": "Signup successful!",
  "data": {
    "username": "Your Name",
    "access_token": "eyJ...",
    "token_type": "Bearer"
  }
}
User IDs are generated automatically as UUIDs prefixed with user_. The access token is valid immediately after signup — you do not need to log in separately.
5

Log in and get a JWT token

If you already have an account, exchange your credentials for a JWT token:
curl -X POST "$API_URL/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'
A successful response returns HTTP 200:
{
  "message": "Login successful!",
  "data": {
    "username": "Your Name",
    "access_token": "eyJ...",
    "token_type": "Bearer"
  }
}
Export the token for subsequent requests:
export TOKEN="eyJ..."
Tokens are short-lived. If a protected endpoint returns 401, log in again to obtain a fresh token.
6

Make an authenticated request

With a valid token, you can call any protected endpoint. Retrieve the authenticated user’s profile:
curl -X GET "$API_URL/v1/user/me" \
  -H "Authorization: Bearer $TOKEN"
The response includes the user’s name, email, account creation date, and Gmail connection status:
{
  "data": {
    "name": "Your Name",
    "email": "you@example.com",
    "created_at": "2025-01-01T00:00:00Z",
    "gmail_account_connected": false
  }
}
The gmail_account_connected field indicates whether the user has linked their Gmail account via the OAuth 2.0 flow. Until Gmail is connected, invoice ingestion endpoints will not have access to the inbox.

​
Next steps

Architecture overview

Understand how Lambda, API Gateway, DynamoDB, S3, and EventBridge fit together.

API reference

Explore all available endpoints with request and response schemas.

Gmail OAuth setup

Connect a Gmail account so invoice ingestion can access the inbox.

Terraform setup

Learn about all Terraform modules and how to customize the deployment.

Build docs developers (and LLMs) love

Get started for freeTalk to us