# Project plan — datafy_powersync

Evidence date: 2026-10-17.

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

Inspected revision: `main` at `0aa51f9` (2025-02-25, Jaco Brits, "added abolute paths"). Full SHA `0aa51f98ff6068260c0a96ccac1d1f47310e769e`.

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

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

There was no `silicon_ark/datafy_powersync/` directory before this document set. Silicon Ark already documents Datafy clients and databases that use the same table names (`flutter_app`, `flutter_webportal`, `flutterflow_sync`, `datafy-supabase-functions`, `datafy_web`). None of those sets names this repository. Whether this repo is the server those products sync through is **Unknown / Requires Confirmation**. See the discrepancy in `prd.md`.

## Product

The repository is a self-hosted [PowerSync](https://docs.powersync.com/) deployment kit. It is Docker Compose, YAML service config, and two upstream demo clients. It does not contain the Datafy mobile or web application.

Provenance: **Implemented** file tree. `README.md` is an empty file (0 bytes), so the product purpose is not **Documented** in the source repo.

What the current root stack declares:

- A PowerSync service image `journeyapps/powersync-service:latest`, started as one process (`start -r unified`: API and replication in the same container).
- MongoDB 7 as the sync-bucket store, database name `powersync_datafy`, replica set `rs0`.
- A Postgres source reached through environment variables, not a Postgres container in the root compose file.
- Sync rules over four tables: `task`, `store`, `app_user`, `store_user_link`.
- Client auth with `supabase: true` and JWT audiences `powersync-dev` and `powersync`.

`v2/` is a second stack. Its source database is an Amazon RDS Postgres host in `eu-west-1`. Its bucket store is a local Postgres, not MongoDB. Those files also contain a database password. The password is omitted from Silicon Ark. See `technical-documentation.md`.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` (default; `origin/HEAD`) | `0aa51f9` | 2025-02-25 | Only branch. 26 commits, 2025-02-22 through 2025-02-25 |

No tags. No other local or remote branches.

Every commit is authored by Jaco Brits `<jaco@netstart.co.za>`. Messages are short ("update", "update config", "version 2"). Two were checked file-by-file:

- `037261a` ("use postgress as the store") edits `v2/config.yaml` and `v2/docker-compose.yaml`. At HEAD, `v2/` stores buckets in Postgres and comments out Mongo.
- `0aa51f9` ("added abolute paths") edits only `v2/docker-compose.yaml`. That file mounts `/home/ubuntu/datafy_powersync/v2/...`.

No commit after 2025-02-25 was on `origin/main` at inspection. Whether anyone ran the stack after that date is **Unknown / Requires Confirmation**.

**Discrepancy:** the task-creation scan on 2026-09-28 listed `sonar-project.properties` and `sonarqube_scan.bat` at the repository root. Neither path is in git at `0aa51f9`. Provenance: **Unknown** — they may have been untracked files on the scan host.

## Scope in the repository

Tracked layout:

| Path | What it is |
|---|---|
| `README.md` | Empty file. |
| `.gitignore` | Stock Bitbucket example (Node, Java, Python bytecode, logs, Maven, JetBrains, macOS, Windows, executables, large video and TIFF). It does not ignore `.env`. |
| `example.env` | Postgres and `PS_PORT` placeholders for the root stack. |
| `docker-compose.yaml` | Current root stack: include `ps-mongo.yaml`, PowerSync service, env templates. |
| `ps-mongo.yaml` | MongoDB 7 replica set and a one-shot `mongo-rs-init`. |
| `config/powersync.yaml` | Service config using `!env` for Postgres, Mongo, and port. Sync rules loaded from `sync_rules.yaml`. |
| `config/sync_rules.yaml` | Bucket SQL for `task`, `store`, `app_user`, `store_user_link`. |
| `config.yaml` | Older single-file config: inline URI `postgresql://postgres:postgres@postgres:5432/postgres`, inline sync rules, Mongo `powersync_datafy`, port 8080. Not referenced by `docker-compose.yaml`. |
| `services/powersync.yaml` | Reusable PowerSync service (healthcheck, memory cap, `POWERSYNC_CONFIG_PATH`). Used by the demos, not by the root compose file. |
| `services/mongo.yaml` | MongoDB 7 with a healthcheck and a retrying replica-set init. Used by the demos. |
| `services/postgres.yaml` | `postgres:latest` with `wal_level=logical`. Used by the Node demo. |
| `docker-compose_old.yaml` | Earlier stack. PowerSync volume `./config.yml` (that file is not in git). Postgres service commented out. |
| `old.txt` | Scratch paste: a compose snippet with `/home/ubuntu/powersync/...`, a different YAML shape (`database` / `http` / `auth`), and the same sync SQL. Not referenced by a compose `include`. |
| `v2/` | Second stack. Absolute Ubuntu paths, RDS source URI, local Postgres bucket store. Four YAML copies of the service config. |
| `Mackup.yml` | Docker Compose file, not a Mackup backup manifest. Supabase-network demo plus a demo client. |
| `demos/nodejs/` | Upstream PowerSync Node/React todo demo, wired to `services/`. |
| `demos/supabase/` | Upstream Supabase local-dev notes, plus a copy of the Datafy sync rules. |

Out of scope of this repository, on the evidence: table DDL for `task`, `store`, `app_user`, or `store_user_link`; a Postgres publication for those tables; a Supabase `config.toml`; tests; a CI pipeline; a pinned image digest; a running-host inventory.

## System architecture

```text
Root stack (docker-compose.yaml + ps-mongo.yaml)
  powersync   journeyapps/powersync-service:latest
              command: start -r unified
              network_mode: bridge
              env PS_PG_URI, PS_MONGO_URI, PS_PORT
              mounts ./powersync.yaml (file absent) and ./config
        |
        +-- MongoDB mongo:7.0   replica set rs0   db powersync_datafy   port 27017
        |
        +-- Postgres source     host/user/db from example.env
                                this compose file does not start Postgres

v2 stack (v2/docker-compose.yaml)
  powersync   same image, port 8080
              mounts /home/ubuntu/datafy_powersync/v2/...
        |
        +-- postgres:latest     published 5431 -> 5432, wal_level=logical
        |                       bucket storage URI points here
        |
        +-- RDS Postgres        eu-west-1, user supabase_admin, db postgres
                                replication source (password is in git; not copied here)

Demos
  demos/nodejs     extends services/* , adds pg-db + demo-backend + demo-client
  demos/supabase   extends services/* , optional external Docker network
  Mackup.yml       same idea as the Supabase demo, plus demo-client on port 4170
```

Provenance: **Implemented** in the compose and YAML files. Nothing in git records that any of these stacks is the one a phone or browser uses today.

## Major components

| Component | Role | Where |
|---|---|---|
| PowerSync unified service | Replicate Postgres, serve the sync API | Root compose, `services/powersync.yaml`, `v2/docker-compose.yaml` |
| Mongo replica set | Bucket storage for the root stack and the demos | `ps-mongo.yaml`, `services/mongo.yaml` |
| Local Postgres | Logical-replication source for the Node demo; bucket storage in `v2/` | `services/postgres.yaml`, `v2/docker-compose.yaml` |
| RDS Postgres | Replication source named only in `v2/` | Four YAML files under `v2/` |
| Sync rules | Which rows a client receives | `config/sync_rules.yaml` and copies |
| Node todo demo | React client plus a backend cloned from GitHub at image build | `demos/nodejs/` |
| Supabase demo | Notes and compose for a local Supabase project that is not in this repo | `demos/supabase/`, `Mackup.yml` |

## What was implemented (there is no written roadmap)

There is no milestone document, issue list, or TODO tracker. `config.yaml` and the `v2/` files contain the comment `TODO use specific sync rules here`, and the sync SQL under that comment is the Datafy four-table rules, not a placeholder `SELECT`.

History, oldest first, from `git log` subjects only except where a diff was read:

- 2025-02-22 — Initial commit, then "update powersync", "update docker", "add extra mountings".
- 2025-02-24 — "update config".
- 2025-02-25 — Docker, Mongo parameters, a bridge network, a Supabase connection test (commit subject "testing supabase conection"), naming, a network id, `v2/` ("version 2"), "remove services", Postgres as the bucket store (`037261a`), then config edits, and absolute paths in `v2/docker-compose.yaml` (`0aa51f9`).

## Dependencies

| Dependency | How it appears | Pin |
|---|---|---|
| Docker Compose include | Comment requires Compose > 2.20.3 | Comment in `docker-compose.yaml`, `Mackup.yml`, both demo compose files |
| `journeyapps/powersync-service` | Service image | Tag `latest` only. Healthcheck comment in `services/powersync.yaml` says the liveness probe needs `0.5.8` or later |
| `mongo` | Bucket store | `7.0` |
| `postgres` | Demo source and v2 bucket store | Tag `latest` |
| `node` | Demo Dockerfiles | `node:20`. Demo app `.nvmrc` is `v20.9.0` |
| pnpm | Demo image build | Dockerfile installs `pnpm@9` for the Node demo. Supabase demo dockerfile installs `pnpm` with no version |
| `@powersync/web` `^1.12.1`, `@powersync/react` `^1.5.1` | Demo client | `demos/nodejs/demo-app/package.json` version `0.2.3`, package name `@powersync/react-custom-auth-todolist` |
| GitHub `powersync-ja/powersync-nodejs-backend-todolist-demo` | Built as `demo-backend` from a remote Git context | `demos/nodejs/ps-nodejs-demo.yaml`. No commit pin |
| GitHub `powersync-ja/powersync-js` | Cloned inside `demos/supabase/demo-client.dockerfile` | `git clone` of default branch, no pin |
| Supabase CLI / local stack | README instructions | Not vendored. Network name `supabase_network_powersync_datafy` |

## Current status

The git default branch is the 2025-02-25 tree above. Several compose files disagree with each other (which config is mounted, which env var fills the Postgres URI, Mongo versus Postgres bucket storage, relative versus `/home/ubuntu/...` paths). Those conflicts are written up in `technical-documentation.md` and `business-rules.md`. They are not resolved by a later commit.

`README.md` does not say how to start the root stack.

## Human confirmation

- Is any compose file in this repo still deployed, and on which host (`/home/ubuntu/datafy_powersync` or somewhere else)?
- Is the live Datafy app using this self-hosted service, or the JourneyApps cloud project named in the `flutter_app` Silicon Ark set (`https://67c1c2c9586c8d282a0669f2.powersync.journeyapps.com`)?
- Has the RDS password committed under `v2/` been rotated? Silicon Ark does not repeat it.
- Where do `task`, `store`, `app_user`, and `store_user_link` live, and is there a PowerSync publication for them? This repo does not create those objects.
- What happened to `sonar-project.properties` and `sonarqube_scan.bat` from the 2026-09-28 scan? They are not in git.