# Project plan — formulys_simpleflow

Evidence date: 2026-10-14.

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

Inspected revision: `master` at `07cd01b` (2024-06-21, joshgatdew, "Merge branch 'master' of https://bitbucket.org/overdrive/formulys_simpleflow"). `origin/HEAD` points at `master`. The scan-host path `~/projects/sonar_scan/repos/formulys_simpleflow` was not on this machine. The tree below was read from a clone of that git revision. Pipeline variable names and the Form.io host are recorded. Secret values are not in git and are not reproduced.

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

## Product

The browser title in `index.html` is **SimFlow Process Hub**. The npm package name in `package.json` is `simflow-react`, version `0.0.0`, `private: true`. The Bitbucket slug is `formulys_simpleflow`.

`README.md` is the stock Vite + React template. It does not describe Formulys, SimFlow, users, or workflows.

**Implemented.** A React 18 single-page app, built with Vite, that:

1. Logs a person in against a Form.io form and keeps the returned JWT in `localStorage`.
2. Loads that person's company record, including a list of business processes.
3. Shows process cards, a task list, and a recent-submissions panel, and opens Form.io forms in Bootstrap modals.
4. Lets Simflow Admins and Project Managers manage companies and users.
5. Lets a Simflow Admin view SendGrid bounce and block lists.

**Inferred** from the title, the form names (`simflowlogin`, `simflowclientdetail`, `simflowclientusers`, `simflowuserroles`), and the navigation: this is the Formulys SimFlow client for running configured business processes and tasks. No product brief in the repository states the commercial purpose, the customer, or the success criteria.

**Unknown / Requires Confirmation:** product owner, live URL, and whether this front end is meant to call `formulys_simpleflow_backend`. This repository never references that backend. Silicon Ark's `formulys_simpleflow_backend` documents describe an Express + Socket.io + Mongoose scaffold whose role names (`tenantUser`, `tenantAdmin`, `platformAdmin`) do not appear here. The two trees were last changed weeks apart in 2024 and do not share an API contract in git.

The Form.io host `https://rzkiqpzlxxtfqjl.form.io` is the same host recorded for `pestelite_html`. Form paths in this repo are `simflow*`. Pestelite paths are different. Whether the two products share one Form.io project on purpose is **Unknown / Requires Confirmation**.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `07cd01b` | 2024-06-21 | Application, pipeline, Sonar key |
| `origin/url-query-state` | `b5896d3` | not merged | One commit, "app state via url query params", based on `e11b604` (2024-05-31), which is two commits behind `master` |

No tags were present at inspection.

History runs from `2e7010a` (2024-02-29, Jason Wandrag, "SimFlow Boilerplate UI") through `07cd01b` (2024-06-21). Authors on `master`: Jason Wandrag, joshgatdew (`joshua@overdrive.co.za`), silmaanie (`maanie@overdrive.co.za`), Lloyd (`lloyd@overdrive.co.za`), Jaco Brits (`jaco@overdrive.co.za`). Nothing has been committed since 2024-06-21.

`url-query-state` reads `formId` and `submissionId` from the query string, stores them in the submission store, and after submissions load calls a helper that tries to open a modal whose id is `Modal-Form-{formId}-Submission-{submissionId}`. The card component on that branch changes modal ids to match. The commit still contains a `console.log`, a commented `useSearchParams` example, and a commented line that would clear the query after open. It does not fix the `getAllSubmissions` reference used when a card modal closes. Provenance: **Planned** only as an unmerged branch. It is not behaviour on `master`.

**Discrepancy:** the task-creation scan listed `sonarqube_scan.bat` at the repository root. The bat file is not in any commit on `master` or `url-query-state`. Provenance of the bat file: **Unknown** — it may have been an untracked file on the scan host.

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

No milestone document, roadmap, or issue list is in the repository. The behaviour that was built, in the order the commits describe it:

- 2024-02-29 — boilerplate UI (`2e7010a`).
- 2024-03-01 — dashboard, company data separated from the user, branding and roles (`a75b984`, `9573e64`, `f605d5d`). Sonar project key and the first pipeline file added the same day by Jaco Brits.
- 2024-03-08 — coming-soon pages for areas that are still placeholders (`d78591c`).
- 2024-04-10 to 2024-04-22 — task list and profile update.
- 2024-04-15 — deployment script iterations by Lloyd, ending on FTP upload of the Vite `dist` output. Commit messages include "revert to git ftp".
- 2024-05-09 — management page with company and user tabs (`926f6a8`).
- 2024-05-16 — email management against SendGrid (`bdd44ce`, silmaanie).
- 2024-05-17 — role label changed from Admin to Simflow Admin (`15b5186`).
- 2024-05-28 — user management rewritten from the Form.io form builder to a React form (`b843b82`). Password no longer required on that form (`22a9d07`).
- 2024-05-31 — management styling and reporting page (`e11b604`). The reporting route still renders "Coming Soon".
- 2024-06-21 — logo change (`525e462`) and a merge commit. Tip of `master`.

