# Project plan — bi_tool_frontend_phase6

Evidence date: 2026-10-19.

Source repository: `git@bitbucket.org:overdrive/bitool_frontend.git`, branch `phase_6` at `82d7ef04` (2026-08-21, Jason Wandrag, "Domestic reports and Firefox bugfixes").

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

The task-creation path `~/projects/sonar_scan/repos/bi_tool_frontend_phase6` was not present on this machine. Evidence is a single-branch clone of `phase_6`. The remote also has `master`, `qa`, `phase3` through `phase5`, `phase6_pr`, and several feature and bugfix branches. Those branches were not checked out.

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

## Product

**Documented** in `README.md`, `scope/User_Flow_Scope.md`, and `public/index.html`: a SAWIS BI web application. The HTML title is "SAWIS Report". `package.json` name is "SAWIS BI".

**Implemented:** a Create React App single-page application. Logged-out visitors can open Home, Export Reports, Grape Production, and Vineyard Status. Logged-in users also get Domestic Sales. Users with `admin_role` greater than 0 get an Admin area (mapper tools and, by role, SAWIS 7 user management and submissions).

The browser talks to a separate API. Development proxies that API to a CodeIgniter 4 process on port 8080 (`src/setupProxy.js`). `DEVELOPER_DOCUMENTATION.md` still draws the backend as ASP.NET and SQL Server. That diagram is **not** what `setupProxy.js` and the Phase 6 README describe. See Discrepancies.

## Branch reality

| Item | Evidence |
|---|---|
| Documented tip | Issue metadata and `git log -1`: `82d7ef04`, 2026-08-21 |
| History on this clone | 341 commits reachable from `phase_6` (single-branch clone, so this is not the whole remote) |
| First commit on this history | `978f2c9`, 2023-11-03, Jaco Brits, "Initial commit" |
| Authors on this history | Jason Wandrag 265, Ettiene 56, Jaco Brits 17, Lloyd 3 |
| Recent work | July–August 2026 Phase 6 domestic capture, auth guards, plain-language messages, Firefox layout, domestic reports |

`CHANGELOG.md` heading is `[Unreleased]`. No release tag was inspected. Treat "unreleased" as "not cut as a version in this file", not as "absent from the branch". The behaviours listed there are present in `82d7ef04`.

## Objectives visible in the repository

These are recovered from README, changelog, and commits. They are not a signed product charter.

1. Show wine-industry export, grape production, and vineyard status reports in the browser, with charts, pivot tables, and Excel export.
2. Let a signed-in user see value and currency figures and build price-range tables.
3. Let linked producers capture a SAWIS 7 domestic return (volumes, cultivar lines, draft, submit) and let certain admin roles review it.
4. Let admin roles prepare mapper import files and maintain lookup tables used by export processing.
5. Keep the CRA toolchain and reduce npm audit findings without ejecting `react-scripts`.

## Scope on `phase_6`

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

- Home
- Domestic Sales (`/domestic/reports`, `/domestic/capture`) — login required
- Exports (`/reports`)
- Grape Production (`/grape-production`)
- Vineyard Status (`/vineyard-status`)
- Admin (`/admin/tools`, `/admin/users`, `/admin/submissions`, `/admin/submissions/:id`) — `admin_role` > 0

Out of this frontend, **confirmed by absence of routes**: account registration and password reset (the login modal links out to `sawis.co.za`), the API and database, and any mobile native app.

`scope/User_Flow_Scope.md` section 2 does not list `/domestic`. Section 4.7 does describe the admin role split. The scope file is partly behind the code. See Discrepancies.

## System shape

```text
Browser (React 18 SPA, Zustand)
  │
  ├─ same-origin fetch when REACT_APP_API_BASE_URL is empty
  │     CRA dev proxy (src/setupProxy.js) → http://localhost:8080
  │     paths: /loginAuth, /auth/*, /admin/*, /get*, /tables/*,
  │            /grapeProduction/*, /vineyardStatus/*
  │
  └─ absolute REACT_APP_API_BASE_URL in other environments
        Authorization: <token>   (no "Bearer " prefix)

Leftover: /weatherforecast is proxied to an ASP.NET URL.
No page in AppRoutes calls it.
```

Provenance: **Implemented** in `setupProxy.js` and the API modules. The CI4 sentence is a comment in `setupProxy.js`, not a copy of the backend repository.

## Major components

