# Project plan — bitool_frontend

Evidence date: 2026-10-19.

Source repository: `git@bitbucket.org:overdrive/bitool_frontend.git`, default branch `master` at `937e09cb` (2026-09-22, Jason Wandrag, "Merged in hotfix/random-logouts-cluver (pull request #13)").

This plan describes what `master` contains. It does not decide which branch should be production.

The task-creation path `~/projects/sonar_scan/repos/bitool_frontend` was not present on this machine. Evidence is a full clone of the remote. The task-creation snapshot named `c6259e3` (2025-10-24, "Update SidebarFilters.jsx") as the tip. `master` has moved four commits past that snapshot.

Related Silicon Ark sets, for other lines of the same remote:

- `bi_tool_frontend_phase6/` documents branch `phase_6` at `82d7ef04` (2026-08-21). That set says the other branches were not checked out.
- `bi_tool_php/` documents a separate PHP import repository. It is not the API this frontend calls.

There was no `bitool_frontend/` directory in Silicon Ark before this set.

## Product

**Documented** in `DEVELOPER_DOCUMENTATION.md`, the Home page copy, and `public/index.html`: a SAWIS (SA Wine Industry Information and Systems) business-intelligence web application. The HTML title is "SAWIS Report". `package.json` name is "SAWIS BI", version `0.1.0`.

**Implemented on `master`:** a Create React App single-page application. Visitors can open Home, Export Reports, Grape Production, and Vineyard Status without an account. A signed-in user also sees export value and currency columns, a Reports tab (RSA exports), and Price Range tables.

The browser calls a separate HTTP API whose base URL is `REACT_APP_API_BASE_URL`. This repository does not contain that API or a database.

## Branch reality

`origin/HEAD` points at `master`. History reachable from `master` is 269 commits, from `978f2c9` (2023-11-03, "Initial commit") to `937e09cb`.

