# Project plan — magalies-pharma-heisenberg-serverless

Evidence date: 2026-10-09.

Source repository: `git@bitbucket.org:overdrive/magalies-pharma-heisenberg-serverless.git`.

Inspected revision: `master` at `7d003d5` (2023-05-03, "Increased timeout to 19 sec"). Only remote branch: `master`. `origin/HEAD` points at `master`. History is 189 commits, from `88f2a57` (2021-11-15, "Initial commit") to `7d003d5`.

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

There is no prior Silicon Ark directory for this project. The repository README is titled "Heisenberg Serverless" and documents database naming and a Serverless Framework deploy order. It is not a product brief. `package.json` names the package `heisenberg-serverless` and records a GitLab URL `https://gitlab.assemble.co.za/magalies-pharma/heisenberg-serverless.git`. Provenance: **Documented** in `README.md` and `package.json`.

The local scan path named when this task was created (`~/projects/sonar_scan/repos/magalies-pharma-heisenberg-serverless`) was not present on this machine. Evidence below is from a read-only clone of `origin/master`.

## Product

**Inferred.** Heisenberg is the back-end API for Magalies Pharma's prescription, manufacture, packaging, and courier workflow. Callers submit a prescription (company, prescriber, patient or other individual, address, and medicine lines), staff review and split orders, fulfilment creates medicine batches, packaging scans barcodes onto order lines, and courier functions talk to Dawn Wing (DPD) for waybills and tracking. A separate front end is not in this repository. CloudFormation creates an S3 bucket `heisenberg-frontend-${EnvironmentName}`, so a front end is expected to live elsewhere.

**Implemented.** Sixteen Serverless Framework services under `serverless/functions/`, sharing one API Gateway named `admin-${stage}` in `eu-west-1`, a Cognito user pool, and a MySQL 8 database named `heisenberg`.

**Unknown / Requires Confirmation:** whether any stage is still deployed, who the product owner is, and which application calls this API.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `7d003d5` | 2023-05-03 | Node.js 14 Serverless API, CloudFormation stacks, Knex/Objection models, SQL migrations and seeds |

No other branches or tags were present on the remote that was cloned. Pull-request history was not inspected.

The task-creation scan listed `sonar-project.properties` and `sonarqube_scan.bat` at the repository root. Neither file is in `master` at `7d003d5`. Provenance: **Unknown** — they may have been untracked files on the scan host.

## Objectives

No roadmap exists in the repository. The following objectives are **Inferred** from the domain model, Cognito groups, and HTTP functions:

- Record prescriptions as orders with a patient, doctor, pharmacist company, prescriber, shipping address, and medicine lines.
- Maintain a catalogue of medicines, dosage forms, package types, and sellable package variants, including a medicine number used at scan time.
- Manufacture stock as batches of unscanned package units, then assign a barcode and medicine number when a package is packed.
- Let packaging mark an order line packed only after every assigned unit has a barcode.
- Create child orders so one prescription can be split, and move lines between a parent and its children.
- Hand delivery orders to Dawn Wing / DPD and store waybill and tracking data.
- Give staff a date-range dashboard and medicine, batch, and order reports.
- Administer Cognito users in groups SuperAdmin, Prescription, Fulfilment, Packaging, and Customer.

## Scope

### In this repository

- CloudFormation for a shared IAM role, a VPC with two public subnets, Cognito, RDS MySQL, S3 buckets, and the admin API Gateway with authorizers.
- Lambda layers: `authorize`, `aws-services`, `database` (Objection models), `email`, `general-utils`.
- HTTP Lambdas for users, companies, individuals, medicines and dosage/package catalogues, orders and prescriptions, batches, stock check, fulfilment scan, courier, reports, dashboard, audit log, presigned S3 URLs, and PDF/image generation.
- SQL migrations in `database/migrations/` and seed data in `database/seeds/`.
- A database diagram (`database/diagrams/main.png`, `main.uxf`). The diagram was not re-read as a source of requirements; the SQL is.

### Not in this repository

- The front-end application. Only the bucket name `heisenberg-frontend-${EnvironmentName}` is here.
- Stage env files (`dev.env.yml`, `stage.env.yml`, `live.env.yml`, `prod.env.yml`). They are gitignored. `example.env.yml` is the template.
- Automated tests. `package.json` script `test` prints an error and exits 1. No test directory is in the tree.
- A pipeline definition. Serverless package excludes name `.gitlab-ci.yml`, but that file is not in the tree.
- A queue, scheduled worker, or background job. Every function in the templates is an HTTP Lambda.

## Architecture

One regional API Gateway (`admin-${stage}`) is created by `serverless/formations/06 - api-gateway.yml`. Each domain service imports that API (`serverless-import-apigateway`) and adds routes. Functions that touch MySQL run in the VPC public subnets and the Lambda security group exported by the network stack.

