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

# Quickstart

> Deploy the PayPulse Cloud infrastructure and make your first API call.

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

<Note>
  The infrastructure deploys to `eu-west-1` by default. You can override this by setting `aws_region` in your `terraform.tfvars`.
</Note>

## Steps

<Steps>
  <Step title="Clone the repository">
    Clone the PayPulse Cloud repository and navigate into the Terraform directory:

    ```bash theme={null}
    git clone https://github.com/azfar-imtiaz/PayPulse-Cloud.git
    cd PayPulse-Cloud/aws-infra-terraform
    ```
  </Step>

  <Step title="Configure terraform.tfvars">
    Create a `terraform.tfvars` file in the `aws-infra-terraform/` directory. This file is **gitignored** and must never be committed.

    <Warning>
      `terraform.tfvars` contains sensitive secrets. Confirm that `.gitignore` excludes it before adding any values.
    </Warning>

    The following variables have no default and **must** be provided in `terraform.tfvars`:

    | Variable                   | Type          | Description                                                     |
    | -------------------------- | ------------- | --------------------------------------------------------------- |
    | `gmail_secret_credentials` | string (JSON) | Gmail access credentials stored in Secrets Manager              |
    | `google_oauth_client_id`   | string        | Google OAuth client ID for Gmail API access via the iOS app     |
    | `gemini_api_key`           | string        | API key for the Gemini Flash API used in retail invoice parsing |

    A minimal `terraform.tfvars` looks like this:

    ```hcl terraform.tfvars theme={null}
    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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Initialize and apply Terraform">
    Run the standard Terraform workflow from inside `aws-infra-terraform/`:

    ```bash theme={null}
    terraform init
    ```

    Review the planned changes before applying:

    ```bash theme={null}
    terraform plan
    ```

    Apply the infrastructure:

    ```bash theme={null}
    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:

    ```bash theme={null}
    export API_URL="https://<id>.execute-api.eu-west-1.amazonaws.com"
    ```
  </Step>

  <Step title="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`:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "message": "Signup successful!",
      "data": {
        "username": "Your Name",
        "access_token": "eyJ...",
        "token_type": "Bearer"
      }
    }
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Log in and get a JWT token">
    If you already have an account, exchange your credentials for a JWT token:

    ```bash theme={null}
    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`:

    ```json theme={null}
    {
      "message": "Login successful!",
      "data": {
        "username": "Your Name",
        "access_token": "eyJ...",
        "token_type": "Bearer"
      }
    }
    ```

    Export the token for subsequent requests:

    ```bash theme={null}
    export TOKEN="eyJ..."
    ```

    <Warning>
      Tokens are short-lived. If a protected endpoint returns `401`, log in again to obtain a fresh token.
    </Warning>
  </Step>

  <Step title="Make an authenticated request">
    With a valid token, you can call any protected endpoint. Retrieve the authenticated user's profile:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Architecture overview" icon="diagram-project" href="/architecture/overview">
    Understand how Lambda, API Gateway, DynamoDB, S3, and EventBridge fit together.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/auth/signup">
    Explore all available endpoints with request and response schemas.
  </Card>

  <Card title="Gmail OAuth setup" icon="envelope" href="/gmail-oauth/overview">
    Connect a Gmail account so invoice ingestion can access the inbox.
  </Card>

  <Card title="Terraform setup" icon="wrench" href="/infrastructure/terraform-setup">
    Learn about all Terraform modules and how to customize the deployment.
  </Card>
</CardGroup>