| Branch | Tip date | Tip | Subject | Relation to `master` |
|---|---|---|---|---|
| `master` | 2026-09-22 | `937e09cb` | Merged in hotfix/random-logouts-cluver (pull request #13) | Default. This documentation set |
| `qa` | 2026-10-16 | `584d8b7` | Merged in phase6_pr (pull request #23) | 148 commits not in `master` |
| `phase6_pr` | 2026-10-15 | `c8eca9f` | client feedback bugfix | Included in the `qa` commits above |
| `phase_6` | 2026-08-21 | `82d7ef0` | Domestic reports and Firefox bugfixes | Ancestor of the `qa` line. Documented in `bi_tool_frontend_phase6/` |
| `hotfix/random-logouts-cluver` | 2026-09-22 | `17d160e` | fix(deps): clear npm audit vulnerabilities | Merged to `master` by pull request #13 |
| `phase5` | 2026-01-26 | `f9e691e` | Fix package vulnerabilities | Not the `qa` tip |
| `phase4` | 2025-10-08 | `b1fdf4e` | Update PivotTableRenderer.jsx | Behind `master` |
| `phase3` | 2025-11-26 | `675e4b4` | Update warning layout and design of login flow | Same tip as `bugfix-failed-login-flow` |
| `login_encyryption` | 2026-02-13 | `98ca210` | Encrypt login payloads | Not merged to `master` |
| `env/qa` | 2024-06-07 | `8e109dd` | updated and added auth headers for QA environment | Old |

Other remote heads exist (`jason-handover`, `testsprite_tests`, `upload_debug`, `ettiene_debug`, `code-smells`, `feature/Phase_2`, `feature/et1_testDocument`, `bugfix/industry_specific_import`, `fix/npm-package-vulnerabilities`). They were listed from `git ls-remote` and `git for-each-ref`. Their files were not read, except the route files on `qa` named below.

`qa` routes that are absent from `master` (`git show origin/qa:src/AppRoutes.js` and `src/pages/domestic/DomesticRoutes.jsx`):

- `/domestic/reports` and `/domestic/capture` (capture wrapped in an auth guard)
- `/admin` and `/admin/*` wrapped in `AdminRouteGuard`

A commit on that line, `ff8dd70`, says "fix(build): replace CRA with Vite and remove unused Tailwind". That change is on `qa`, not on `master`.

Which branch is deployed is **Unknown / Requires Confirmation**.

## Objectives visible in the repository

These are recovered from `DEVELOPER_DOCUMENTATION.md`, Home copy, and commit subjects. They are not a signed product charter.

1. Show wine-industry export, grape production, and vineyard status information in the browser.
2. Let a visitor filter export charts and volume tables, and download tables to Excel.
3. Let a signed-in user see currency and value figures, generate an RSA exports report, and keep price-range tables.
4. Keep a session across refresh, and clear it only when the API returns HTTP 401.

## Scope on `master`

In the running UI (`src/AppRoutes.js`, `src/pages/Home.js`, `src/components/Navbar.js`):

- Home (`/`)
- Exports (`/reports`) — Overview, Volume, a guest-only Value prompt, Price Range, and a signed-in Reports tab
- Grape Production (`/grape-production`)
- Vineyard Status (`/vineyard-status`)

Present on `qa` and `phase_6`, absent from `master` routes:

- Domestic Sales
- Admin (mapper tools and user management)

Out of this frontend, confirmed by the code that was read:

- Account registration and password reset. The login modal links to `https://www.sawis.co.za/`.
- The API and its database.
- A native mobile app.

The task-creation scan listed `sonarqube_scan.bat` at the repository root. That file is not in `master`. Provenance: **Unknown** — it may have been an untracked file on the scan host.

## System shape

```text
Browser (React 18 SPA, Zustand, React Router 7)
  → fetch(REACT_APP_API_BASE_URL + path)
       guest:  /loginAuth, /getFilters, /getChartData, /get* table and chart paths,
               /getGrapeProductionFilters, /getGrapeProductionReports,
               /getVineyardStatusFilters, /getVineyardStatusReports,
               and POST {API}/{report.URL} for each grape or vineyard report
       signed-in: Authorization header = raw token (no "Bearer " prefix)
               /auth/getFilters
               /auth/tables/*
               /auth/getPriceRangeData
               /auth/getPriceRangeFilterHistory
               /auth/setPriceRangeFilterHistory
               /auth/reports/getRSAExportsReport
               /auth/getCountryGroup

Chart POSTs (/getChartData and the other overview chart paths) stay on the
public prefix even when a user is signed in.

Leftover CRA template: src/setupProxy.js proxies /weatherforecast to an
ASP.NET Core dev URL. No page calls that path.
npm prestart still runs aspnetcore-https.js and aspnetcore-react.js.
```

Provenance: **Implemented** in `src/store/*`, `src/setupProxy.js`, and `package.json`. `DEVELOPER_DOCUMENTATION.md` draws the backend as ASP.NET and SQL Server. That diagram is a claim in the developer doc. This repository does not contain that backend. The committed `env` file points the client at `http://localhost:8080` and comments out `https://bi.sawisonline.co.za`.

## Major components

| Area | Where it lives | Role |
|---|---|---|
| Shell | `src/App.js`, `src/components/Layout.js`, `src/components/Navbar.js` | Routes, disclaimer footer, login modal, contact mail |
| Home | `src/pages/Home.js` | Three navigation cards and the SAWIS vision, promise, and values |
| Export reports | `src/pages/Reports.js`, `src/components/tabs/*`, `src/components/Sidebar.js`, `src/store/filterStore.js` | Filters, overview charts, volume tables, price range, RSA report |
| Grape and vineyard | `src/pages/GrapeProduction.js`, `src/pages/VineyardStatus.js`, `src/components/SidebarFilters.jsx`, `src/components/pivotTable/GenericPivotTable.jsx` | API-driven report list and pivot tables |
| Auth | `src/store/authStore.js`, `src/utils/authSession.js`, `src/components/forms/LoginForm.jsx` | Login, cookie session, 401-only logout |
| Excel | `src/lib/helpers.js`, `@linways/table-to-excel`, `xlsx` | Table downloads |

## Milestones visible in git

| When | Commit | What the subject records |
|---|---|---|
| 2023-11-03 | `978f2c9` | Initial commit |
| 2023-11-16 | `e0bb030` | "point to php" |
| 2025-09-10 | `30f818e` | Filters update only when Apply is clicked |
| 2025-09 to 2025-10 | `phase4` commits through `c6259e3` | Pivot tables, Excel formatting, grape and vineyard load rules, sidebar clear |
| 2026-08-25 | `8df1cad` | "fixed all issues and errors" |
| 2026-09-16 | `29cf45b` | Stop navigation from logging the user out |
| 2026-09-22 | `17d160e`, `937e09cb` | npm audit cleanup, merged as pull request #13 |

No git tag was found on `master`.

## Dependencies known from this repo

- Node toolchain: Create React App `react-scripts` 5.0.1, React 18.2.0, React Router DOM 7.18.2, Zustand 4.4.3, Bootstrap 5.2.3, ECharts 6.1.0, Axios is listed in `package.json` and is not imported by `src/` (calls use `fetch`).
- Google reCAPTCHA (`react-google-recaptcha`) on the login form. The site key in the committed `env` file is empty.
- Google Analytics 4, measurement id `G-1RFV9ZJG9K`, started from `src/index.js` after 3 seconds.
- External sites linked from the UI: `www.sawis.co.za` (register and forgot password), `mailto:bi@sawis.co.za`, `www.dawineonline.co.za`, `www.overdrive.co.za`.
- Deploy helper `master_deploy.php` calls deploy scripts on `lui.sawisonline.co.za` (Label) and `biqa.sawisonline.co.za` (BIQA, and also the case labelled BI). Tokens in that file are not copied here.

## Current status

`master` is a maintained CRA frontend whose latest merged work is the logout and dependency hotfix of 2026-09-22. The newer product surface (domestic sales, admin, and a Vite build) is on `qa` / `phase6_pr` and is not in this default branch.

Bitbucket Pipelines on `master` runs a SonarQube scan only. It does not build or test the app.

## Discrepancies

1. `DEVELOPER_DOCUMENTATION.md` describes React Router v6, ECharts 5.4.3, `oidc-client`, a dev server on port 3000, and Playwright specs under `tests/`. `package.json` has Router 7.18.2, ECharts `^6.1.0`, no `oidc-client`, `.env.development` sets port `44487`, and there is no `tests/` directory in git (`/tests` is gitignored).
2. The same document says authenticated routes redirect by auth state. `AppRoutes.js` has no guard. Gating is inside the Exports tabs.
3. `DEVELOPER_DOCUMENTATION.md` says the API is ASP.NET and SQL Server. `master` `setupProxy.js` only proxies `/weatherforecast`. The committed `env` file targets `http://localhost:8080`. Commit `e0bb030` says "point to php". The live API technology is **Unknown / Requires Confirmation**. `bi_tool_frontend_phase6/` records a CodeIgniter proxy on `phase_6`, which is a different branch.
4. `master_deploy.php` labels one case "Deploying to BI" and calls the BIQA host. The IP allow-list check is commented out. **Requires confirmation** before anyone treats that script as the production deploy.
5. Task-creation metadata said the tip was `c6259e3` (2025-10-24). The tip is `937e09cb` (2026-09-22).
6. `bi_tool_frontend_phase6/` is accurate for `phase_6` at `82d7ef04` and states other branches were not read. `origin/qa` has since moved to `584d8b7` (2026-10-16).

## Human confirmation

- Which branch (`master`, `qa`, or another) is what users open in production, QA, and label.
- Whether `https://bi.sawisonline.co.za` is still the production API host. It appears only as a comment in `env`.
- Whether the BI case in `master_deploy.php` should call a different host from BIQA.
- Whether domestic sales and admin on `qa` are approved scope for the default branch.