# Project plan — label_system

Evidence date: 2026-10-10.

Source: `git@bitbucket.org:overdrive/label_system.git`, branch `master` at `c8b07d50` (2026-06-03, "Revert changes made by Jacques to match QA"). The checkout used for this plan was a depth-1 clone, so earlier history was not inspected commit by commit.

There is no prior `label_system` directory in Silicon Ark. The repository README still describes the **Admin Overdrive Starter** (authentication, menu management, CRUD generator). The running product is a SAWIS wine-label approval system built on that starter. The README and the product diverge. See the conflict list below.

The onboarding issue recorded last commit `d1ae9b8` (2025-11-25, "Fix note ids not being set properly"). That is not the current `master` tip. Whether `d1ae9b8` is an ancestor of `c8b07d50` was not verified on this shallow clone.

## Purpose

**Implemented.** Let SAWIS users submit wine-label artwork (PDF), record product data (trademark, producer, cultivar, alcohol, container), route the submission through a meeting group, and record approval, approval with provisions, rejection, contest, resubmission, or a dispensation request. Approval and rejection write meeting-minute notes and queue an email. A weekly analytics email reports year-on-year label volumes.

**Documented** only in fragments: `README.md` (starter features plus the weekly analytics cron), `CHANGELOG.md` (2026-01-21 analytics email), and `NewKnowledgeBase.md` (cron and timezone). There is no product plan, milestone list, or owner in the repository.

## Scope

In scope for this repository at `c8b07d50`:

- CodeIgniter 4 application under `app/`, public entry under `public/`, Spark CLI `spark`.
- Label submission, review, comments, file versions, email queue, meeting minutes, analytics, and system settings.
- Login against SAWIS Online, with a local password fallback.
- Menu-based authorisation inherited from the starter.
- Bitbucket Pipelines SonarQube scan on `master` and `qa`.

Out of scope of this repository, or present only as starter leftovers:

- SAWIS Online itself (`sysUser`, `sysLabelSystemLogin`, `tblMember`, `sysSecurity`, menus). This app only reads those databases.
- Whether production, QA, and training are actually deployed. Paths in code assume a `/label/public` document root when `baseURL` does not contain `.local`.
- The Jira board and Confluence space linked from the README (`SI` board, space `AO`). Those pages were not read.
- The car-finance, ChatGPT, master-file import, UI-test, and organisation JWT modules. They are in the tree. They are not described as the label product. Whether any customer still uses them is **Unknown**.

## Users

Role ids are hardcoded. Display names live in `user_role` and are not seeded beyond Developer. Names below are the comments in `app/Models/MenuModel.php` and `app/Controllers/Labels.php`.

| Role id | Name used in code comments | What the list does |
|---|---|---|
| 1 | Developer | Sees all active labels after the cutoff date |
| 2 | SAWIS Staff | Sees all active labels after the cutoff date |
| 3 | Label Committee / Label Board | Sees only labels in the user's meeting groups, and only status `2` |
| 4 | Producer | Sees labels whose producer matches SAWIS member names linked to the user, or labels they designed |
| 5 | Designer | Sees only labels where they are `user_designer_id` |
| 6 | Members / Farmers (upload comment only) | May upload and request dispensation. No list query exists for this role |
| 7 | Sawis Admin | Sees all active labels after the cutoff date |
| 8 | Sawis User who cannot use the label system | Mapped to a SAWIS menu group. No label list query |
| 9 | WCA Board | Sees all active labels after the cutoff date |

Provenance: **Implemented** (comments and queries). The stored `role_name` strings are **Unknown / Requires Confirmation** because they are database rows.

## Architecture

One PHP application. Sessions are stored in the `sessions` table. The label database is the default connection. SAWIS Online is a second connection chosen from `baseURL`:

- URL contains `.local` → `sawisOnlineDev`
- URL contains `qa.` → `sawisOnlineQa`
- URL contains `training.` → `sawisOnlineTRAINING`
- otherwise → `sawisOnline`

Hostnames and credentials are in `app/Config/Database.php`. They are not copied here.

Label artwork is stored on the web server under `uploads/` (and `uploads/dispensation/`). Imagick plus Ghostscript turns a single-page PDF into a JPEG. mPDF builds meeting-minute PDFs. Outbound mail is inserted into `sent_queue` and sent later by `GET /cronJobs`.

## Major components

- `Labels` — list, form, upload, submit, approve, reject, contest, dispensation, comments, certificate PDF.
- `LabelStatus`, `LabelUserGroups`, `LabelEmailTemplates`, `SystemSettings` — configuration screens.
- `MeetingMinutes` — minutes for a sitting, PDF, email, draft, signed copy.
- `Analytics` and `CronJobs::sendWeeklyAnalyticsReport` — on-screen counts and the Monday email.
- `Welcome` — SAWIS seamless login and local login.
- `Email` and `EmailPixelTracking` — queue a templated message and record an open pixel.
- Starter modules: users, menu management, CRUD generator, organisations API, car API, ChatGPT, master file, media and uploaded files, site health, database admin.

## Milestones

No milestone dates are in the repository. Schema history implies this sequence. Provenance: **Inferred** from migration timestamps, not from a plan.

1. 2022-11 — starter users, roles, menus, organisations.
2. 2023-06 to 2023-08 — starter cron, settings, car, master file, media, tests.
3. 2023-10 to 2023-12 — label, notes, files, log, status, provisions, meeting groups, email templates.
4. 2024-01 to 2024-05 — email queue, trademark, agent, CC list, provisions on the label, container types, cultivars, public holidays, saved comments.
5. 2025-01 to 2025-08 — meeting-minute drafts, notes, groups, documents, signed documents, blend cultivars.
6. 2026-01-21 — changelog entry for the weekly analytics email.
7. 2026-06-03 — current `master` tip reverts changes "to match QA".

## Current status

**Implemented** and on `master` as of 2026-06-03. `CHANGELOG.md` has a single dated section (2026-01-21). There is no version number. `composer.json` still names the package `codeigniter4/adminstarter` with description "Admin Overdrive".

Pipelines run SonarQube on `master` and `qa`. They do not deploy. How code reaches the `/label` vhost is **Unknown**.

## Known dependencies

- PHP `^8.0` with intl, mbstring, mysqlnd, json, xml, curl, fileinfo, and Imagick (used, not declared in Composer).
- Ghostscript on Windows at `C:/Program Files/gs/gs10.05.0/bin` when converting PDFs.
- CodeIgniter 4, mPDF 8, PhpSpreadsheet 1.25, `orhanerday/open-ai` 3.5, AWS SDK 3.254 (no `Aws\` usage was found under `app/`).
- MySQL for the label schema and for SAWIS Online.
- An external scheduler calling `GET /cronJobs`. The scheduler itself is not in the repo.
- SAWIS Online as the identity and member source.

## Conflicts that need a decision

- README product ("Admin Overdrive Starter") versus the label workflows in `Labels.php`.
- Issue metadata commit `d1ae9b8` versus `master` at `c8b07d50`.
- Role 2 is called Staff in `MenuModel` and is grouped with "Developers, Staff, WCA Board and Admin" in `Labels::index`. Confirm the live `user_role` names.
- `label_status` names are data. Code also hardcodes ids 0–12. The live names for ids 2, 3, 8, 9, 10, and 12 are **Unknown / Requires Confirmation**.