# Project plan — formulys_simpleflow_backend

Evidence date: 2026-10-14.

Source repository: `git@bitbucket.org:overdrive/formulys_simpleflow_backend.git` (clone used `https://jacooverdrive@bitbucket.org/overdrive/formulys_simpleflow_backend.git`).

Inspected revision: `master` at `c30ed2baddbfdd28467a803ba153a58ef344ec6a` (`c30ed2b`, 2024-06-05 16:14:00 +0200, maanie `<maanie@overdrive.co.za>`, "Setup basic project structure"). `origin/HEAD` points at `master`.

The scan-host path `~/projects/sonar_scan/repos/formulys_simpleflow_backend` was not on this machine. The tree below was read from a clone of that git revision. Secret values from the tracked `.env` file are not reproduced here.

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

No `silicon_ark/formulys_simpleflow_backend/` directory existed before this file. A search of Silicon Ark Markdown for the slug `formulys_simpleflow_backend` found no earlier mention. Other Silicon Ark docs describe a separate product family named Simpleflow (for example `intersect_lambda` and `simpleflowhub.app`). Whether this repository belongs to that product family is **Unknown / Requires Confirmation** — the only shared signal in this repo is the substring `simpleflow` in the Bitbucket slug.

## Product

There is no README, product brief, or API specification in the repository. The committed behaviour is an early Node.js HTTP and Socket.io server scaffold with a Mongoose `User` model and a MongoDB connection driven by `MONGO_URI`.

Provenance: **Implemented** in `package.json`, `server.js`, `models/User.js`, `socket_handlers/index.js`, and `.env`.

The repository and npm package name is **formulys_simpleflow_backend**. The words "formulys" and "simpleflow" appear only in that name (and in the lockfile name). Nothing in the source states what Formulys is, who uses it, or which problem the backend solves.

**Unknown / Requires Confirmation:** product owner, intended clients, relationship to other Simpleflow / Formulys repositories, and whether this revision was ever deployed.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `c30ed2b` | 2024-06-05 | Only branch. Two commits |

No other local or remote branches were present at inspection. No tags.

History, oldest first:

- `bb640f4` — 2024-05-28 11:33:56 +0000 — Abdurahmaan Ismail `<maanie@overdrive.co.za>` — "Initial commit". Adds Bitbucket's stock example `.gitignore` only.
- `c30ed2b` — 2024-06-05 16:14:00 +0200 — maanie `<maanie@overdrive.co.za>` — "Setup basic project structure". Adds `package.json`, `package-lock.json`, `server.js`, `models/User.js`, `socket_handlers/index.js`, and `.env`. Tip of `master`.

Nothing has been committed since 2024-06-05.

The onboarding issue (OVER-134, captured 2026-09-28) recorded the same tip: `c30ed2b`, 2024-06-05, "Setup basic project structure", branch `master`. This clone agrees on that commit.

**Discrepancy:** the task-creation scan listed `sonar-project.properties` and `sonarqube_scan.bat` at the repository root. Neither file is in any commit at `c30ed2b`. Provenance of those paths: **Unknown** — they may have been untracked files on the scan host.

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

- Run an Express HTTP server that listens on `process.env.PORT` or `3000`.
- Connect to MongoDB with Mongoose using `process.env.MONGO_URI`.
- Accept Socket.io connections and broadcast a `message` event to all clients.
- Model users with username, password, optional tenant reference, and a role enum.

Provenance: **Inferred** from `server.js`, `models/User.js`, and `package.json` scripts. There is no written milestone list.

## Scope

### In scope of `master` at `c30ed2b`

| Path | Role |
|---|---|
| `package.json` / `package-lock.json` | npm package `formulys_simpleflow_backend` `1.0.0`, dependencies and scripts |
| `server.js` | Express app, HTTP server, Socket.io, MongoDB connect, `GET /` |
| `models/User.js` | Mongoose `User` schema |
| `socket_handlers/index.js` | Socket.io connection handler module (not successfully wired — see technical documentation) |
| `.env` | Declares `MONGO_URI` (value committed; not copied into Silicon Ark) |
| `.gitignore` | Bitbucket example ignore patterns; does **not** list `.env` |

### Out of scope / not in this repository

- README, tests, lint config, Docker, CI pipeline, Sonar files, infrastructure-as-code.
- Auth routes, password hashing, session or JWT handling.
- A `Tenant` model (referenced by `User.tenantId`).
- Any use of the declared dependency `axios`.
- A file at `./socket` (required by `server.js`) or `index.js` (named as `package.json` `main`).

## System architecture (as committed)

```text
Client (unknown)
   |  HTTP          |  Socket.io
   v                v
Express (GET /)   socket.io on same HTTP server
   |
   +--> mongoose --> MongoDB (MONGO_URI)
```

**Implemented** intent in `server.js`. **As written, the process does not start:** `server.js` calls `require('./socket')` and `socketSetup(io)` before `io` exists, and there is no `socket.js` (or `socket/index.js`) in the tree. See `technical-documentation.md`.

## Major components

| Component | Evidence | Status |
|---|---|---|
| HTTP server | `http.createServer(app)`, `server.listen` | **Implemented** in source; blocked by load-order / missing module |
| Express JSON middleware | `app.use(express.json())` | **Implemented** |
| Health / smoke route | `GET /` → `'Hello World'` | **Implemented** |
| MongoDB connection | `mongoose.connect(process.env.MONGO_URI, ...)` | **Implemented** |
| User model | `models/User.js` | **Implemented** schema only; no routes use it |
| Socket broadcast | `message` event → `io.emit('message', msg)` | **Implemented** twice (inline in `server.js` and in `socket_handlers/index.js`) |
| Dev reload | `nodemon` via `npm run dev` | **Implemented** as script |

## Milestones and implementation plan

No milestones, backlog, or roadmap exist in the repository.

From git history only:

| When | Commit | What landed |
|---|---|---|
| 2024-05-28 | `bb640f4` | Ignore file |
| 2024-06-05 | `c30ed2b` | Basic Node/Express/Socket/Mongo scaffold |

**Unknown / Requires Confirmation:** next intended work (auth, tenancy, Formulys domain APIs, deployment).

## Known dependencies

### Runtime (from `package.json`)

- `express` `^4.19.2`
- `socket.io` `^4.7.5`
- `mongoose` `^8.4.1`
- `dotenv` `^16.4.5`
- `axios` `^1.7.2` (declared; **not imported** by any tracked source file)

### Development

- `nodemon` `^3.1.3`

### External systems

- MongoDB reachable at whatever URI is in `MONGO_URI`.
- Node.js (version **Unknown** — no engines field, no `.nvmrc`).

## Current project status

**Implemented** as an incomplete scaffold on `master` at `c30ed2b` (last change 2024-06-05). The User model suggests multi-tenant roles; no tenant or auth feature is wired. The entry file as committed cannot load successfully because of the `./socket` require and use of `io` before definition.

**Unknown / Requires Confirmation:**

1. Whether Formulys Simpleflow is an active product and this repo is still the intended backend.
2. Whether the Sonar files seen on the scan host were intentional and should be committed.
3. Whether committing `.env` with `MONGO_URI` was accidental (`.gitignore` does not exclude `.env`).
4. Whether this backend is related to the Simpleflow material documented under `intersect_lambda` and related Silicon Ark entries.

## Documentation set

| File | Purpose |
|---|---|
| `project-plan.md` | This file |
| `prd.md` | Product requirements recovered from the implementation |
| `features.md` | Feature inventory |
| `business-rules.md` | Rules enforceable from the schema and handlers |
| `technical-documentation.md` | Stack, layout, env, defects, operations |