# Project plan — intersect_cloud

Evidence date: 2026-10-12.

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

Inspected revision: `main` at `6efd9251248643019e3602152f5e95bdcb68ef65` (2025-01-22 18:37:29 +0200, Jaco Brits, "fixes update"). `git ls-remote` reports that commit as `refs/heads/main`. A second remote branch, `prod`, points at `f72dda92542fa63e0db24dac53ee4067408f45cd` (2024-10-24 13:23:14 +0200, Dirk, "update prod arn"). No tags were on the remote.

The scan-host path `~/projects/sonar_scan/repos/intersect_cloud` was not on this machine. The tree below was read from git.

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

No `silicon_ark/intersect_cloud/` directory existed before these files. Silicon Ark already has `intersect_cloud_prod/`, `intersect_cloud_v2/`, and `intersect_lambda/`. Those are different repositories. See [Related repositories](#related-repositories).

## Product

The Flutter package name is `simpleflow_hub`. The Material app title, Android label, iOS display name, and web apple-mobile-web-app title are **Simpleflow Hub**. The web Open Graph title is **Simpleflow** and the description is **Simpleflow Process Hub**.

Provenance: **Implemented** in `pubspec.yaml` (`name: simpleflow_hub`, `version: 1.0.0+1`), `lib/main.dart` (`title: 'Simpleflow Hub'`), `android/app/src/main/res/values/strings.xml`, `ios/Runner/Info.plist`, and `web/index.html`.

The README title is also "Simpleflow Hub", then the FlutterFlow starter sentence "A new Flutter project." It does not describe customers, workflows, or goals. Provenance: **Documented**, and thin.

The Android application id and iOS bundle id are `co.za.intersectcloud.simpleflowhub`. Deep-link scheme `simpleflowhub` uses host `simpleflowhub.com`. Provenance: **Implemented** in `android/app/build.gradle`, `android/app/src/main/AndroidManifest.xml`, and `ios/Runner/Info.plist`.

The configured backend URL on `main` is `https://alb.simpleflowhub.app`, loaded from `assets/environment_values/environment.json`. The loader labels the current environment `demoQA`. Provenance: **Implemented** in `lib/environment_values.dart` and that JSON file. The anon key in the JSON is not copied here.

What the product does, from the screens and tables that are actually wired:

- A signed-in user works inside one tenant. A system admin (`user.user_role` stored as `Admin`) can open tenant, user, and client management. A tenant admin (`tenant_user_list.role` stored as `Admin`) opens a smaller management area.
- The phone shell is Home, Process Hub, Notifications, Tasks, and More. Wider layouts use a side nav.
- Process Hub shows processes linked to the current tenant and opens the list whose chip label matches `process.filter_name`.
- Form packs in the routed hub cover job cards, inspections, tasks, bookings, documents, support tickets, Pest Elite reports, and Plateau quality reports.
- The web build is what the pipeline deploys. Android, iOS (including an `ImageNotification` extension), and Windows projects are in the tree.

Who the commercial customers are, beyond names compiled into the code (Pest Elite, Plateau), is **Unknown / Requires Confirmation**. Whether `alb.simpleflowhub.app` is staging, demo, or production is **Unknown / Requires Confirmation**. `intersect_cloud_prod` points at `https://prod-alb.simpleflowhub.app` instead.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` | `6efd925` | 2025-01-22 | Inspected tree. Pipeline deploys this branch with the staging deployment variables |
| `prod` | `f72dda9` | 2024-10-24 | Older tree. Pipeline deploys this branch with the production deployment variables. Hardcodes the same `https://alb.simpleflowhub.app` URL inside `lib/backend/supabase/supabase.dart`. Does not contain `lib/environment_values.dart` |

The onboarding issue (OVER-160, captured 2026-09-28) recorded `main` at `6efd925` and the message "fixes update". This clone agrees.

A deepen of 15 commits on `main` retrieved 16 commits, from `232f179` (2024-11-06, "remove apk") through `6efd925`. `232f179` still has parent `0dcad9d`, which was not retrieved. History before that parent is **Unknown**.

`prod` was fetched at depth 1. Its parent is `b0e4416`, which was not retrieved. How `prod` relates commit-for-commit to `main` is **Unknown / Requires Confirmation**. The trees differ by thousands of files: `main` has the environment-values loader, later form work, and files that `prod` does not.

## Objectives (inferred from the app, not from a written plan)

No project plan or requirements document exists in the repository. The following are **Inferred** from the implemented screens and from commit messages that name a deploy:

- Give each tenant a branded workspace (logo and colours stored on the tenant).
- Run operational processes: tasks, job cards, inspections, bookings, documents, assets, support tickets, and messages.
- Carry tenant-specific form packs in the same app. The packs visible in code are a general set, a Pest Elite pest-control set, and a Plateau quality-report set.
- Let a system admin operate across tenants, and a tenant admin operate inside one tenant.
- Publish the Flutter web build to AWS (S3 and CloudFront). `main` uses the staging deployment; `prod` uses the production deployment.

## Scope

### In scope of `main`

- Flutter app `simpleflow_hub` version `1.0.0+1`, generated largely by FlutterFlow (custom-action headers say so).
- Targets present as projects: Android, iOS (including an `ImageNotification` extension), web, and Windows. No `linux/` or `macos/` project.
- Supabase client: auth (implicit flow), PostgREST table classes, storage uploads, and a set of RPC calls.
- Custom Dart for PDF generation, signatures, file upload, OTP helpers, theme colours, and HTML placeholder replacement.
- Bitbucket pipeline that deploys `build/web` to S3 and invalidates CloudFront.
- A committed `build/` tree, including `build/web`. `.gitignore` comments out `/build/`, so the build output is tracked. `git ls-files build` lists 74 paths on `main`.
- Local helper `commit.bat`, which runs `flutter pub get`, `flutter build web`, then `git add .`, commit, and `git push origin`.

### Out of scope / not in this repository

- The Supabase database itself: SQL migrations, RLS policies, Edge Functions, and the bodies of the RPCs the app calls. Only the client calls and generated row classes are here.
- The AWS account, S3 bucket name, CloudFront distribution id, and OIDC role. Those are pipeline variables (`$AWS_ARN`, `$AWS_PROD_ARN`, `$AWS_REGION`, `$AWS_S3_BUCKET`, `$DISTRIBUTION_ID`).
- Store listings. Nothing in git says the Android or iOS app is published. The release build type in `android/app/build.gradle` still uses the debug signing config.
- `intersect_cloud_prod`, `intersect_cloud_v2`, and `intersect_lambda`. See below.
- `sonar-project.properties` and `sonarqube_scan.bat`. OVER-160 listed both at the repository root. Neither file is in `6efd925`. `.gitignore` does not match those names.

## System architecture

```text
Browser / Android / iOS / Windows
        │
        ▼
Flutter app (simpleflow_hub)
  go_router pages, FlutterFlow widgets, FFAppState
        │
        ▼
https://alb.simpleflowhub.app
  Supabase auth (implicit flow) + PostgREST + storage + realtime client
        │
        ▼
Postgres tables and RPCs (not in this repo)

Web deploy path:
  committed build/web
    main branch → S3 via $AWS_ARN (deployment: staging) → CloudFront invalidation
    prod branch → S3 via $AWS_PROD_ARN (deployment: production) → CloudFront invalidation
```

The pipeline's compile step is commented out on both branches. The step that runs is deploy-only. Provenance: **Implemented** in `bitbucket-pipelines.yml`.

## Major components

| Component | Where | Role |
|---|---|---|
| App shell | `lib/main.dart` | Splash, auth stream, theme, bottom nav on phone (Home, Process Hub, Notifications, Tasks, More) |
| Router | `lib/flutter_flow/nav/nav.dart`, `lib/index.dart` | Named routes. Logged-out `/` shows Login |
| Auth | `lib/pages/auth/`, `lib/auth/supabase_auth/` | Email sign-in, forgot password, reset password, create-password page |
| Tenant session | `FFAppState` in `lib/app_state.dart` | Current tenant, system role, tenant role, colours, persisted in secure storage |
| Process Hub | `lib/pages/process_hub/process_hub/` | Tenant processes and the form lists those processes open |
| Management | `lib/pages/management/` | Tenants, users, clients. Routed pages live here |
| General forms | `lib/pages/general_forms/` | Routed tasks, assets, calendar, documents, support tickets |
| Pest Elite forms | `lib/pages/pest_elite/` | Site forms, checklists, action and recommendation reports. Opened from Process Hub, not as their own routes |
| Plateau forms | `lib/pages/plateau/` | Service, non-conformance, and corrective-action reports. Opened from Process Hub |
| PDFs and signatures | `lib/custom_code/` | Client-side PDF builders and signature pads |
| Data client | `lib/backend/supabase/database/tables/` | 111 generated table/view classes |
| API calls | `lib/backend/api_requests/api_calls.dart` | Direct PostgREST and RPC calls using the anon key, and the user token on some calls |

## Milestones visible in the fetched history

Messages are the commit subjects. They do not describe a product plan. File notes are from `git show --stat` on that commit.

| When | Commit | Subject | What the diff shows |
|---|---|---|---|
| 2024-11-06 | `232f179` | remove apk | Adds the Flutter project files (`pubspec.yaml`, Android project, README) and also adds `build/app/outputs/apk/release/app-release.apk`. Parent `0dcad9d` was not fetched |
| 2024-11-06 | `56ac800` | remove | Deletes `build/app/outputs/apk/release/app-release.apk` |
| 2024-11-25 | `de61736` | pestelite deploy | Job-card item struct/table and Pest Elite checklist table edits, plus a rebuilt `build/web/main.dart.js` |
| 2024-12-10 | `5e27cff` | qa deploy | Plateau report list tables, calendar struct, API calls, plus a rebuilt web bundle |
| 2024-12-19 | `e1365c9` | new bug changes | Adds `assets/environment_values/environment.json` and updates auth manager and app state |
| 2025-01-22 | `6efd925` | fixes update | Current `main` |

Eleven other commits in the same window use subjects such as "updates", "update", and "latest updates". They were not diffed one by one.

## Implementation plan

There is no forward plan in the repository. Current status: **`main` last changed 2025-01-22, `prod` last changed 2024-10-24, web deploy pipeline present and compile step commented out, database and cloud resources outside this repo**.

## Known dependencies

Runtime (selected; full pin list is `pubspec.yaml` / `pubspec.lock`):

- Flutter SDK `>=3.0.0 <4.0.0`. `.metadata` revision `4d7946a68d26794349189cf21b3f68cc6fe61dcb`, channel stable. The active pipeline downloads Flutter 3.10.0 and then runs `flutter upgrade`.
- `supabase_flutter` 2.6.0, `go_router` 12.1.3, `provider` 6.1.2.
- `flutter_riverpod`, `hive`, and `sqflite` are in `pubspec.yaml`. No Dart file under `lib/` imports them.
- `pdf`, `pdfx`, `signature`, `file_picker`, `image_picker`, `flutter_secure_storage`, `encrypt`.
- Barcode scanner and colour picker from FlutterFlow git refs.
- `sign_in_with_apple` is a dependency. The only `signInWithApple` hit under `lib/` is the method declaration on `AuthManager`. No page calls it.

Deploy:

- Bitbucket Pipelines, Atlassian S3 deploy pipe 1.1.0, CloudFront invalidation pipe 0.10.1, AWS OIDC.

## Related repositories

| Repository | Relationship |
|---|---|
| `intersect_cloud_prod` | Separate repository. Same Flutter package name `simpleflow_hub` and the same display name. Its inspected `main` (`f4affe1`, 2025-01-06) points at `https://prod-alb.simpleflowhub.app` and its pipeline deploys that `main` with `$AWS_PROD_ARN`. This repository's `main` points at `https://alb.simpleflowhub.app` and deploys with `$AWS_ARN` (staging). Silicon Ark: `intersect_cloud_prod/`. |
| `intersect_cloud_v2` | Empty apart from a starter `.gitignore` (commit `6dd7641`, 2024-09-27). It is not a second version of this app. Silicon Ark: `intersect_cloud_v2/`. |
| `intersect_lambda` | Separate repository. Its mail and Supabase behaviour is not this app's behaviour. Silicon Ark: `intersect_lambda/`. |

## Discrepancies found while onboarding

1. OVER-160's scan listed `sonar-project.properties` and `sonarqube_scan.bat`. They are not in git.
2. The pipeline compiles nothing. It deploys the committed `build/web`.
3. The environment loader's constant is `demoQA`. The JSON URL is `https://alb.simpleflowhub.app`. Some screens hardcode `https://www.demo.simpleflowhub.app/tasks` and `https://demo.simpleflowhub.app/`. `intersect_cloud_prod` uses `https://prod-alb.simpleflowhub.app`.
4. Router auth is required only for `SupportTicketList`. Other named routes leave `requireAuth` at its default, false.
5. Choosing a Process Hub filter deletes `job_card` rows whose `status` is null.
6. `pages/user_management/` and the Process Hub copies `process_hub_v1`, `process_hub_base`, `process_hub_pest_elite`, and `process_hub_plateau` are not exported by `lib/index.dart`. Imports of those paths only appear inside the same folders.
7. `prod` is the branch the pipeline sends to the production deployment, and it is older than `main` (2024-10-24 versus 2025-01-22). Both still name `https://alb.simpleflowhub.app`.

Details and provenance are in `prd.md`, `features.md`, `business-rules.md`, and `technical-documentation.md`.