# Project plan — DigitalBio

Evidence date: 2026-10-17.

Source repository: `https://bitbucket.org/overdrive/digitalbio.git` (origin `git@bitbucket.org:overdrive/digitalbio.git`).

Inspected revision: `master` at `2739231` (2023-03-07, author `Dirk`, subject "Name changes and changed tile to show on ML Results page"). `origin/HEAD` points at `master`. The scan-host path `~/projects/sonar_scan/repos/DigitalBio` was not on this machine. The tree was read from a fresh clone of that git revision. `HEAD` matched the commit recorded when this onboarding issue was created.

AWS account numbers, IAM role ARNs, the Amplify app id, and the Secrets Manager secret value are omitted. The secret id string and the API host written in `README.md` are included because they are in the source tree.

No `silicon_ark/DigitalBio/` documents existed before this set. The repository itself has no project plan, PRD, or requirements file. This plan describes what the repository contains. It does not decide what the product should become.

## Product

The npm package and the Amplify project are both named `digitalbio`, version `0.1.0` (`package.json`, `amplify/.config/project-config.json`). The browser title and the web-app manifest name are **Digical Digital** (`public/index.html`, `public/manifest.json`). The logo file is `src/Images/digitalBio.png`. The icon file on disk is `public/digitalBio-icon.png`. The HTML and the manifest request `digicalBio-icon.png`, which is not a tracked file.

Which of those strings is the product name is **Unknown / Requires Confirmation**.

What the repository implements is a Create React App (React 18) that does not render until AWS Amplify's `withAuthenticator` has a Cognito session. After sign-in, a left-hand column offers three screens: **ML Results**, **Jobs**, and **Canvasses**. There is no URL router. The selected screen is React state in `src/App.js`, so a refresh returns to ML Results.

The screens read a PostgreSQL database through one Amplify REST API (`apia19f7356`) backed by the Lambda `SearchTiles`. They show slide tiles, a per-tile result table (a result string and a confidence percentage), batch-transform job rows, and canvas images with a tile grid. Image bytes are not in the database response. The client turns an `uri` column into an S3 presigned URL.

Provenance of the screens and the API: **Implemented**. Provenance of the local run steps and the API host: **Documented** in `README.md`. No sentence in the README says who the users are or what a slide, a tile, a canvas, or a result means.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `2739231` | 2023-03-07 | The app as described in this set |
| `origin/ui-update` | ancestor of `master` | 2023-03-03 | Merged by `272949e` ("Merged in ui-update (pull request #1)"). Not ahead of `master` |

History is 30 commits from 2023-02-14 through 2023-03-07. Author strings in the log: `Jaco Brits` (the first two commits), `Dirk` (most commits), `Dirk Jansen van rensburg` (the merge commit `272949e` only), `liam-ovd` (UI commits on `ui-update`). 54 tracked files. No commits after 2023-03-07.

Whether any deployed site or the `dev` Amplify stack still serves this tree is **Unknown / Requires Confirmation**.

Observable milestones from the commit subjects (not a written plan):

| Commit | Date | Author string | Subject |
|---|---|---|---|
| `dc793e2` / `e8b8b5a` | 2023-02-14 | Jaco Brits | README created; first commit |
| `2b078df` / `6888ace` | 2023-02-15–16 | Dirk | Amplify config; region fix |
| `d1dc297` / `be916da` / `faf3d8b` / `e45c8ee` | 2023-02-15–17 | Dirk | Cognito login; auth; username sign-in |
| `6842c2a` then `e5dd795` | 2023-02-17 | Dirk | Added API `SearchSlide` / Lambda `SearchSlides`, then removed them the same day |
| `8783e60` | 2023-02-16 | Dirk | Dashboard and search |
| `5259d68` | 2023-02-17 | Dirk | README updated with the local steps and an API host |
| `4cc2894` / `df8b399` / `0210bce` | 2023-02-24 | Dirk | Slide Explorer, result tile viewer, confidence column. This is the first commit of Lambda `SearchTiles` |
| `c7b943d` | 2023-02-24 | Dirk | Job search |
| `42756ad` / `0c1b49f` / `a5cbd43` | 2023-02-24–03-01 | Dirk | Canvas pages |
| `93383c9` / `2578447` | 2023-03-02 | Dirk | Loading placeholders; canvas search and next-button fix |
| `e0d76a1` / `272949e` | 2023-03-02–03 | liam-ovd, then Dirk Jansen van rensburg | UI improvements; merge pull request #1 |
| `00e1951` | 2023-03-03 | Dirk | Removed the search button from job search |
| `d442a33` | 2023-03-07 | Dirk | Removed the Dashboard button from Slide Explorer |
| `2739231` | 2023-03-07 | Dirk | Sidebar labels became "ML Results" and "Canvasses". The ML Results table shows `name` instead of `slide` |