```text
Caller (unknown front end)
  -> API Gateway admin-{stage}  (eu-west-1)
       Cognito authorizer (header idtoken)
       Lambda TOKEN authorizers (header accesstoken)
       API-key private routes (three courier reads/writes)
  -> Lambda (nodejs14.x, 128 MB, typically 6 s; courier 19 s; batch create and puppeteer 30 s)
       layers: database, general-utils, authorize, aws-services, email
  -> RDS MySQL 8 database heisenberg
  -> S3 (deployments, front end, prescriptions, email templates)
  -> Cognito user pool admin-user-pool-{stage}
  -> Dawn Wing HTTPS swatws.dawnwing.co.za (courier service only)
```

Deploy order **documented** in `README.md`: `01 - base.yml`, `02 - network.yml`, `03 - cognito.yml`, `04 - database.yml`, `serverless.layers.yml`, `serverless.authorizers.yml`, `05 - api-gateway.yml`, then the other function services. Region in the README examples is `eu-west-1`. Default Serverless stage in the templates is `dev`.

## Major components

| Component | Where | Role |
|---|---|---|
| Formations | `serverless/formations/01`–`06` | Shared AWS resources |
| Authorizers | `serverless/functions/serverless.authorizers.yml`, `src/authorizers/` | Cognito group checks |
| Catalogue | `serverless.medicine.yml` | Medicine, dosage unit/type, package type, dosage-package links |
| Parties | `serverless.company.yml`, `serverless.individual.yml` | Companies and people |
| Orders | `serverless.order.yml` | Prescription submit, list, view, edit, split, move, tracking |
| Manufacture | `serverless.batch.yml`, `serverless.batch-item.yml`, `serverless.stock.yml` | Batches, batch items, stock counts |
| Packaging | `serverless.fulfilment.yml` | List, scan, mark packed |
| Courier | `serverless.courier.yml` | Local shipping/waybill/tracking plus Dawn Wing proxy |
| Reporting | `serverless.misc.yml` | Form data, dashboard, three reports |
| Files | `serverless.presigned-url.yml`, `serverless.puppeteer.yml` | S3 URLs and label/PDF generation |
| Users | `serverless.user.yml` | Cognito user CRUD for SuperAdmin |
| Audit | `serverless.log.yml` | Read the `log` table |
| Data | `serverless/layers/database`, `database/migrations` | Objection models and SQL |

## Milestones visible in Git

These are commit clusters, not a published plan.

| When | Evidence | What landed |
|---|---|---|
| 2021-11 | `88f2a57`, `b830a1b`, `bcacb24` | Initial commit, formations, layers, authorizers, first migration |
| 2022-04 to 2022-05 | migrations dated `04_20` and `05_10` | Batch comment, individual email, tracking table |
| 2022-08 | migrations dated `08_08` and `08_16` | Medicine number, distributor, package price/label, prescriber |
| 2022-09 to 2022-11 | migrations `09_30` through `11_23` | Batch expiry, waybill JSON, scanned medicine number, float quantity, prescriber points at `individual` |
| 2023-05-03 | `7d003d5` | Courier Lambda timeout raised to 19 seconds |

No commit after 2023-05-03 is on `master`.

## Implementation plan

There is no open implementation plan in the repository. Current status is a finished snapshot of the API as of May 2023. Planned work is **Unknown**.

## Known dependencies

- Node.js runtime `nodejs14.x` (AWS Lambda). Local tooling: Serverless Framework `^2.72.3`, `serverless-jetpack`, `serverless-import-apigateway`, `yamljs`.
- MySQL 8.0.25 on RDS (`db.t3.micro`), accessed with Knex and Objection from the database layer.
- Amazon Cognito user pool, API Gateway, Lambda, S3, SES (email layer only), SNS (Cognito SMS role).
- Dawn Wing web services host `swatws.dawnwing.co.za`. Example path is `/dwwebservices/v2/uat/api`. Commit `121c681` says live credentials live in `live.yml`, which is gitignored.
- Puppeteer/Chromium inside `src/puppeteer/generate` for JPEG and PDF output. The only Handlebars template in the tree is `lib/templates/order_summary.hbs`.
- AWS account id is resolved at package time by `serverless/helpers/account-id.js`.

## Current project status

**Implemented** on `master`, last changed 2023-05-03. Whether it is deployed, which stage is production, and whether a front end still calls it are **Unknown / Requires Confirmation**.

`README.md` still says `cd re-mind-serverless/` in the install steps. That directory name does not match this repository. Treat the README install snippet as stale starter text.

## Human confirmation

- Is Heisenberg still the live Magalies Pharma API, and which stage (`dev`, `stage`, `live`, `prod`) is production?
- Where is the front end that uses `heisenberg-frontend-${stage}`?
- Should the unused Customer authorizer and the unused email layer be treated as planned or abandoned?
- Are the scan-host files `sonar-project.properties` and `sonarqube_scan.bat` required documentation, or were they never committed?