# Project plan — lambda_java

Evidence date: 2026-10-10.

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

Inspected revision: `main` at `7055717` (2024-06-24, Dirk, "init"). The scan-host path `~/projects/sonar_scan/repos/lambda_java` was not on this machine. The tree below was read from that git revision. Credential values, sample JWTs, and account numbers that appear as literals in source are omitted here.

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

There is no product requirements document in the source repository and no prior Silicon Ark set for this directory. `IM-CAPITAL-BACKEND-SERVICE/README.md` is still the upstream AWS SAM Java hello-world guide. It names `HelloWorldFunction`, `sam local invoke HelloWorldFunction`, and `mvn test` inside a `HelloWorldFunction` folder. None of those match the code that was committed.

The task-creation scan listed `sonarqube_scan.bat` at the repository root. That file is not in git at `7055717`.

## Product

**Inferred** from the Maven name `IM-CAPITAL backend services.`, the SAM description `IM-CAPITAL-BACKEND-SERVICE`, the Java package `co.ke.imcapital`, and the I&M Bank and Sanlam East Africa HTTP calls.

What the code actually does is a set of AWS Lambda functions behind one API Gateway REST API. The functions:

- store users, sessions, transactions, settings, whitelist rows, and Sanlam member links in MySQL database `IMCapital`;
- call I&M Bank (Keycloak realm `inm-retail`, access-control, OTP, customer, and payment APIs);
- call Sanlam East Africa for tokens, customers, purchases, withdrawals, balances, yields, and statements.

No written statement of product purpose, owner, or audience was found. The payment payload uses `customerType` `RETAIL` and event id prefix `WEALTH_FUND_DEPOSIT_`. Whether this is the I&M wealth-fund channel is **Inferred**.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` (default; `origin/HEAD`) | `7055717` | 2024-06-24 | Only branch. 4 commits, all on 2024-06-24 |

Nothing in git is dated after 2024-06-24. Whether the stacks named in `samconfig.toml` are still deployed is **Unknown / Requires Confirmation**.

| Commit | Date | Author | Subject |
|---|---|---|---|
| `0add845` | 2024-06-24 08:59 UTC | Jaco Brits | Initial commit (`.gitignore` only) |
| `5341c23` | 2024-06-24 09:01 UTC | Jaco Brits | `sonar-project.properties` created online with Bitbucket |
| `371d8a6` | 2024-06-24 09:02 UTC | Jaco Brits | `bitbucket-pipelines.yml` created online with Bitbucket |
| `7055717` | 2024-06-24 15:25 +0200 | Dirk | init — the Java service, SAM template, tests, and a committed `.aws-sam/build` |

## Objectives

No objectives file exists. The behaviour the commits introduced:

1. `0add845` — generic `.gitignore` (Java classes, Maven `target/`, Node `node_modules/`, IDE files). It does not ignore `.aws-sam/`.
2. `5341c23` — Sonar project key `overdrive_lambda_java_429c71b3-ef0b-4a41-9d30-9147798c8de6`. No other Sonar properties.
3. `371d8a6` — Bitbucket pipeline that runs a SonarQube scan on `main` only. No build, test, or deploy step.
4. `7055717` — the IM Capital SAM application: 38 `AWS::Serverless::Function` resources, one API, one REQUEST authorizer, MySQL via Secrets Manager, endpoint URLs via SSM Parameter Store, and JUnit tests.

## Scope

### In scope of `main` at `7055717`

- SAM application `IM-CAPITAL-BACKEND-SERVICE` in `eu-west-1`, Java 17 runtime, 1536 MB, 30 second timeout (45 seconds on `InitiatePayment`).
- API Gateway stage name equal to parameter `Environment` (`dev` or `prod`).
- MySQL database name `IMCapital`, credentials from Secrets Manager secret named by `SECRET_NAME`.
- SSM SecureString parameter names used as integration URLs and client credentials (values are not in git).
- Handler, function, entity, and response classes under `co.ke.imcapital`.
- Unit tests under `src/test/java`.
- `samconfig.toml` deploy profiles `dev` and `prod`.
- Committed SAM build output under `IM-CAPITAL-BACKEND-SERVICE/.aws-sam/`.

### Out of scope / not in this repository

- The MySQL server, schema, and migrations. Table and column names appear only inside SQL strings.
- The Secrets Manager secret resource and the SSM parameters. Only names are referenced.
- The shared IAM role `IMCapital_serverless_deployment`. Functions point at its ARN. The role policy is not in this repo.
- The VPC, subnets, and security group. Ids are hardcoded in `Globals`.
- The caller (web, mobile, or another service). Not named in this tree.
- A custom domain, WAF, or usage plan.
- Application Insights. The resource block at the bottom of `template.yaml` is commented out.

## System shape

```text
Caller (unknown)
    |  Authorization header
    v
