# S3 Integration

## Purpose

S3 is central to this service. It stores the JSON schemas that define routes, authentication, endpoint behavior, validation, rules, functions, persistence, and responses.

It is also used for file uploads from schema operations and generated integration reports.

## Implementation

Main file:

```text
utilities/schema_loader.py
```

Main class:

```text
SchemaLoad
```

## Configuration

| Variable | Purpose |
| --- | --- |
| `AWS_ACCESS_KEY_ID` | AWS key used for S3 session |
| `AWS_SECRET_ACCESS_KEY` | AWS secret used for S3 session |
| `AWS_REGION_NAME` | AWS region used by some direct S3 clients |
| `AWS_BUCKET` | Bucket containing schemas and uploaded objects |

## Schema Reads

`SchemaLoad.s3_read_file(file_path)` reads an S3 object and returns its UTF-8 decoded body.

`SchemaLoad.read_schema(path)` loads the S3 object and parses it as JSON.

Important schema paths:

```text
api_wrapper/api/routes.json
api_wrapper/authentication/authentication_schema.json
api_wrapper/merchant/{merchant_id}/{domain}/{merchant_name}.json
api_wrapper/category/{category_id}/{domain}/{category_name}.json
api_wrapper/{source}/{domain}/category/default/default.json
```

## Existence Checks

`SchemaLoad.s3_check_exists(file_path)` uses S3 `head_object()` to check whether a schema exists.

This is used during endpoint schema selection:

1. Check merchant-level schema.
2. If missing, check category-level schema.

## Uploads

`s3_upload_service(content, file_path)` base64-decodes `content` and uploads it to `file_path` in the configured bucket.

Schema operation:

```json
{
  "operation": "s3Upload",
  "contentKey": "$request.file_content",
  "path": "$request.file_path",
  "stateKey": "upload_status"
}
```

## Other S3 Usage

Additional direct S3 clients are used in:

- `integrations/karza.py` for bill validation PDF reports
- `static_functions.py` for Aadhaar masking outputs and fallback uploads

## Failure Modes

| Symptom | Likely Cause |
| --- | --- |
| Route not registered | `routes.json` missing or app group not configured |
| Auth fails for all requests | auth schema missing domain or unreadable |
| Endpoint fails after auth | merchant/category/admin schema path missing |
| Upload status false | invalid base64 content, bad path, bucket permission issue |
| Generated report missing | S3 put failure or missing AWS region/bucket |

## Documentation Requirement

When adding or moving schemas, update:

- `documentation/schemas.md`
- the endpoint doc under `documentation/endpoints/`
- this file if the S3 path convention changes