## Objectives (inferred from the screens and the API, not from a written plan)

No project plan or requirements document exists in the repository. The following objectives are **Inferred** from the navigation labels, the SQL, and the screens:

- Let a signed-in person look up slide tiles and open one tile image.
- Show, next to that image, rows from `bbox` as a result string and a confidence percentage. The sidebar calls the list **ML Results**. The model that produced those rows is not in this repository.
- Let the person list and filter rows in `batch_transform_jobs`.
- Let the person look up a canvas image and the tiles placed on it (`tiles.row` / `tiles.col`).
- Keep the database and the image buckets outside the browser. The browser only calls the REST API and asks S3 for a presigned GET.

Provenance of the behaviour: **Implemented**. Provenance of "this is the product goal": **Inferred**. There is no backlog, milestone document, or TODO that states a next release. Comments `Todo logic here` and `Add Todo JSX here` in `src/App.js` are Create React App leftovers. They are not a planned feature.

## Scope

### In this repository

- React single-page application under `src/`.
- Amplify backend definition for one Cognito auth resource (`digitalbio5fd52944`), one API Gateway REST API (`apia19f7356`), and one Lambda (`SearchTiles`).
- The Lambda's Express routes, which query PostgreSQL.
- A local run note in `README.md`.

### Not in this repository

- `aws-exports.js`. It is gitignored. The README tells the reader to create it. The file is absent from this clone.
- The PostgreSQL schema (no `CREATE TABLE`, no migration).
- The program that inserts `image`, `bbox`, `batch_transform_jobs`, `canvas`, and `tiles` rows.
- The model, training job, or pipeline behind "ML Results" and behind the table name `batch_transform_jobs`.
- S3 bucket policy. Bucket names are parsed from the `uri` values stored in the database.
- A hosting app. `amplify/backend/backend-config.json` has auth, api, and function only. No Amplify hosting category.
- CI, Docker, Sonar project files, and infrastructure outside Amplify.

The onboarding issue (captured 2026-09-28 from the scan host) listed `sonar-project.properties` and `sonarqube_scan.bat` beside `package.json`. `git ls-files` at `2739231` does not contain them. **Unknown / Requires Confirmation** whether the scan host has untracked copies.

## System architecture

```text
Browser (CRA, React 18)
  withAuthenticator  ->  Cognito user pool + identity pool
  page state in App.js (no router)
        |  API.get('apia19f7356', path)
        v
API Gateway REST (Amplify resource apia19f7356, paths set to open)
        |
        v
Lambda SearchTiles (Node.js 14, Express, 25s timeout)
        |  Secrets Manager secret id "webapp_admin_user" on every request
        v
PostgreSQL   tables referenced: image, bbox, batch_transform_jobs, canvas, tiles

Browser also:
  Auth.currentCredentials() -> S3 GetObject presign (eu-west-1, 3600 seconds)
  using bucket and key parsed from the row's uri
```

Region on the checked-in Amplify environment and in the presign client is `eu-west-1`. The only Amplify environment key in `amplify/team-provider-info.json` is `dev`. Stack name recorded there: `amplify-digitalbio-dev-83808`.

## Major components

