# Project plan — flutterflow_sync

Evidence date: 2026-10-15.

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

Inspected revision: `main` at `8525b9f` (2025-09-04 16:31:58 +0200, Jaco Brits `jaco@overdrive.co.za`, "first commit"). Full hash: `8525b9f526eb25cd9b2452a10ec88a9712e90180`. That commit is `origin/HEAD`. The only remote branch is `main`. There are no tags. The commit has no parent.

The scan-host path named on the onboarding issue (`~/projects/sonar_scan/repos/flutterflow_sync`) was not on this machine. The tree below was read from a clone of the git revision above. That revision is the same commit the issue records.

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

## Product

**Documented.** `README.md` titles the repository **FlutterFlow-Supabase Sync Middleware**. It describes a middleware server that syncs a FlutterFlow app with Supabase, keeps a local MySQL copy, and ships a monitoring dashboard plus a Flutter client library.

`package.json` names the server `flutterflow-sync-middleware` version `1.0.0`. The dashboard package is `flutterflow-sync-dashboard` `1.0.0`. The Flutter package is `flutterflow_sync_client` `1.0.0`.

`CHANGELOG.md` calls `1.0.0` the initial release and dates it `2024-01-XX`. The only git commit is 2025-09-04. Nothing in git explains the date placeholder.

The sync queries name store, survey, promo, stock, and task tables (`sync_rules.yaml`, `server/src/config/syncConfig.js`). The README does not name the FlutterFlow app those tables belong to.

**Unknown / Requires Confirmation:** which FlutterFlow project this middleware was built for, and whether `1.0.0` was ever deployed.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` (default; `origin/HEAD`) | `8525b9f` | 2025-09-04 | Only branch. One commit: "first commit" |

No other local or remote branches were present at inspection. History does not show a later release, a `develop` branch, or a removed feature.

**Discrepancy:** the task-creation scan listed `sonar-project.properties` and `sonarqube_scan.bat` at the repository root. Neither file is in git at `8525b9f`. Provenance: **Unknown** — they may have been untracked files on the scan host.

## Objectives

Stated in `README.md` and `CHANGELOG.md` (**Documented**):

- Run an Express server that pulls Supabase rows into MySQL and pushes queued client writes back to Supabase.
- Give a FlutterFlow app a Dart client for read, write, sync, and file upload.
- Give an operator a web dashboard for stats, sync status, logs, users, and health.
- Isolate data by Supabase user and by store.
- Resolve sync conflicts, retry failures, and run periodic sync and cleanup.

What the tree actually contains (**Implemented** as source, not demonstrated running):

- Server, dashboard, and client source for those three pieces, plus Docker Compose for MySQL 8, Redis 7, the server, and an nginx dashboard.
- Sync bucket SQL transcribed into `server/src/config/syncConfig.js`. `sync_rules.yaml` is not loaded at runtime (no YAML parser is a dependency, and no code reads the file).
- A `sync_conflicts` table and a dashboard query for it. No code inserts a conflict or applies a resolution.
- Scheduled jobs in `server/src/server.js`: sync every 5 minutes, cleanup at 02:00, and a log line at midnight labelled "log rotation".

The server was not started in this investigation. Static reading shows startup and wiring defects recorded in `technical-documentation.md`. Current status is source-only.

## Scope

### In scope of `main`

1. Node.js middleware in `server/` (Express, Socket.IO, MySQL, Redis, Supabase client, multer, sharp).
2. React dashboard in `dashboard/` (Vite, TypeScript, Tailwind, Chart.js).
3. Dart client in `client/lib/` (HTTP, Socket.IO client, Supabase Flutter).
4. Sync selection SQL for the tables listed in `sync_rules.yaml`.
5. Docker Compose and two Dockerfiles.
6. Operator docs under `docs/` for FlutterFlow setup, custom actions, widgets, and adding the library to an existing app.
7. `README.md`, `CHANGELOG.md`, `NewKnowledgeBase.md`, `env.example`.

### Out of scope of this repository

- The FlutterFlow project itself (screens, generated app, Supabase project).
- Supabase table DDL, except a sample `execute_sync_query` function and `_health_check` table in the README.
- A device-local database. The client has no sqflite, Hive, or other offline store.
- Account administration for Flutter users. The dashboard user list is an aggregate of `sync_metadata`.
- CI, SonarQube config, tests, and a license file. See "Not in git" in `features.md`.

## System architecture

```text
FlutterFlow app
  └─ client/lib  (HTTP + Socket.IO, Supabase access token)
        │
        ▼
