# Project plan — datafy_web (Datafy Web)

Evidence date: 2026-10-17.

Source repository: `git@bitbucket.org:overdrive/datafy_web.git`.

Inspected revision: `main` at `df8299e` (2026-01-19, "bitbucket-pipelines.yml edited online with Bitbucket").

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

There was no `silicon_ark/datafy_web/` directory before this document set. The application repository's own `README.md` is the Flutter default ("A new Flutter project") plus one sentence that FlutterFlow projects run on the Flutter stable channel. Provenance: **Documented**, and it does not describe product behaviour.

## Product

Datafy Web is a Flutter client, generated in FlutterFlow, for retail store execution. Signed-in users work with stores, products, tasks, promotions, KaChing challenges, surveys, and notifications. Store rows carry availability and stock-issue counts (out of stock, negative stock, stock on hand with no sales, seven-day cover, visibility, non-issues). A dashboard asks Supabase for store, rep, KaChing, promo, survey, and task totals for a customer.

Provenance: **Implemented** (`lib/main.dart` title `Datafy Web`, `web/index.html`, `lib/pages/includes/navbar/navbar_widget.dart`, `lib/backend/supabase/database/tables/store.dart`, `lib/custom_code/actions/get_dashboard_overview.dart`).

The public product name, the customers who use it, and whether a separate mobile app shares this Supabase project are **Unknown / Requires Confirmation**. A fallback profile image URL points at `https://alb.datafyapp.co.za`. The Supabase client in this repository points at `https://datafy.appmonitor.co.za`. Provenance: **Implemented** (`lib/pages/auth/login/login_widget.dart`, `lib/backend/supabase/supabase.dart`).

## Branch reality

