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

# Architecture overview

> How PayPulse Cloud components fit together on AWS.

PayPulse Cloud is a fully serverless AWS backend. There are no application servers to manage — every unit of compute is a Lambda function invoked on demand or on a schedule. Terraform manages the entire infrastructure as code.

## System diagram

```
┌─────────────────────────────────────────────────────────────────────┐
│  iOS App                                                            │
└────────────┬────────────────────────────────────────────────────────┘
             │  HTTPS (JWT Bearer)
             ▼
┌────────────────────────┐
│  API Gateway (HTTP)    │  PayPulseAPI — throttle: 1,000 req/s
│  /v1/...               │
└──────────┬─────────────┘
           │  AWS_PROXY integration
           ▼
┌──────────────────────────────────────────────────────────┐
│  Lambda functions (Python 3.12)                          │
│                                                          │
│  Auth          │  Users         │  Invoices              │
│  ─────────     │  ──────        │  ────────              │
│  signup_user   │  get_user_     │  fetch_invoices        │
│  login_user    │  profile       │  fetch_latest_invoice  │
│  gmail_store_  │  delete_user   │  fetch_retail_invoices │
│  tokens        │                │  parse_invoice (ECR)   │
│                │                │  parse_retail_invoice  │
│                │                │  get_invoices          │
│                │                │  get_rental_invoice    │
│                │                │  delete_retail_invoice │
│                │                │  send_invoice_         │
│                │                │  notification          │
└──────────┬─────────────┬────────┴────────────────────────┘
           │             │
    ┌──────▼──────┐  ┌───▼──────────────────────────────┐
    │  DynamoDB   │  │  S3 (rental-invoices-bucket)     │
    │             │  │                                  │
    │  Users      │  │  invoices/{user_id}/rental/*.pdf │
    │  RentalInv. │  │  invoices/{user_id}/retail/      │
    │  RetailInv. │  │    {sub_type}/*.html             │
    │  VendorConf │  └──────────────┬───────────────────┘
    │  + 8 detail │                 │  s3:ObjectCreated
    │    tables   │          ┌──────▼────────────┐
    └──────┬──────┘          │  parse_invoice    │
           │  DynamoDB       │  (Docker / ECR)   │
           │  stream         └──────────────────┘
    ┌──────▼──────────────────┐
    │  send_invoice_          │
    │  notification Lambda    │
    └──────────┬──────────────┘
               │
          ┌────▼─────────────────────────────┐
          │  SNS (NewInvoiceTopicNotification) │
          │  → email + iOS push              │
          └──────────────────────────────────┘

EventBridge (cron: weekday 08:30 UTC)
  └── fetch_latest_invoice Lambda

EventBridge (weekly cron)
  └── fetch_retail_invoices Lambda
```

## AWS services and their roles

| Service             | Role                                                                                                                                                                                    |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Gateway**     | HTTP API (`PayPulseAPI`) that routes all iOS requests to Lambda. Logs to CloudWatch. Burst limit 5,000 / rate limit 1,000 req/s.                                                        |
| **Lambda**          | 13 Python 3.12 functions covering auth, user management, invoice ingestion, parsing, retrieval, and notifications.                                                                      |
| **DynamoDB**        | 11 tables storing user records, parsed rental invoices, retail invoices (base + 8 detail tables), and vendor configuration.                                                             |
| **S3**              | Two buckets: `rental-invoices-bucket` for invoice files (PDF and HTML), and the Lambda functions bucket for deployment ZIP artifacts.                                                   |
| **EventBridge**     | Scheduled rules trigger `fetch_latest_invoice` (daily, weekday mornings) and `fetch_retail_invoices` (weekly). Also drives the DynamoDB stream mapping for `send_invoice_notification`. |
| **SNS**             | Topic `NewInvoiceTopicNotification` delivers email and iOS push notifications when a new rental invoice is parsed.                                                                      |
| **Cognito**         | Identity pool (`WallenstamAppIdentityPool`) provides unauthenticated guest credentials for iOS push notification registration.                                                          |
| **Secrets Manager** | Stores Gmail OAuth 2.0 tokens per user (`gmail/user/{user_id}`) and the Google OAuth client ID.                                                                                         |
| **CloudWatch**      | Log groups for every Lambda function and for API Gateway. Detailed metrics and data tracing enabled.                                                                                    |

## Detail pages

<CardGroup cols={2}>
  <Card title="Lambda functions" icon="bolt" href="/architecture/lambda-functions">
    Full reference for all 13 Lambda functions, layers, and deployment methods.
  </Card>

  <Card title="Data storage" icon="database" href="/architecture/data-storage">
    DynamoDB table schemas and S3 bucket structure.
  </Card>

  <Card title="Event flow" icon="arrow-right-arrow-left" href="/architecture/event-flow">
    Step-by-step pipelines for rental and retail invoice ingestion.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/auth/signup">
    Interactive reference for every REST endpoint.
  </Card>
</CardGroup>