# SAWIS BI Tool – User Flow / Scope

This document describes how to use the SAWIS BI (Business Intelligence) frontend application: main routes, user roles, and step-by-step flows.

---

## 1. Application Overview

- **Name:** SAWIS BI (SA Wine Industry Information and Systems – Business Intelligence)
- **Purpose:** View and analyze wine industry data: export reports, grape production, vineyard status, and (for logged-in users) value/currency data and price ranges. Admin users can manage mapper imports and lookups.
- **Tech:** React 18, React Router 6, Zustand, Bootstrap/Reactstrap. API base URL from `REACT_APP_API_BASE_URL`.

---

## 2. Routes and Access

| Route | Description | Access |
|-------|-------------|--------|
| `/` | Home – landing and navigation to main sections | All |
| `/reports` | Export Reports – overview, tables, price range, generated reports | All (some tabs need login) |
| `/grape-production` | Grape Production – pivot reports with filters | All |
| `/vineyard-status` | Vineyard Status – pivot reports with filters | All |
| `/admin`, `/admin/*` | Admin – mapper import prep, lookups | Admin only (see 3.2) |

---

## 3. User Roles and Auth

### 3.1 Anonymous (not logged in)

- Can use: **Home**, **Export Reports** (Overview, Volume, Value placeholder, Price Range prompt), **Grape Production**, **Vineyard Status**.
- Export Reports: **Volume / Value** shows “Volume” only; **Value** tab shows “Log in to compare volume data with currencies”; **Price Range** shows “Log in to compare price ranges for exports”; **Reports** tab is not shown.
- Session: App attempts **auto-login** from cookies on load (`authStore.autoLogin`). If valid cookie exists, user is treated as logged in.

### 3.2 Logged-in user (no admin)

- **Login:** Navbar → “Login” → modal: Sign In (email, password, reCAPTCHA) → Accept Disclaimer → session stored in cookies.
- **Logout:** Navbar → user name/icon → Sign Out modal → confirm.
- Export Reports: **Volume / Value** includes value/currency; **Value** tab hidden; **Price Range** and **Reports** tabs visible and usable.
- **Admin** link is not shown.

### 3.3 Admin user

- Same as logged-in user, plus:
- **Admin** link in navbar (when `user.admin_role` > 0).
- Access to **Admin** routes; non-admins are redirected to `/` by `AdminRouteGuard`.

---

## 4. User Flows (How to Use)

### 4.1 Home

1. Open app → **Home** (`/`).
2. Banner and three navigation cards:
   - **Export Reports** → `/reports`
   - **Grape Production** → `/grape-production`
   - **Vineyard Status** → `/vineyard-status`
3. Footer: “Terms of Use” (Disclaimer modal), source link (Wine Online), Silicon Overdrive logo.

### 4.2 Login

1. Navbar → click **Login** (or user icon when logged in).
2. Modal opens:
   - **Sign In:** Email, Password, reCAPTCHA → **Sign In**.
   - On success → **Disclaimer** text → **Accept** or **Cancel**.
3. On **Accept:** user is set in store and cookies; modal closes; navbar shows user name and Logout.
4. “Forgot Password?” and “Create One” link to external SAWIS pages.

### 4.3 Logout

1. Navbar → click user name/icon.
2. Modal: “Are you sure you want to sign out?” → **Yes** or **Cancel**.
3. On **Yes:** cookies cleared, user cleared, modal closes.

### 4.4 Export Reports (`/reports`)

- **Layout:** Collapsible **sidebar (filters)** on the left; main area with **tabs** and content. Sidebar is hidden on **Price Range** tab.
- **Sidebar filters:** Producer/Role Player, Year, Ending Month, Reporting Period (months), Product Type, Package Type, Country (with “Select All”), Cultivar/Type. **Apply** sends filters; **Clear** resets to defaults. When logged in, producer options are loaded; when not, producer filter can be hidden.
- **Tabs:**

| Tab | Purpose | Login required |
|-----|---------|----------------|
| **Overview** | Charts: export by product type, exports over time, cultivar, top 25, etc. | No |
| **Volume / Value** | Volume-only when anonymous; Volume + Value (currencies) when logged in. Tables with year comparison, producer tables when producer filter is not “Industry”. | Value: Yes |
| **Value** | Shown only when **not** logged in: prompt to log in to compare volume with currencies. | N/A |
| **Price Range** | Create/compare up to 5 price-range tables by country etc.; add via “Create” in form. | Yes |
| **Reports** | Generated reports table (year/groups selection, refresh, export to Excel). | Yes (tab only visible when logged in) |

