# Project plan — lambda (IM Capital backend)

Evidence date: 2026-09-28.

Source repository: `git@bitbucket.org:overdrive/lambda.git`.

Inspected revision: `master` at `dfb4dca` (2024-02-02, Dirk, "adding settings api"). The scan-host path `~/projects/sonar_scan/repos/lambda` was not on this machine. The tree below was read from that git revision. Credential values, bearer tokens, cookies, and client secrets are omitted from this document.

This plan describes what the repository contains. It does not decide what the product should become.

## Product

There is no product requirements document in the repository. The names used in code and deployment config are **IM-CAPITAL-BACKEND-SERVICE** and **IM Capital**.

The runnable behaviour is a set of AWS Lambda functions that sit between a caller (not in this repository) and:

- I&M Bank digital-experience APIs (`imbank.com` hosts, plus internal Fiorano-style hosts).
- Sanlam East Africa investment APIs (login, members, statements, customers, purchases, withdrawals, balances, yields).
- A MySQL database named `IMCapital`.

Provenance: **Inferred** from function names, URLs, and SQL. No written statement of product purpose was found.

Public payment constants in `functions/IMInitatePayment.java` name the counterparty bank **I & M Bank Ltd**, BIC `IMBLKEN0XXX`, customer type `RETAIL`, and transfer type `within-retail`. Provenance: **Implemented**.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `dfb4dca` | 2024-02-02 | Only branch. 33 commits from 2023-01-23 to 2024-02-02 |

No other local or remote branches were present at inspection.

History falls into two stretches:

- 2023-01-23 to 2023-06-08 — Node.js Serverless functions for an I&M token flow and Sanlam statement / subgroup calls. Authors: Jaco Brits, liam-ovd.
- 2023-09-18 to 2024-02-02 — Java SAM application added and expanded (users, OTP, payments, Sanlam purchase and withdrawal, settings, log export). Author of the application commits: Dirk. Sonar properties and the pipeline file were edited by Jaco Brits.

The last commit, `dfb4dca`, adds `GET /getsettings`.

**Discrepancy:** the task-creation scan listed `sonarqube_scan.bat` at the repository root. That file is not in git history. Provenance: **Unknown** — it may have been an untracked file on the scan host.

## Objectives (inferred from the implementation, not from a written plan)

- Obtain an I&M Bank access token and establish a user context (service agreement) so account data can be read.
- Register an IM Capital user locally and link that user to a Sanlam member number.
- Record a local transaction, then create a Sanlam purchase or withdrawal and mark the local transaction `complete`.
- Start an I&M within-bank transfer, with a one-time password (OTP) and a preferred second factor.
- Read settings, whitelist status, statements, balances, yields, and profile images for the caller.
- Write application logs to MySQL and copy them to S3 on a schedule.

## Scope

### In scope of `master`

Three deployable trees live side by side:

1. Root Node.js Serverless Framework service (`serverless.yml`, `handler.js`, `token_check.js`, `sanlam_statement_data.js`, `sanlam_subgroup_members.js`).
2. Kotlin / Java 11 Serverless service under `Java/IM-CAPITAL-BACKEND-SERVICE-JAVA/`. It exposes the same four behaviours on `*Java` paths.
3. AWS SAM Java service under `SAM/IM-CAPITAL-BACKEND-SERVICE/`. This is the wide API (users, payments, Sanlam orders, settings, scheduled log export).

Also in scope: Bitbucket Pipelines SonarQube scan, `sonar-project.properties`, and one Node invoke fixture at `test/token_check.json`.

### Out of scope / not in this repository

- The client that calls these APIs. An IAM role trusts `amplify.amazonaws.com`. Whether an Amplify app is that client is **Unknown / Requires Confirmation**.
- The MySQL server and its schema migrations. Connection details come from AWS Secrets Manager. The database is not in git.
- The Parameter Store values behind the SSM names. Only the parameter names are in source.
- A written backlog, milestone plan, or owner for which of the three stacks is the one that should be deployed.

## System architecture

```text
Caller (unknown; Amplify trust exists)
        |
        v
API Gateway  IM-CAPITAL-BACKEND-SERVICE
stage = dev | prod          region eu-west-1
        |
        +-- Node Serverless (stage hardcoded DEV) ---- I&M test host, Sanlam :3002
        +-- Kotlin Serverless (stage dev) ------------ same four calls
        +-- SAM Java 17 functions
                |
                +-- Secrets Manager -> MySQL database IMCapital
                +-- SSM Parameter Store (URLs and keys)
                +-- I&M Bank APIs (token, agreements, OTP, payments, statements)
                +-- Sanlam East Africa APIs
                +-- S3 bucket imcapital-dev-app-logs (hourly export)
```

