# Project plan — sawis (SAWIS Online)

Evidence date: 2026-10-04.

Source repository: `https://bitbucket.org/silicon_bit_bucket/sawis.git`.

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

The companion API is documented separately under `silicon_ark/sawis_api/`. This repository is the SAWIS Online web application that calls that API for login and password reset.

## Product

**SAWIS Online** is the member and staff web application for SAWIS. The signed-in home page states the purpose in English and Afrikaans.

Documented on `home.php` (English):

- Purpose: assist the wine industry by turning data into information.
- Vision: be the indispensable data technology resource to the wine industry, with online, real-time access to relevant information.
- Mission: furnish timely, accurate, needs-based information to industry role players, apply the industry’s origin system, and provide support services.
- Promise: collaborate to access data, process it, and make the information easy to access.
- Values named on the page: competitive advantage, confidentiality, confidence, creativity.
- Core principles include confidential treatment of individual information, open communication, neutrality, and co-ownership of SAWIS.
- Strategic headings on the page: WISE, focus on clients, information technology, training and development, workplace management.

Provenance: **Documented** in `home.php`. The acronym SAWIS is not expanded in the repository. **Unknown / Requires Confirmation** what the letters stand for in current organisation language.

Public host names in `system.php` and `system.server.PROD.php`: `www.sawisonline.co.za` and `sawisonline.co.za`.

## Branch reality