**Typical flow:**

1. Go to **Export Reports**.
2. (Optional) Set filters in sidebar → **Apply**.
3. Switch tabs to view **Overview** charts or **Volume / Value** tables.
4. If logged in: use **Price Range** to add/compare price tables; use **Reports** to view/export generated report data.

### 4.5 Grape Production (`/grape-production`)

1. Open **Grape Production** from Home or nav.
2. **Sidebar:** Filters (e.g. Year, single/multi-select) loaded from API; choose values → **Apply** (or **Clear**).
3. Main area: list of report items (from `/getGrapeProductionReports`). Each item is a **GenericPivotTable**: name, description, type selector (if applicable), **Generate Report** loads data from item URL with selected filters; table and export options follow.

### 4.6 Vineyard Status (`/vineyard-status`)

- Same pattern as **Grape Production**: sidebar filters, report list from `/getVineyardStatusReports`, each item rendered as **GenericPivotTable** with generate report and table/export.

### 4.7 Admin (`/admin`)

- **Access:** Navbar **Admin** (admin users only).
- **By role:**
  - **DAFF (role 1):** sidebar shows **Tools** only; `/admin` lands on `/admin/tools`. Direct `/admin/users` or `/admin/submissions` redirects to tools.
  - **Super User (role 3):** sidebar shows **User management** and **SAWIS 7 Submissions** (no Tools); `/admin` lands on `/admin/submissions`. Direct `/admin/tools` redirects to submissions.
  - **Other admin roles (2, 4):** **Tools** (default landing), **User management**, and **SAWIS 7 Submissions**.
- **Submission status actions:**
  - **Cancel:** available on submission review when status is **Open** or **Submitted** for roles **2, 3, 4**. Sets status to **Cancelled** and locks editing.
  - **Open up:** available on submission review when status is **Cancelled** or **Missed** for roles **2, 4** only. Sets status back to **Open** so editing can resume.
- **Tools sections:**
  - **Mapper Import Prepper:** Table of mapper processing sheet history (search, columns e.g. id, status, step, admin_email, sent_at). **View** opens modal with file process details. **Upload** opens **Upload Import Wizard** (drag-and-drop or file picker for .xlsx/.xls/.csv; upload and processing feedback).
  - **Mapper Lookups:** CRUD for lookup entities (data tables with Add/Edit/Delete, modals for create/edit).
- **Typical Tools flow:**
  1. Go to **Admin**.
  2. **Mapper history:** Search if needed → **View** for details or **Upload** to start wizard → select file → upload and monitor result.
  3. **Lookups:** Use table actions to add, edit, or delete lookup entries as needed.

---

## 5. Global UI Elements

- **Navbar:** Logo/banner, Home / Exports / Grape Production / Vineyard Status, Login|user + Logout, Admin (if admin), Contact (mailto).
- **Footer:** Disclaimer modal, Wine Online link, Silicon Overdrive logo.
- **Modals:** Login, Logout, Disclaimer, Terms of Use, and various content modals (e.g. View process details, Lookup forms).

---

## 6. Key Technical Notes

- **Auth:** Zustand `authStore`; cookie stores token, email, admin_role, admin_email; `autoLogin` on app mount.
- **Export Reports data:** `filterStore` (filters, reporting data, chart/table state); refetches when filters or user change.
- **Grape Production / Vineyard Status:** Dedicated stores (`grapeProductionStore`, `vineyardStatusStore`) for filters and selected values; report list from API; each report item uses `GenericPivotTable` with POST to item URL for generated data.
- **Price Range:** `priceRangeStore` (filters, filter history, data); logged-in only; up to 5 tables.
- **Generated Reports:** `GeneratedReportPivotTable` uses `filterStore` and auth; Excel export via table-to-excel.

---

## 7. Scope Summary

- **In scope:** All flows above (Home, Login/Logout, Export Reports including Overview/Tables/Price Range/Reports, Grape Production, Vineyard Status, Admin mapper import and lookups).
- **Out of scope (for this doc):** Backend API contracts, deployment, env vars (except where they affect usage), and non-BI features not present in this frontend.

---

*Document generated from codebase analysis. Update this file when adding new routes or major user-facing flows.*