| Area | Where it lives | Role |
|---|---|---|
| Shell | `src/App.js`, `src/components/Layout.js`, `src/components/Navbar.js` | Router, nav, disclaimer footer, login modal |
| Auth | `src/store/authStore.js`, `src/components/forms/LoginForm.jsx` | `loginAuth`, cookie session, disclaimer gate |
| Exports | `src/pages/Reports.js`, `src/store/filterStore.js`, `src/components/tabs/*`, `src/components/pivotTable/*` | Overview charts, volume/value tables, price range, generated RSA export report |
| Grape / vineyard | `src/pages/GrapeProduction.js`, `src/pages/VineyardStatus.js`, `GenericPivotTable.jsx` | Filter sidebar and pivot reports |
| Domestic | `src/pages/domestic/*`, `src/api/domestic*.js`, `src/components/domestic/**` | Reports and SAWIS 7 capture |
| Admin | `src/pages/admin/*`, `src/components/admin/*` | Mapper tools, users, submission review |
| Permissions | `src/utils/domesticPermissions.js` | Role and `domestic.permissions` checks |

## Milestones visible in git (not a formal plan)

| When | What the commits say | Provenance |
|---|---|---|
| 2023-11 | Initial CRA app | `978f2c9` |
| Through 2026-05 | Export reports, admin mapper UI, table display | Ettiene / Jason commits on this history |
| 2026-06-05 | Admin page and logout-on-error behaviour | Ettiene |
| 2026-07-08 | "Initial screens" | Jason Wandrag |
| 2026-07-14 | Phase 6.1 auth/linking and 6.2 capture UI | `a6c2b8b` |
| 2026-08-05 to 2026-08-21 | Phase 6 flow, guards, drafts, Firefox, domestic reports | commits through `82d7ef04` |

There is no milestone document that says Phase 6 is finished or what Phase 7 is. **Unknown / Requires Confirmation.**

## Known dependencies

- Node toolchain for CRA 5 (`react-scripts` 5.0.1) via CRACO. `package.json` `build` sets `NODE_OPTIONS=--max-old-space-size=8192`.
- Backend that implements `/loginAuth` and the paths listed above. Local default target `http://localhost:8080`.
- `REACT_APP_LOGIN_PAYLOAD_KEY` when the API base is not localhost (AES-256 login body). Dev proxy sends plain JSON.
- Google reCAPTCHA site key `REACT_APP_RECAPTCHA_DATA_SITE_KEY`, unless `REACT_APP_DISABLE_RECAPTCHA=true`.
- SheetJS `xlsx` from the SheetJS CDN tarball pinned in `package.json`.
- Google Analytics 4 script initialised in `src/index.js`.
- SonarQube on Bitbucket Pipelines for branch `master` only (`bitbucket-pipelines.yml`). `phase_6` is not in that pipeline file.

## Current status

**Implemented on `phase_6` and described as current in the README Phase 6 section:** domestic lookups, submission open by producer code + period + country, saved totals v2, back-page row CRUD, help, public domestic report endpoints, admin list/approve/unlock, producer-list verify/sync.

**Still called a gap in code comments:** `GET auth/domestic/me` is treated as a 404/403 gap. The client keeps the `domestic` block from login, or rebuilds a permission object from role numbers (`src/api/domesticAdmin.js`, `authStore.refreshDomesticProfile`).

**Lookup and help 404s** fall back to fixtures in `src/data/domestic/lookupsFixture` (`domesticLookups.js`). That is a client fallback, not evidence that production lookups are fixtures.

## Discrepancies to confirm

1. `DEVELOPER_DOCUMENTATION.md` says ASP.NET, SQL Server, React Router v6, ECharts 5.4.3, and `oidc-client`. `package.json` has `react-router-dom` ^7.18.2, `echarts` ^6.1.0, and no `oidc-client`. The dev proxy targets a CI4 comment and port 8080.
2. `scope/User_Flow_Scope.md` route table omits Domestic Sales and still says vineyard reports POST. `GenericPivotTable.jsx` uses GET when `Type` is `VineyardStatus`.
3. `master_deploy.php` "BI deploy" calls the same BIQA URL as the "BIQA deploy" case. Hosts are `lui.sawisonline.co.za` (Label) and `biqa.sawisonline.co.za` (BIQA and the BI case). Tokens are hard-coded in that file and are **not** copied here.
4. Changelog and the user-flow doc say Cancel locks editing. The producer capture form sets read-only only for `submitted`, `approved`, and `synced` (`ProducerCapturePanel.jsx`). Cancelled is locked on the admin review page, not in that producer flag.
5. `NavMenu.js` shows Admin only when `admin_role` < 0. `Navbar.js` (the bar `Layout` renders) uses `admin_role` > 0. Home's `NavMenu` usage is commented out.