# Setup And Runtime

## Runtime Requirements

The service is designed to run with:

- Python 3.10
- Flask 2.2
- Gunicorn with gevent workers
- MySQL
- AWS S3 access
- AWS CloudWatch Logs access
- PHP CLI for encryption/decryption helper scripts
- `wkhtmltopdf` for PDF generation through `pdfkit`

The Docker image installs PHP and `wkhtmltopdf` because both are runtime dependencies.

## Local Environment

Create and activate a virtual environment outside normal documentation scope. The existing `myenv/` folder is a local environment and should not be documented or committed.

Install dependencies:

```bash
pip install -r requirements.txt
```

The service reads environment variables through `.env` using `python-dotenv` and through direct `os.getenv()` calls. The `.env` file can contain secrets and must not be committed.

## Required Environment Variables

### Flask

| Variable | Purpose |
| --- | --- |
| `HOST` | Host used by `app.py` when running directly |
| `PORT` | Port used by `app.py` when running directly |
| `SECRET_KEY` | App-level secret from config, although `app.py` currently generates a UUID secret at startup |

### MySQL

| Variable | Purpose |
| --- | --- |
| `MYSQL_HOST` | MySQL host |
| `MYSQL_DB` | MySQL database name |
| `MYSQL_USER` | MySQL username |
| `MYSQL_PASSWORD` | MySQL password |
| `MYSQL_PORT` | MySQL port, referenced in config |

`db/database.py` creates a MySQL connection pool named `api_wrapper_pool` with pool size 5.

### AWS And S3

| Variable | Purpose |
| --- | --- |
| `AWS_ACCESS_KEY_ID` | AWS key used by schema loader |
| `AWS_SECRET_ACCESS_KEY` | AWS secret used by schema loader |
| `AWS_REGION_NAME` | AWS region for S3 clients |
| `AWS_BUCKET` | Bucket containing route/auth/endpoint schemas and uploaded files |

### CloudWatch

| Variable | Purpose |
| --- | --- |
| `CLOUDWATCH_ACCESS_KEY` | AWS key used by custom CloudWatch log handler |
| `CLOUDWATCH_SECRET_KEY` | AWS secret used by custom CloudWatch log handler |
| `CLOUDWATCH_GROUP` | Present in config, but the logger currently hardcodes `/aws/api_wrapper` |
| `CLOUDWATCH_STREAM` | Present in config, but the logger currently hardcodes `mconnect` |

### External Integrations

| Variable | Purpose |
| --- | --- |
| `KARZA_URL` | Base URL for Karza APIs |
| `KARZA_ELEC_API_KEY` | API key for Karza electricity verification |
| `karza_api_key` | API key used by Aadhaar OCR/masking flow |
| `Pirimid_Api` | Pirimid upload endpoint |
| `PIRIMID_API_KEY` | Pirimid API key |
| `LENDER_KMGCP_LOGO` | Logo URL used in generated bill validation PDF |

### Business Configuration

| Variable | Purpose |
| --- | --- |
| `SOLAR_CATEGORY_ID` | Category ID used to decide solar category schema path |
| `SSE_COMMENT_TAG_USER_ID` | Comma-separated user IDs used by `StaticFunctions.get_comment_tag()` |
| `CF_ENDPOINT` | Backend endpoint value exposed through config |
| `EMI_CHECKOUT_BE_ENDPOINT` | Checkout/backend endpoint value exposed through config |

## Running Locally

Direct Flask run:

```bash
python app.py
```

(For running in local a few changes need to be made:
    1. In main.py uncomment the local json reading code.
    2. In the authentication.py file, uncomment mconnect source and the ip whitelist code)


This uses `HOST` and `PORT` from the environment.

Gunicorn-style run:

```bash
./gunicorn.sh
```

The script binds to `0.0.0.0:5000` and runs `app:app`.

## Running With Docker

Build:

```bash
docker build -t api-wrapper .
```

Run with an environment file:

```bash
docker run --env-file .env -p 5000:5000 api-wrapper
```

The container entrypoint is `./api-wrapper/gunicorn.sh`.

## External Dependencies Needed For A Real Request

A request cannot complete with only Flask running. The service also needs:

- S3 route schema at `api_wrapper/api/routes.json`
- S3 auth schema at `api_wrapper/authentication/authentication_schema.json`
- matching merchant/category/admin endpoint schema in S3
- reachable MySQL database
- valid auth data in the database for authenticated routes
- external API credentials when a schema calls Karza, Pirimid, or other API operations

## Common Startup Problems

| Symptom | Likely Cause |
| --- | --- |
| Route missing | Route not present for enabled `app_name` in S3 route schema |
| Auth always fails | Host prefix missing from auth schema or DB credential query returns no row |
| Schema loading fails | Wrong S3 path, missing AWS credentials, or missing bucket object |
| DB operations fail | MySQL env vars incorrect or query schema values do not resolve |
| PDF generation fails | `wkhtmltopdf` missing or inaccessible |
| Encryption/decryption fails | PHP CLI missing or PHP script path mismatch |

## Notes For Developers

- Do not commit `.env`.
- Do not edit or document `myenv/`; it is a local dependency environment.
- Treat S3 schema changes as production code changes.
- When adding a new feature, update both endpoint documentation and any changed reference docs.