All three stacks place functions in the same VPC security group and the same two subnets, and name the same deployment bucket family (`imcapital-dev-lambda-deployment`, plus a prod bucket in `samconfig.toml`).

Which stack is actually serving traffic is **Unknown / Requires Confirmation**. The SAM tree is the only one with a prod stack name, the later features, and the last commit.

## Major components

| Component | Location | Role |
|---|---|---|
| Node token and Sanlam callers | repository root | Four HTTP GET functions |
| Kotlin port | `Java/IM-CAPITAL-BACKEND-SERVICE-JAVA/` | Same four functions, `*Java` paths, Java 11 |
| SAM template | `SAM/IM-CAPITAL-BACKEND-SERVICE/template.yaml` | API Gateway, ~30 functions, hourly schedule |
| Java handlers | `SAM/.../src/main/java/` | Request handlers plus `functions/` and `SanlamFunctions/` |
| Shared DB access | `functions/GetConnection.java`, `GetSecret.java` | Secrets Manager JSON to JDBC |
| Shared config | `functions/GetParameter.java` | SSM SecureString lookup in `eu-west-1` |
| Log export | `WriteS3Logs` | EventBridge rate of 1 hour |

## Milestones visible in git

No milestone document exists. The commit subjects are the only timeline:

| When | Commit | What landed |
|---|---|---|
| 2023-01-23 | `8c4c65b` | Initial commit |
| 2023-05-29 to 2023-05-30 | `5176d44`, `04eed14` | Token flow, Sanlam statement data, subgroup members |
| 2023-06-08 | `b01d291`, `ce03d50` | Token check; Sonar pipeline |
| 2023-09-20 | `152673d`, `5380b20` | Java `getToken`, then "all functions" |
| 2023-11-07 to 2023-11-09 | `4a9c301` onward | SAM functions, account balance, service agreement, profile image |
| 2023-11-23 to 2023-12-08 | `e045781`, `2141f59`, `ddaa918` | Sanlam functions, purchase flow, OTP, withdrawal flow |
| 2024-01-09 to 2024-01-29 | `d9640cb`, `fcc11ad`, `5ed24ea` | Logging and further function updates |
| 2024-02-02 | `dfb4dca` | Settings API. Last commit on `master` |

Nothing in git after 2024-02-02. Current status: **inactive in this repository since that date**. Whether a deployed stack is still in use is **Unknown / Requires Confirmation**.

## Known dependencies

- AWS account `597707462019`, region `eu-west-1`.
- IAM role `IMCapital_serverless_deployment` (referenced by all three stacks; the policy document for that role is not in git).
- Deployment buckets `imcapital-dev-lambda-deployment` and `imcapital-prod-lambda-deployment`.
- Secrets Manager secret name `imcapital-dev-mysql-aurora` (set as `SECRET_NAME` on every SAM function, including the prod configuration block).
- MySQL 8 connector, database name `IMCapital`.
- Node 18 dependencies: `axios`, `qs`, `express`, `serverless-http`, `serverless-offline`.
- Java: AWS Lambda Java core, Jackson, AWS SDK v2 (Secrets Manager, SSM, S3), OkHttp, MySQL connector. SAM runtime is Java 17. The Maven compiler target is 1.8. The Kotlin project targets Java 11.
- Bitbucket Pipelines image `maven:3.3.9` running only the SonarQube scan pipe.

## Implementation plan

No forward plan is written in the repository. The implemented sequence, read from history, was: Node proof of the token and Sanlam calls, a Kotlin port of those four calls, then a SAM Java API that absorbed and extended them.

## Open items that block a single description of "the" system

- Which tree is deployed to dev, and whether prod (`IM-CAPITAL-BACKEND-PROD`) was ever deployed.
- Why `SECRET_NAME` and the S3 log bucket stay on the **dev** names inside the shared SAM globals and `WriteLogsToS3.java`.
- Why `TokenCheck` in Java has the I&M calls commented out, while the Node `token_check.js` still performs them.
- Who the caller is, and whether API Gateway IAM auth as written in the template is what clients use.