API Gateway  IM-CAPITAL-BACKEND-SERVICE
    stage = dev | prod
    default authorizer = MyAuthorizer (REQUEST)
    |
    +-- Authorizer Lambda
    |     reads Authorization
    |     GET IM service agreements (SSM IM_Service_Agreement)
    |     Allow only when a master agreement id is returned
    |
    +-- Route Lambdas (Java 17, VPC)
          |
          +-- MySQL IMCapital  (Secrets Manager: SECRET_NAME)
          +-- SSM Parameter Store eu-west-1 (SecureString names)
          +-- I&M Bank HTTPS (Keycloak, OTP, customer, payment, access control)
          +-- Sanlam East Africa HTTP(S) (token, customer, purchase, withdrawal, balances)
          +-- SQS queue log_queue  --> hourly Lambda --> S3 imcapital-dev-app-logs
```

## Major components

| Component | Where | Role |
|---|---|---|
| SAM template | `IM-CAPITAL-BACKEND-SERVICE/template.yaml` | API, authorizer, functions, VPC, environment |
| Handlers | `src/main/java/co/ke/imcapital/handlers` | API Gateway entry points |
| Functions | `src/main/java/co/ke/imcapital/function` | SQL, HTTP calls, checksum, secrets, SSM |
| Entities | `entity/Customer.java`, `OutputCustomer.java`, `PostalAddress.java` | I&M customer JSON shape |
| Gateway response | `responce/GatewayResponse.java` | status, headers, body for API Gateway |
| Authorizer helpers | `io/AuthPolicy.java`, `io/TokenAuthorizerContext.java` | Present. `AuthPolicy` is not referenced by `Authorizer` |
| Deploy config | `samconfig.toml` | Dev and prod stack names and buckets |
| Pipeline | `bitbucket-pipelines.yml` | SonarQube on `main` |

## Milestones

No milestone plan is in the repository. The only delivery recorded in git is the 2024-06-24 import. `samconfig.toml` distinguishes dev and prod stacks, which is the only environment plan in the tree.

## Known dependencies

- AWS: Lambda, API Gateway, Secrets Manager, SSM, S3, SQS, IAM, VPC (EC2 network interfaces), CloudFormation via SAM.
- Java 17 runtime in the template. Maven compiler settings disagree (see technical documentation).
- Maven dependencies: `aws-lambda-java-core` 1.2.2, `aws-lambda-java-events` 3.11.0, AWS SDK v2 (Secrets Manager, SSM, S3, SQS) 2.21.16, Jackson 2.13.4.1, MySQL connector 8.0.33, OkHttp 4.9.1, Apache Oltu OAuth2 client 1.0.2, commons-codec 1.15.
- External systems: I&M Bank (`imbank.com`, plus a private host `172.24.11.135`) and Sanlam East Africa (`sanlameastafrica.com`, plus `105.27.230.181:3002`).
- Bitbucket Pipelines image `maven:3.3.9` and pipe `sonarsource/sonarqube-scan:2.0.1`.

## Current project status

**Implemented** as a single import on `main`. No later commits. The README does not describe the imported service. Several template handlers do not match classes in source, and several classes are not attached to a template event. Those gaps are listed in `features.md` and `technical-documentation.md`.

## Human confirmation

- Whether `IM-CAPITAL-BACKEND-DEV` and `IM-CAPITAL-BACKEND-PROD` are deployed, and which git revision they run.
- Whether the product owner, audience, and wealth-fund interpretation are correct.
- Whether hardcoded UAT hosts, the dev secret name on the prod parameter path, and committed sample tokens are accepted.
- Whether `sonarqube_scan.bat` existed only on the scan host.