| Component | Path | Role |
|---|---|---|
| Shell and navigation | `src/App.js`, `src/Components/AppHeader.jsx`, `src/Components/Hearder.jsx` | Authenticator gate, logo, username, sign out, three navigation buttons, page switch |
| ML Results | `src/Pages/Dashboard.jsx` | Latest tiles, slide search, row opens the tile viewer |
| Slide Explorer | `src/Pages/SlideExplorer.jsx` | Image cards for a slide search. Not a navigation button. Opened from the search field submit |
| Tile viewer | `src/Pages/ResultTileViewer.jsx` | Zoomable image, previous/next by id, bbox table |
| Jobs | `src/Pages/Jobs.jsx` | Job table and name search. Rows do not open another page |
| Canvasses | `src/Pages/CanvasSearch.jsx`, `src/Pages/CanvasResultViewer.jsx` | Canvas cards, zoomable canvas, tile grid table |
| API client | `src/util/getDataFromAPI.js`, `src/util/getDataWithSignedURL.js`, `src/util/s3Utils.js` | Amplify GET, then presign when `uri` is present |
| API implementation | `amplify/backend/function/SearchTiles/src/app.js` | Express routes and SQL |
| Auth and API config | `amplify/backend/auth/digitalbio5fd52944/cli-inputs.json`, `amplify/backend/api/apia19f7356/cli-inputs.json` | Cognito settings and route list |

## Current project status

The tip is a read-only viewer. The Lambda defines GET routes only. The UI has no create, update, or delete control for slides, jobs, or canvases.

Work stopped on 2023-03-07 at a UI rename. There is no open branch ahead of `master`. There is no tracked issue list inside the repository.

The default Jest test still looks for the text "learn react" (`src/App.test.js`). The app does not render that text, and `src/App.js` imports `./aws-exports`, which is not in the clone. The test was not executed for this document. **Inferred:** `npm test` cannot pass on a clean clone until `aws-exports.js` exists, and the assertion would still fail after that.

`SearchTiles-cloudformation-template.json` grants the Lambda role CloudWatch Logs only. `custom-policies.json` has an empty action and an empty resource. The handler calls Secrets Manager and then PostgreSQL. Whether a live role was given those permissions outside this template is **Unknown / Requires Confirmation**.

## Known dependencies

Frontend (`package.json`): React 18.2, React DOM 18.2, `react-scripts` 5, `aws-amplify` 5, `@aws-amplify/ui-react` 4, `aws-sdk` 2 (used by `s3Utils.js`), `@aws-sdk/client-secrets-manager` 3 (listed; no file under `src/` imports it), `react-icons` 4, `react-jss` 10, `react-zoom-pan-pinch` 2, Testing Library, `web-vitals`.

Lambda (`amplify/backend/function/SearchTiles/src/package.json`): `express` 4, `body-parser`, `aws-serverless-express` 3, `pg` 8, `@aws-sdk/client-secrets-manager` 3. Runtime in the CloudFormation template: `nodejs14.x`. Handler: `index.handler`. Timeout: 25 seconds. Memory is not set in the template.

External, not vendored: Amazon Cognito, API Gateway, Lambda, Secrets Manager, S3, and a PostgreSQL server whose host is inside the secret.

## Implementation plan

There is no forward plan in the repository. The commit list above is the record of how the current tree was built.

## Human confirmation

Collected here so the other documents can stay specific. None of these were resolved from the code:

1. The product name: `digitalbio`, `Digical Digital`, or `digitalBio`.
2. What a slide, a tile, a canvas, and `bbox.results` mean in the business, and which system writes those tables.
3. Whether `batch_transform_jobs` rows are Amazon SageMaker batch transform jobs. Only the table name suggests that.
4. The full column list, keys, and the database host. This repo only shows the columns the UI reads.
5. Whether `image.uri` and `canvas.uri` are `s3://bucket/key` or an HTTPS URL. The presign parser assumes the bucket is the first segment after `//`.
6. Whether `bbox.score` and `batch_transform_jobs.perc` are fractions from 0 to 1. The UI multiplies both by 100.
7. Whether job search is meant to match the job number. The placeholder says "Job No. Search". The SQL filters `name`.
8. Whether the canvas search button is meant to open Slide Explorer. The placeholder is "Slide No. Search", and that placeholder is what shows the button.
9. Whether the `dev` stack and the README API host are still deployed.
10. Whether the Lambda role can read secret `webapp_admin_user`. The checked-in policy does not allow it.
11. Whether `sonar-project.properties` and `sonarqube_scan.bat` exist only on the scan host.
12. Whether self-service sign-up should remain available. The authenticator call does not hide it, and the user pool has no groups.