Inspection for this document is `dev_2020` at `069966f31413b5a1717a40e62ee71c723a436986` (2026-09-14), subject “Merged in PHP_UPGRADE_8.2_2025_NEW_FEB25 (pull request #1747)”.

The onboarding task was created against an earlier tip of the same branch: `592b278f` (2026-02-02), “Merged in PHP_UPGRADE_8.2_2025_NEW_FEB25 (pull request #1723)”. The branch moved between those dates. This set describes the 2026-09-14 tip.

| Line | Tip | Date | What the tip commit says |
|---|---|---|---|
| `dev_2020` (inspected) | `069966f` | 2026-09-14 | Merge of `PHP_UPGRADE_8.2_2025_NEW_FEB25`, pull request #1747 |
| `master` (default `HEAD`, not inspected file by file) | `da74b067` | 2025-10-08 | “Merge branch `prod_2020`” |
| `QA_2020` | present on the remote | not read | Deploy script targets a lowercase name `qa_2020` |
| `PHP_UPGRADE_8.2_2025_NEW_FEB25` | `d60a7dd` | not read beyond the merge | Named PHP 8.2 upgrade branch already merged into `dev_2020` by PR #1747 |

`bitbucket-pipelines.yml` runs SonarQube on branches `master` and `dev_2020`, and on every pull request. It does not name `prod_2020` or `QA_2020`.

`deploy.php` fetches `origin/qa_2020` and runs `git reset --hard origin/qa_2020`. The remote branch list shows `QA_2020`, not `qa_2020`. Whether Bitbucket treats those as the same ref is **Unknown / Requires Confirmation**.

Which branch is deployed to `www.sawisonline.co.za` is **Unknown / Requires Confirmation**. `master` is older than `dev_2020` and was not used as the evidence base.

Other remote branch names that are not the `dev_2020` tip, and were not diffed:

- `feature/20260623-Russel-SendEmailViaSMTP`
- `feature/20260701-Russel-blnInitialFinalLitresChanges`
- `feature/640-my-tanks-list` and `feature/640-my-tanks-list-2`
- `prod_2020` is named by the `master` merge commit. Its tip was not fetched for this pass.
- Many older `feature/ET2023*` and `critical_copies/*` branches.

Whether those feature branches are already contained in `dev_2020` was not proven from ancestry. Treat them as open lines until a human compares them.

## Objectives (from the home page and the implemented modules)

No project plan or README exists in the repository. `NewKnowledgeBase.md` is a dated implementation note log (entries from 2025-01-08 through 2026-02-02 on this tip). It is not a product plan.

Objectives **Documented** on `home.php`, and **Inferred** from the modules that exist:

- Give wine-industry members and SAWIS staff a signed-in place to maintain membership, farms, vineyard blocks, cellars, tanks, harvest loads, blends, certification numbers (WS and WSB), bottling, duties, losses, and transfers.
- Apply an origin and certification information system (WS / WSB numbers, blend master, traceability back to a legacy mapper).
- Keep individual information inside the member’s own records, with SAWIS admin groups able to see across members.
- Offer the interface in English and Afrikaans.
- Produce operational reports (harvest, fortification, SAWIS 5, SAWIS 10, cellar stock, block totals, tank walkthrough, WS/WSB transactions).

## Scope

### In this repository

- PHP pages at the web root, one script per area (`member.php`, `tanks.php`, `my.tanks.php`, and the rest of that pattern).
- Class files under `includes/` (about 90 domain classes).
- The Nemo UI framework under `_framework/` (list, details, menu, email, database, wizard, report, password, breadcrumbs, translations).
- Environment maps: `system.server.PROD.php`, `system.server.QA.php`, `system.server.DEV.php`, `system.server.TRAINING.php`, `system.server.LOCAL.php`.
- Daily cron `_cron.daily.php`.
- WSB traceability workers (`start.wsb.number.traceability.data.retrieval.process.php`, `get.and.store.wsb.number.traceability.data.php`, `check.wsb.number.traceability.data.retrieval.status.php`).
- Vendored PDF and spreadsheet libraries (`mpdf` via Composer, plus `dompdf`, `fpdi`, `PHPExcel`).
- Document storage folders under `documents/`.
- SonarQube pipeline only. No application test suite.

### Out of this repository

- `sawis_api` (separate repository; Silicon Ark folder `sawis_api`). Login and `setPassword` are HTTP calls into that API.
- The legacy mapper reached at `{MapperAPIServerPath}/ice/default.asp` (service `WSBNUMQUERY3`). The mapper application is not in this tree.
- Stellenbosch GIS endpoint `https://sungis10.stb.sun.ac.za/sawisvm/`, called from `my.farms.php` and `forsilicon.html`.
- Menu labels and security-entity rows. They live in MySQL (`sysMenuLevel1`, `sysMenuLevel2`, `sysSecurity`, `sysSettings`). The full menu a user sees cannot be listed from git alone.
- Production deploy procedure beyond `deploy.php` (QA hard reset) and the host map in `system.php`.

## System architecture

```text
Browser
  → PHP page (root *.php)
    → system.php
        → one system.server.*.php chosen by HTTP host
        → MySQL database sawis | sawis_dev | sawis_training
        → sysSettings loaded into $SystemSettings
    → includes/*.cls.php (domain)
    → _framework Nemo (HTML list / details / menu)
  → sawis_api (api.php) for vendor authenticate, loginUser, setPassword
  → mapper ASP (WSBNUMQUERY3) for WSB certification numbers not only in tblBlendMaster
  → SMTP via NemoEmail (settings keys such as "SMTP Send As Sawis3")
  → sungis10 farm map (browser POST of a farm id)
```

Two databases are used by one login:

1. The SAWIS Online database (`sawis` in production) holds members, cellars, tanks, and users (`sysUser`).
2. The API database (`sawis_api`) holds `apiVendor` and is the target of `loginUser`. `index.php` switches the mysqli connection with `switchBD()` for the vendor lookup, then calls the API over HTTP.

A sync lock in `system.php` polls `sysSettings.blnSyncInProgress` for up to 60 seconds and then dies with “DATABASE LOCK TIMEOUT”. What writes that flag is **Unknown** from this repository (likely an external sync into this database).

## Major components

| Component | Role | Evidence |
|---|---|---|
| Membership and registration | New member, link to existing member, change of cellar ownership. Wizard sessions `S3REGISTRATION`, and farm registration via `Nav=SAWIS2` | `registration.member.php`, `includes/member.registration.cls.php`, `registration.farm.php` |
| Farms, blocks, single vineyard | Vineyard register, vine counts, SAWIS 1 PDF | `farm.php`, `block.php`, `single.vineyard.php`, `documents/SAWIS_1_Reports/` |
| Harvest / BG1 | Harvest declarations, IPW checks, wine descriptors | `BG1.php`, `includes/BG1.cls.php`, `loads.php` |
| Cellar tanks and stock | Tank register, stock movement, press register, loss | `tanks.php`, `stock.movement.php`, `press.register.php`, `loss.php` |
| Blends and certification | Blend sandbox, blend master, WS and WSB numbers | `blend.sandbox.php`, `blend.master.php`, `ws.php`, `wsb.numbers.php` |
| Traceability | Walk a WSB number through blend master and the mapper | `includes/wsb.number.traceability.cls.php`, `get.and.store.wsb.number.traceability.data.php` |
| Duties, bottling, transfers | SARS-oriented documents, bottling notices, wine transfers, inspector audit | `duties.php`, `bottling.applications.php`, `wine.transfers.php` |
| Access control | Security groups, per-entity view/save/delete/special, member-company switch, pilot-group page gate | `_framework/_nemo.menu.cls.php`, `system.php`, `cellar.access.php` |
| Reporting | Admin and member report catalogues | `report.php` |
| Housekeeping | Users, email templates, FAQ, settings, IP block, navigation analytics | `user.php`, `email.php`, `faq.php`, `settings.php`, `ip.block.php` |

Member-facing scripts are prefixed `my.` (`my.tanks.php`, `my.loads.php`, `my.duties.php`). The unsuffixed scripts are the staff/admin counterparts. That split is **Inferred** from the file pairs and from admin-only filters (security group IDs 1 and 2).

## Milestones visible in the tree

There is no milestone plan in git. The history that can be stated from branch names and file comments:

| When | What | Status |
|---|---|---|
| 2014–2018 | Nemo pages for members, farms, blocks, tanks, email, security groups. Comments name authors pj, Gael, maanie, jacques, Rachel, Neils | **Implemented** (comments and classes still present) |
| 2016-11-24 onward | BG1 / IPW harvest work | **Implemented** (`includes/BG1.cls.php`) |
| 2017-08-02 | Login moved to API `loginUser` | **Implemented** (`index.php`) |
| 2020 | Branch family `dev_2020`, `QA_2020`, `Default_2020`, `prod_2020` | Branch names exist. Which one is production is **Unknown** |
| 2021-06-21 | Blend Sandbox created | **Implemented** (`includes/blend.sandbox.cls.php`) |
| 2022-03-01 | Blend Master page created | **Implemented** (`includes/blend.master.cls.php`) |
| 2024 | Training server settings added | **Implemented** (`system.server.TRAINING.php`, comment “2024 - jacques”) |
| 2025–2026 | PHP 8.2 upgrade branches, merged to `dev_2020` through PR #1747 (2026-09-14) | **Implemented** on `dev_2020`. Runtime PHP version on each host is **Unknown** |
| 2026-01 to 2026-02 | Notes in `NewKnowledgeBase.md`: duties export alignment, bottling WSB lookup scoped by tank, blend-sandbox single-vineyard warnings, initial-final litres flags, navigation analytics batching, movable tanks | **Implemented** as notes on this tip. Each note is a code change, not a signed-off requirement |

## Implementation plan

No forward plan is written in the repository. Open remote branch names suggest work that may still be in flight:

- SMTP send path (`feature/20260623-Russel-SendEmailViaSMTP`).
- Further `blnInitialFinalLitres` behaviour (`feature/20260701-Russel-blnInitialFinalLitresChanges`). `NewKnowledgeBase.md` already describes a version of that flag on `dev_2020`.
- “My tanks” list (`feature/640-my-tanks-list`).

Do not treat those names as approved scope. **Requires Confirmation** which of them should land, and on which branch production runs.

## Known dependencies

- PHP with `mysqli` and `curl`.
- MySQL databases `sawis` (production and QA), `sawis_dev` (some localhost maps), `sawis_training`, and the separate `sawis_api` database.
- Composer package `mpdf/mpdf` ^8.2. `composer.json` has no other requirements and no PHP platform pin.
- Vendored `dompdf`, `fpdi`, `PHPExcel`, `Sauer_Pagination_Library`.
- SAWIS API (`api.sawisonline.co.za` in production). See `silicon_ark/sawis_api/`.
- Legacy mapper ASP service `WSBNUMQUERY3`.
- SMTP settings stored in `sysSettings`, not in git.
- SonarQube (`SONAR_HOST_URL`, `SONAR_TOKEN`) for the Bitbucket pipeline. Project key `SAWIS`.

## Current project status

**Implemented** and actively changed on `dev_2020` through September 2026. The application is a large procedural PHP system, not a framework rewrite.

**Not established:**

- Which git branch matches production, QA, and training hosts.
- Whether `master` (October 2025, merge of `prod_2020`) is still what `www.sawisonline.co.za` serves.
- A written product roadmap.
- An automated test suite. `checkMemberAccessTest.php` is a manual script with commented example IDs. Pipelines run SonarQube only.

## Human confirmation

1. Confirm the branch that is deployed to `www.sawisonline.co.za`, `qa.sawisonline.co.za`, and `training.sawisonline.co.za`.
2. Confirm whether `deploy.php` is reachable on a public host. It runs `git reset --hard` with no login check in the file.
3. Confirm the open feature branches above are still wanted.
4. Training settings point the API hostname at `api.sawisonline.co.za` / `10.0.0.173` while the training site database is `sawis_training`. Confirm that training logins are supposed to use the production API database.