Default branch is `main`. `origin/HEAD` points at `main`. No other remote branches were present at inspection.

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` | `df8299e` | 2026-01-19 | Pipeline edit. 52 commits from `7c71293` (2024-04-22, "Initial commit") |

Application updates are mixed with pipeline-only commits. Notable subjects include "latest update" (`dbb7ec0`, 2024-05-23), "update web" (`e1a62e0`, 2024-09-09), "Update to latest version" (`6689d99`), and "Add AWS deployment" (`fa4e0d7`). Which of those commits changed product screens was not diffed line by line. Provenance: **Implemented** (git history).

## Scope in the repository

In scope of what is implemented on `main`:

- A Flutter app (Dart SDK `>=3.0.0 <4.0.0`, package version `1.0.10+1`) targeting web, with Android, iOS, and Windows project folders also present.
- Email sign-in against Supabase Auth, then a read of the `user` row for name, role, and `super_admin`.
- Routed screens for dashboard, tasks, stores, products, promos, KaChing, surveys, notifications, profile, users, customers, SJ report, call sheet, survey create/view, and non-issues.
- Supabase table bindings for stores, products, tasks, surveys, promos, KaChing, customers, users, call sheets, and SJ reports.
- Spreadsheet-style upload and PDF/CSV/Excel export custom actions.
- An image-analysis POST from the tasks screen to an AWS API Gateway stage.
- Bitbucket Pipelines: SonarQube on `main`; a wider security-scan pipeline on pull requests; an AWS S3 and CloudFront deploy step that is defined and commented out on `main`.

Out of scope of the code that was found, or not present as a committed application:

- A written product requirements document, business-rule catalogue, or architecture description inside the application repository.
- Supabase SQL, Row Level Security policies, database functions, and Edge Functions. The client calls REST views and RPCs that live in the Supabase project, not in this repository.
- A running production URL for the Flutter web build. The pipeline names `$AWS_S3_BUCKET` and `$DISTRIBUTION_ID` and does not commit their values.
- Automated Flutter tests that exercise product behaviour. `test/widget_test.dart` pumps `MyApp` and asserts nothing. `tests/selenium/datafy_web.side` exists; the pull-request pipeline tries to run `tests/selenium/*.side` through a Python command that is not a Selenium IDE runner.

## System architecture

```text
Browser (Flutter web; path URL strategy)
  → GoRouter screens under lib/pages and a few top-level survey screens
  → FFAppState (flutter_secure_storage)
  → Supabase at https://datafy.appmonitor.co.za
      → Auth (email, implicit flow)
      → PostgREST /rest/v1  (tables, views)
      → RPCs (dashboard, scores, exports, activity)
      → Storage bucket "uploads" (public URLs)
  → AWS API Gateway eu-west-1 Stage POST /analyze-image
      (called from the tasks screen)

Bitbucket Pipelines (separate from the app runtime)
  → SonarQube at https://scan.appmonitor.co.za
  → On pull requests: Safety, Gitleaks, OWASP Dependency-Check,
    a Selenium step, then POST results to
    https://supabase.appmonitor.co.za/rest/v1/deploy_results
  → Defined, not active on main: S3 upload of ./build/web
    and CloudFront invalidation
```

Provenance: **Implemented**.

## Major components

| Component | Location | Role |
|---|---|---|
| App entry | `lib/main.dart` | Loads environment JSON, Supabase, theme, persisted app state, router |
| Router | `lib/flutter_flow/nav/nav.dart` | GoRouter routes. `requireAuth` stays at its default `false` on every route |
| Navigation | `lib/pages/includes/navbar/navbar_widget.dart` | Sidebar. Users and Customers render only when `superAdmin` is true |
| Auth | `lib/auth/supabase_auth/` | Email sign-in, sign-out, email update, password reset method, Apple sign-in method |
| App state | `lib/app_state.dart` | Role, super-admin flag, selected store/chain, store lists, survey answer drafts |
| Supabase client | `lib/backend/supabase/supabase.dart` | URL, anon key, `AuthFlowType.implicit` |
| Table bindings | `lib/backend/supabase/database/tables/` | 83 generated table/view classes |
| REST helpers | `lib/backend/api_requests/api_calls.dart` | `AllApisGroup` calls the same Supabase `/rest/v1` base |
| Custom actions | `lib/custom_code/actions/` | Uploads, exports, dashboard RPCs, image analysis, sign-up helpers |
| Custom widgets | `lib/custom_code/widgets/` | Dashboard charts, active users, task export |
| Pipeline | `bitbucket-pipelines.yml` | Scan and (commented) deploy |
| Web shell | `web/index.html` | Title "Datafy Web", `noindex`, "Built with FlutterFlow." |

## Milestones visible in git

These are commit dates, not an approved roadmap.

| When | Commit | Subject |
|---|---|---|
| 2024-04-22 | `7c71293` | Initial commit |
| 2024-04-22 | `76f1778` | falpha deploy commit |
| 2024-05-23 | `dbb7ec0` | latest update |
| 2024-09-09 | `e1a62e0` | update web |
| Later, before the tip | `fa4e0d7` | Add AWS deployment |
| 2026-01-19 | `df8299e` | bitbucket-pipelines.yml edited online with Bitbucket |

What "falpha" refers to is **Unknown / Requires Confirmation**.

## Implementation plan (as the repository stands)

There is no milestone plan in the repository. The current delivery shape is:

1. FlutterFlow generates the Dart client.
2. Custom actions in `lib/custom_code/` add exports, dashboard RPCs, uploads, and image analysis.
3. `main` runs SonarQube.
4. A deploy step that uploads `./build/web` to S3 and invalidates CloudFront exists and is commented out on the `main` pipeline.

Whether FlutterFlow is still the editor of record, and who publishes the web build, is **Unknown / Requires Confirmation**.

## Known dependencies

- Flutter stable (stated in `README.md`; the exact Flutter version pin is not in the repository).
- Supabase project at `https://datafy.appmonitor.co.za` (client, database, auth, storage).
- A second Supabase project at `https://supabase.appmonitor.co.za` used only by the pipeline to store scan results.
- SonarQube at `https://scan.appmonitor.co.za`. Project key `overdrive_datafy_web_d647d0ad-8efb-43dd-9f4e-35f28942bc1d` in `sonar-project.properties`.
- AWS API Gateway `https://i78eyrnc87.execute-api.eu-west-1.amazonaws.com/Stage/analyze-image`.
- AWS S3 and CloudFront, referenced only as pipeline variables.
- Packages of note: `supabase_flutter` 2.9.0, `go_router` 12.1.3, `fl_chart`, `excel`, `pdf`, `printing`, `file_picker`, `geolocator`, `google_fonts`. `webviewx_plus` is pinned to a FlutterFlow git commit.

## Current project status

The client on `main` is a large FlutterFlow application (about 570 Dart/YAML/Markdown files in the working tree, 774 git-tracked paths) with live-looking Supabase bindings and a Production environment flag (`FFDevEnvironmentValues.currentEnvironment = 'Production'`). Environment JSON only carries `"version": "5.31.7"`.

The `main` pipeline does not deploy. Route guards do not require authentication. Several screen families exist twice (`lib/pages/task` and `lib/pages/tasks`, `lib/pages/user` and `lib/pages/users`). Backup tables dated November 2024 are generated into the client (`store_backup_20241118`, `store_product_backup_20241128`).

Provenance: **Implemented**. Whether this revision is what users open in production is **Unknown / Requires Confirmation**.