Express server  (server/src/server.js, port 3000)
  ├─ /api/auth, /api/sync, /api/data, /api/upload
  ├─ /dashboard/api  (operator JSON)
  ├─ /health
  ├─ Socket.IO rooms user_<supabase user id>
  │
  ├─ MySQL 8   local JSON rows, sync metadata, pending writes, logs, file metadata
  ├─ Redis     intended session store and sync_stats cache
  └─ Supabase  auth.getUser, auth.admin.getUserById,
               rpc execute_sync_query, table insert/update/delete

Operator browser
  └─ React dashboard (Vite dev port 3001, or nginx container port 3001→80,
     or Express static — three different host stories; see technical-documentation.md)
```

Provenance: **Implemented** as this source layout. The process was not run.

## Major components

| Component | Path | Role |
|---|---|---|
| HTTP and socket server | `server/src/server.js` | Routes, Helmet, CORS, rate limit, sessions, cron |
| Sync engine | `server/src/services/syncManager.js` | Pull buckets, store JSON rows, push `pending_changes`, stats, cleanup |
| Sync rules (executed) | `server/src/config/syncConfig.js` | Four buckets and their SQL |
| Sync rules (not executed) | `sync_rules.yaml` | Same buckets in a PowerSync-like YAML shape. Not parsed |
| API auth | `server/src/middleware/auth.js` | Supabase `getUser` on the bearer token |
| Dashboard auth | `server/src/middleware/dashboardAuth.js` | Shared username and `bcrypt.compare` |
| File upload | `server/src/services/fileUploadService.js`, `server/src/routes/upload.js` | Multer, sharp, local disk |
| Dashboard UI | `dashboard/src/` | Login, overview, sync status, logs, users, health |
| Flutter client | `client/lib/` | Actions, widgets, HTTP and socket client |
| Compose stack | `docker-compose.yml` | mysql, redis, sync_server, dashboard |

## Milestones

| Item | Evidence | Status |
|---|---|---|
| Single commit containing server, dashboard, client, docs, and Compose | `8525b9f` | **Implemented** in git. Not shown running |
| Changelog "1.0.0" initial release | `CHANGELOG.md` date `2024-01-XX` | **Documented**. Git date is 2025-09-04. No tag |
| Version 1.1.0: advanced conflicts, realtime subscriptions, dashboard analytics, mobile monitoring app, API versioning | `CHANGELOG.md` checkboxes, all unchecked | **Planned** in the changelog only |
| Version 1.2.0: multi-region, caching, compression, security, performance monitoring | Same | **Planned** |
| Version 2.0.0: rewrite, GraphQL, analytics, machine learning, enterprise features | Same | **Planned** |

`NewKnowledgeBase.md` restates several of those future items as lessons and opportunities. It is a narrative note, not a schedule.

## Known dependencies

Runtime, from manifests and Compose:

- Node.js 18 (Dockerfiles). README says Node.js 18+.
- MySQL 8.0, Redis 6+ (README) / Redis 7 (Compose image `redis:7-alpine`).
- A Supabase project with `execute_sync_query(text)` and the tables named in the sync SQL.
- Flutter SDK `>=3.10.0`, Dart `>=3.0.0 <4.0.0` for the client package.
- npm packages in `server/package.json` and `dashboard/package.json`. No `package-lock.json` is committed, so the Dockerfiles' `npm ci` has no lockfile to install from.

External systems: Supabase Auth and Postgres (via the Supabase client). No other SaaS, queue broker, or mail provider appears in the tree.

## Current project status

Source for a sync middleware and dashboard exists on `main` and has not moved since 2025-09-04.

Documentation inside the repo (`README.md`, `CHANGELOG.md`, `NewKnowledgeBase.md`) describes a finished 1.0.0 product: offline-first mobile cache, conflict resolution, Joi validation, tests, CI, and a working default dashboard login. The code does not implement several of those claims. The gaps are listed as discrepancies in the other four documents. They are not treated here as approved product changes.

**Unknown / Requires Confirmation:**

- Whether this commit was ever run, deployed, or pointed at a real Supabase project.
- Which FlutterFlow app owns the store, survey, promo, and task tables.
- Whether `sync_rules.yaml` was exported from PowerSync. The file uses `request.user_id()` and `bucket.*` parameter syntax. The repository never names PowerSync.
- Whether the Sonar files from the scan host were intentional local-only files.
- Whether the changelog roadmap is still wanted.