## Scope

### In scope of `master`

- Login, session restore, logout.
- Dashboard of Form.io submissions, with search on `simflowCardName`, and a Simflow Admin recent-submissions column.
- Process Hub for starting a non-task process the user's role may access.
- Task list and a nav badge for open tasks.
- Profile modal (name and password).
- Management: companies, users, and (Simflow Admin only) SendGrid bounces and blocks.
- Placeholder routes: notifications, messages, reporting, settings.
- Bitbucket Pipelines: `npm run build` on `master`, FTP upload of `dist/*` using QA variable names, then a SonarQube scan.
- `sonar.projectKey=overdrive_formulys_simpleflow_09e31949-1f76-42c8-9767-83697088df34`.

### Out of scope of this repository / not present

- Form.io form definitions and submission data. They live on `https://rzkiqpzlxxtfqjl.form.io`.
- The Express backend in `formulys_simpleflow_backend`.
- A production deploy target. The pipeline variable names are `FTP_*_QA` only.
- Automated tests. `package.json` has `lint` and `build`. It has no `test` script, and the tree has no test files.
- A written product plan, user manual, or API specification.

## System shape

```text
Browser (Vite + React 18)
  ├─ Zustand auth store ── JWT in localStorage ("token")
  ├─ Zustand submission store
  ├─ Form.io  https://rzkiqpzlxxtfqjl.form.io
  │    simflowlogin, current, simflowclientdetail,
  │    simflowclientusers, simflowuserroles,
  │    plus whatever form URL a company process stores
  └─ SendGrid suppression API (browser-side client)
        only the Emails tab, Simflow Admin

Bitbucket Pipelines (master)
  ├─ npm run build  →  dist/
  ├─ ncftpput dist/*  →  FTP host from FTP_*_QA variables
  └─ sonarsource/sonarqube-scan:2.0.1
```

There is no database, queue, or background worker in this repository. Company colours, logo, and the process catalogue are fields on the Form.io company submission, read at login.

## Current status

Active development on `master` stopped at `07cd01b` on 2024-06-21. The committed `src/App.jsx` has a trailing `1` on the Messages import (introduced in `5952e5d`, 2024-05-09, and still present at the tip). That token is a JavaScript syntax error, so `npm run build` cannot succeed on this revision. Whether Bitbucket Pipelines is currently failing was not observed from this machine (the Bitbucket API returned 401 during this inspection).

Several screens are labelled Coming Soon. The unmerged `url-query-state` branch is an unfinished deep link and is not on `master`.

## Dependencies known from the repo

| Dependency | Where | Role |
|---|---|---|
| Form.io project `rzkiqpzlxxtfqjl.form.io` | `src/lib/constants.js` and one hardcoded URL in `UpdateUserForm.jsx` | Identity, companies, users, roles, process forms |
| SendGrid | `@sendgrid/client` in `EmailManagement.jsx` | Bounce and block lists. Key expected as `VITE_REACT_SENDGRID_API_KEY` |
| Bootstrap 4.6.2, jQuery 3.5.1, Popper 1.16.1 | CDN in `index.html` | Layout and `$().modal` |
| Bootstrap 5.3.3 | npm import in `src/main.jsx` | Also loaded. How the two versions interact was not runtime-tested |
| Form.io CSS | `https://cdn.form.io/formiojs/formio.full.min.css` | Form renderer styles. JS renderer is the npm package `@formio/react` |
| FTP server | pipeline variables `FTP_USERNAME_QA`, `FTP_PASSWORD_QA`, `FTP_HOST_QA`, `FTP_SITE_ROOT_QA` | QA upload of `dist/*` |
| SonarQube | `SONAR_HOST_URL`, `SONAR_TOKEN`, `sonar-project.properties` | Analysis after deploy on `master` |
| Node 20 | `bitbucket-pipelines.yml` image `node:20`. Comment in the file says "Local node v20" | CI build |

`example.env` documents only `VITE_bob=cat`. It does not list the SendGrid variable the Emails tab reads. `.env` is gitignored.

## Human confirmation

- What Formulys SimFlow is for, who the customer is, and the live URL.
- Whether `formulys_simpleflow_backend` is a replacement, a companion, or unrelated.
- Whether sharing the Pestelite Form.io host is intentional.
- Whether the `master` build is expected to be green. The tip does not parse.
- Whether `url-query-state` should be finished, abandoned, or rebased.
- QA versus production FTP targets, and where `FTP_HOST` / `FTP_SITE_ROOT` (names used only in the pipeline echo) are defined.
- The real catalogue of roles and business processes, which is data in Form.io, not in git.
- Whether a SendGrid key is configured, and whether it is acceptable for that key to be compiled into the browser bundle (`VITE_` prefix).