# Project plan — unity-lambda-api

Evidence date: 2026-09-30.

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

Inspected revision: `master` at `fe4b095` (2021-03-17, Joshua Gatley-Dewing, "Calendar api changes"). The scan-host path `~/projects/sonar_scan/repos/unity-lambda-api` was not on this machine. The tree below was read from that git revision. No database password is stored in git. Mock files contain identity identifiers and a client spreadsheet; those values 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. `README.md`, `package.json`, and `LICENSE` are still the upstream [Serverless Node.js Starter](https://github.com/AnomalyInnovations/serverless-nodejs-starter) (copyright 2017 Anomaly Innovations, MIT). They describe a `hello` demo, not the Unity routes.

Silicon Ark already has other Unity-named directories (`unityNodejsApi`, `unity-skeleton`, `unity-soft-ui`, `unity-lite`, `unity-salestracker`). This repository does not name them. Whether they are one product is **Unknown / Requires Confirmation**.

## Product

**Inferred** from the Serverless service name `unity-lambda-api` and the HTTP prefix `/unity`.

What the code actually does is a set of AWS Lambda functions behind API Gateway. Two stores are used:

- MySQL, through `serverless-mysql`, for `sysUser`, `crmCalendar`, and (in files that are not deployed) member and permission tables.
- DynamoDB table name `loging` (the string in `serverless.yml`), used both as the starter "notes" table (`create.js`, `get.js`) and as an audit log (`logging.js`).

No written statement of product purpose, owner, or audience was found.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `fe4b095` | 2021-03-17 | Only branch. 5 commits from 2020-07-24 to 2021-03-17 |

No other local or remote branches were present at inspection. Nothing in git is dated after 2021-03-17. Whether the API is still deployed is **Unknown / Requires Confirmation**.

| Commit | Date | Author | Subject |
|---|---|---|---|
| `6cebfe4` | 2020-07-24 | Jaco Brits | first commit |
| `19d769f` | 2020-10-14 | Jaco Brits | Update current Global API's |
| `646ab62` | 2021-03-11 | Jaco Brits | clean up all apis and serverless version |
| `b4599f0` | 2021-03-15 | Jaco Brits | Update Calender and general table all data |
| `fe4b095` | 2021-03-17 | Joshua Gatley-Dewing | Calendar api changes |

## Objectives

No objectives file exists. The behaviour the commits introduced:

1. `6cebfe4` — Serverless starter plus MySQL helpers. Deployed routes: `POST /unity` (`create`), `GET /unity/{id}` (`get`), `GET /unity/user/{id}` (`getuser`), `GET /unity/uuid/{id}` (`getuseruuid`). Permission, role, and member-detail modules are in the tree and are not in `serverless.yml`.
2. `19d769f` — `POST /unity` moves from `create` to `global`. `create` moves to `POST /unity/create`. `POST /unity/import` (`saveimport`) is added. `saveimport.js` only logs the body.
3. `646ab62` — `getuserdetails.js` renamed to `getuserdetails_example.js` (still not routed). `adduser.js`, `updateuser.js`, `getusers.js`, `getdetails.js` added. Only `getusers` and `getdetails` are added to `serverless.yml`.
4. `b4599f0` — `crmCalendar` create/read/update/delete and `POST /unity/tableall`.
5. `fe4b095` — Calendar insert and update gain optional `strFirstUser` and `refSysUserID`. List and delete SQL drop a trailing comma.

## Scope

### In scope of `master` at `fe4b095`

- `serverless.yml` service `unity-lambda-api`: Node.js 12.x, stage `prod`, region `eu-west-1`, AWS CLI profile `unity`, 512 MB, IAM authorizer on every HTTP event, CORS enabled.
- Thirteen functions declared in that file (see the route table in `technical-documentation.md`).
- MySQL connection settings from environment names `DBHOST`, `DBUSERNAME`, `DBPASSWORD`, `DBNAME`.
- DynamoDB IAM for `arn:aws:dynamodb:eu-west-1:*:*` and table name `loging`.
- Handler files and `mocks/` that are not declared as functions.
- One Jest test of the starter `hello` handler.
- API Gateway 4XX/5XX CORS responses in `resources/api-gateway-errors.yml`.

### Out of scope / not in this repository

- The MySQL server, schema, and migrations. Table and column names appear only inside SQL strings.
- The DynamoDB table resource. No `AWS::DynamoDB::Table` is defined.
- Cognito user pool or identity pool. Comments say "cognito must be logged in". The authorizer in YAML is `aws_iam`. No Cognito resource is in the template.
- VPC. The security-group and subnet block is commented out.
- A pipeline, Sonar project, Dockerfile, or custom domain.
- The caller (web app or other service). Not named in this tree.
- Real `.env` values. `env.example` only contains `SAMPLE_ENV_VAR`. `.env` is gitignored.

## System shape

```text
Caller (unknown)
    |  AWS IAM (authorizer: aws_iam)
    v
API Gateway   service unity-lambda-api
stage prod    region eu-west-1    memory 512 MB    runtime nodejs12.x
    |
    +-- create, get ---------------> DynamoDB table name "loging"
    +-- global, getuser, getusers, getdetails, getuseruuid,
    |   tableall, calendar four ----> MySQL (serverless-mysql)
    +-- saveimport -----------------> console.log only
    |
    +-- logging.js (from the MySQL handlers) --> DynamoDB "loging"
         not awaited

Not in serverless.yml (present as .js files):
    adduser, updateuser, getrole, getuserdetails_example,
    savepermissions, updatepermissions, updatecustompermissions, updateuuid
```

## Major components

| Piece | Where | Role at `fe4b095` |
|---|---|---|
| HTTP API | `serverless.yml` | Declares the thirteen routes, runtime, IAM, and env |
| Notes-style Dynamo handlers | `create.js`, `get.js` | Starter create/get against `tableName` |
| Generic SQL | `global.js`, `tableall.js` | Build a query from the request and run it |
| System users | `getuser.js`, `getusers.js`, `getdetails.js`, `getuseruuid.js` | Read `sysUser` |
| Calendar | `addcalendarevent.js`, `getcalendarevents.js`, `updatecalendarevent.js`, `removecalendarevent.js` | Write and read `crmCalendar` |
| Import stub | `saveimport.js` | Logs `event.body`. SQL is commented out |
| Audit log | `logging.js` | Puts the event, query, and result into DynamoDB |
| HTTP wrapper | `libs/handler-lib.js`, `libs/response-lib.js` | CORS headers and status codes |
| Unrouted modules | permission, member, role, add/update user | SQL exists. No function entry in `serverless.yml` |
| Starter leftovers | `handler.js`, `handler copy.js`, `tests/handler.test.js`, `libs/images-lib.js` | `hello` demo. `images-lib.js` is empty |

## Milestones

The five commits above are the only milestones in git. There is no roadmap file. Work stopped on 2021-03-17.

## Dependencies known from the tree

Runtime (`package.json` `dependencies`):

- `serverless-mysql` ^1.5.4
- `uuid` ^7.0.3

Dev (`devDependencies`):

- `aws-sdk` ^2.706.0
- `serverless-bundle` ^1.2.5
- `serverless-dotenv-plugin` ^2.1.1
- `serverless-offline` ^5.3.3

The Serverless Framework CLI is not a dependency. The README tells the reader to install it globally. `npm test` runs `serverless-bundle test`.

AWS: API Gateway, Lambda, IAM, DynamoDB. MySQL host is whatever `DBHOST` is at deploy time. An S3 URL for bucket `footprint-reboot-qa-zaf` appears only in the unwired `getuserdetails_example.js`. The S3 client there is commented out.

## Current status

The repository is a finished-looking snapshot of an unfinished API.

- Deployed shape is the thirteen routes in `serverless.yml`.
- Calendar handlers read `event.pathParameters`, and their routes define no path parameters. A normal API Gateway POST will not fill those fields. **Requires confirmation** of how, or whether, calendar calls were meant to be invoked.
- `global.js` does not match the request shape in its own comment, and the join/where branches call `.length()` which is not valid on a string or array.
- `saveimport` does not write to MySQL.
- Several handlers and many mocks have no route.
- MySQL handlers return `success()` / `failure()`, which are already HTTP response objects, and `handler-lib.js` wraps that object again. Callers receive a 200 whose body is another response. A `failure()` result does not set the Lambda status to 500.
- README and `package.json` still describe the upstream starter (`serverless-nodejs-starter` 1.1.0).

**Unknown / Requires Confirmation**

- Whether `prod` in `eu-west-1` under AWS profile `unity` was ever deployed, and whether it is still running.
- The MySQL database name, host, and which tables actually exist (`sysUser`, `crmCalendar`, `tbl_member`, permission tables).
- Whether DynamoDB table `loging` exists, and whether the notes items and log items were intended to share it.
- What the caller is, and whether it sends calendar fields as path parameters, body fields, or a local invoke payload.
- Whether the unwired permission and member handlers were replaced by another service.
- Whether this API belongs to the same product as the other Unity repositories in Silicon Ark.
- Who owns the product now. Last author on `master` is Joshua Gatley-Dewing; four of five commits are Jaco Brits.