> ## 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.

# Introduction

> AWS serverless backend for the PayPulse iOS app — invoice ingestion, parsing, and user management via Lambda, API Gateway, DynamoDB, and Terraform.

## What is PayPulse Cloud?

PayPulse Cloud is the serverless AWS backend that powers the [PayPulse iOS app](https://github.com/azfar-imtiaz/PayPulse). 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

<CardGroup cols={2}>
  <Card title="Serverless Lambda functions" icon="bolt">
    13 Lambda functions handle everything from user auth to invoice ingestion, parsing, and notifications — no servers to manage.
  </Card>

  <Card title="Gmail OAuth 2.0" icon="envelope">
    Secure Gmail access using OAuth 2.0 tokens stored in AWS Secrets Manager. Tokens are automatically refreshed as needed.
  </Card>

  <Card title="Automated invoice ingestion" icon="calendar">
    EventBridge triggers the rental invoice fetch every weekday morning. Retail invoices are fetched on demand via API.
  </Card>

  <Card title="Multi-category retail support" icon="bag-shopping">
    Retail invoices are classified across 8 categories: food delivery, clothing, technology, subscriptions, grocery, utility, travel, and miscellaneous.
  </Card>

  <Card title="Terraform infrastructure" icon="cube">
    Modular Terraform setup with separate IAM and Lambda modules — reproducible, version-controlled infrastructure.
  </Card>

  <Card title="JWT authentication" icon="lock">
    All API endpoints (except signup) require a Bearer JWT token returned on login. Tokens encode user ID and email.
  </Card>

  <Card title="iOS push notifications" icon="bell">
    SNS delivers push notifications to the iOS device whenever a new rental invoice is parsed and stored.
  </Card>

  <Card title="Vendor-driven fetching" icon="gear">
    Retail invoice fetching is driven by a VendorConfig DynamoDB table — add new vendors without code changes.
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Deploy the infrastructure and make your first API call in minutes.
  </Card>

  <Card title="Architecture overview" icon="diagram-project" href="/architecture/overview">
    Understand how the components fit together.
  </Card>

  <Card title="Terraform setup" icon="wrench" href="/infrastructure/terraform-setup">
    Configure and apply the Terraform modules.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/auth/signup">
    Explore the full REST API surface.
  </Card>
</CardGroup>