# Technical documentation — formulys_simpleflow_backend

Evidence date: 2026-10-14.

Source: `git@bitbucket.org:overdrive/formulys_simpleflow_backend.git`, `master` at `c30ed2baddbfdd28467a803ba153a58ef344ec6a` (2024-06-05 16:14:00 +0200, author maanie `<maanie@overdrive.co.za>`, "Setup basic project structure"). Only branch: `master`. `origin/HEAD` points at `master`.

The scan-host path `~/projects/sonar_scan/repos/formulys_simpleflow_backend` was not on the machine that produced this document. Facts below come from a clone of that git revision. Secret values are not copied from `.env`.

## What this repository is

A Bitbucket Node.js repository containing an early Express + Socket.io + Mongoose scaffold. Remote observed on clone: `https://jacooverdrive@bitbucket.org/overdrive/formulys_simpleflow_backend.git`. Task metadata also records `git@bitbucket.org:overdrive/formulys_simpleflow_backend.git`.

| Commit | Date | Author | Subject |
|---|---|---|---|
| `bb640f4` | 2024-05-28 11:33:56 +0000 | Abdurahmaan Ismail `<maanie@overdrive.co.za>` | Initial commit (`.gitignore` only) |
| `c30ed2b` | 2024-06-05 16:14:00 +0200 | maanie `<maanie@overdrive.co.za>` | Setup basic project structure |

No tags. No other branches. No commits after 2024-06-05.

Tracked files at the tip (`git ls-files`):

```text
.env
.gitignore
models/User.js
package-lock.json
package.json
server.js
socket_handlers/index.js
```

## Architecture

Intended runtime shape from `server.js`:

```text
npm start / npm run dev
        |
        v
   server.js
        |
        +-- dotenv.config()
        +-- express() + express.json()
        +-- http.Server
        +-- socket.io(Server)
        +-- mongoose --> MongoDB (MONGO_URI)
        +-- GET /
        +-- Socket.io: connection / message / disconnect
```

**As committed, the process does not reach listen.** Order of statements in `server.js`:

1. `const socketSetup = require('./socket');` — module path does not exist (`socket_handlers/index.js` is the only handler module).
2. `socketSetup(io);` — `io` is not declared yet.
3. Later: create `app`, `server`, `io`, middleware, mongoose, routes, and a second `io.on('connection', ...)`.

Provenance of intended architecture: **Implemented** in the rest of the file. Provenance of runnable state: **Implemented** defect.

## Repository layout

| Path | What it is |
|---|---|
| `server.js` | Application entry used by npm scripts |
| `models/User.js` | Mongoose `User` model |
| `socket_handlers/index.js` | Exports `(io) => { io.on('connection', ...) }` |
| `package.json` | Dependencies and scripts |
| `package-lock.json` | Lockfile from the `c30ed2b` install |
| `.env` | `MONGO_URI=...` (tracked) |
| `.gitignore` | Bitbucket example ignore list |

Absent, including paths the task-creation scan listed:

| Path | Status |
|---|---|
| `sonar-project.properties` | Named by scan host. Not in git |
| `sonarqube_scan.bat` | Named by scan host. Not in git |
| `socket.js` / `socket/` | Required by `server.js`. Not in git |
| `index.js` | `package.json` `"main"`. Not in git |
| `README.md`, tests, Docker, CI | Not in git |
| `models/Tenant.js` | Suggested by schema ref. Not in git |

## Languages and frameworks

| Area | Evidence |
|---|---|
| Language | JavaScript (CommonJS `require` / `module.exports`) |
| Runtime | Node.js — version **Unknown** (no `engines`, no `.nvmrc`) |
| HTTP | `express` `^4.19.2` |
| Realtime | `socket.io` `^4.7.5` |
| ODM / DB | `mongoose` `^8.4.1` → MongoDB |
| Config | `dotenv` `^16.4.5` |
| HTTP client lib | `axios` `^1.7.2` — unused in tracked sources |
| Dev reload | `nodemon` `^3.1.3` |

License field: `ISC`. Description and author fields are empty strings.

## Application structure

### `server.js`

- Loads dotenv.
- Requires `./socket` into `socketSetup` and calls `socketSetup(io)` before creating `io` (**defect**).
- Creates Express app, HTTP server, Socket.io instance.
- Uses `express.json()`.
- Connects mongoose with options `{ useNewUrlParser: true, useUnifiedTopology: true }`.
- Logs Mongo connection error / open.
- Defines `GET /` → `res.send('Hello World')`.
- Registers inline Socket.io `connection` / `message` / `disconnect` handlers.
- Listens on `PORT` or `3000`.

### `socket_handlers/index.js`

Exports a function that registers the same Socket.io behaviour as the inline block in `server.js`. It is not required by any other tracked file under the name `socket_handlers` (only the broken `./socket` require exists).

### `models/User.js`

```text
username: String, required, unique
password: String, required
tenantId: ObjectId, ref 'Tenant'
role: String, enum [tenantUser, tenantAdmin, platformAdmin], required
```

No `timestamps`, no virtuals, no methods, no indexes beyond `unique` on username.

## APIs

| Method | Path | Auth | Body | Response |
|---|---|---|---|---|
| GET | `/` | None | None | Text `Hello World` |

No other HTTP routes. JSON middleware is registered but unused by any route.

### Socket.io events

| Direction | Event | Payload | Behaviour |
|---|---|---|---|
| Server → log | `connection` | — | Log `User connected` |
| Client → server | `message` | `msg` (untyped) | `io.emit('message', msg)` |
| Server → log | `disconnect` | — | Log `User disconnected` |

No Socket.io auth middleware, namespaces, or rooms.

## External integrations

| System | Direction | Auth | Notes |
|---|---|---|---|
| MongoDB | Outbound from app | URI in `MONGO_URI` | Only integration with a concrete config key |
| Socket.io clients | Bidirectional | None in code | Same process as HTTP |
| axios targets | — | — | Dependency only; no calls |

No AWS, email, Supabase, or payment integrations appear in this repository. Silicon Ark docs for other repos mention Simpleflow / `simpleflowhub.app`; this tree does not reference those hosts.

## Environment configuration

| Variable | Used in | Required for intended run | In git |
|---|---|---|---|
| `MONGO_URI` | `server.js` | Yes for a successful mongoose connect | Yes (`.env`) |
| `PORT` | `server.js` | No (defaults to 3000) | Not set in `.env` |

`.gitignore` does not exclude `.env`. **Implemented** risk: connection string lives in git history.

## Auth and security

| Topic | Finding | Provenance |
|---|---|---|
| HTTP auth | None | **Implemented** absence |
| Socket auth | None | **Implemented** absence |
| Password hashing | None | **Implemented** absence |
| Rate limiting | None | **Implemented** absence |
| Helmet / CORS config | None explicit | **Implemented** absence |
| Secrets management | `.env` committed | **Implemented** |

## Background workers / queues / storage

None. No job runner, queue client, or file/object storage code.

## Monitoring

No APM, metrics, structured logging library, or health endpoint beyond `GET /`. Mongo and socket events use `console.log` / `console.error`.

SonarQube: task-creation metadata listed `sonar-project.properties` and `sonarqube_scan.bat`. They are **not** in git at `c30ed2b`. Whether analysis exists outside git is **Unknown / Requires Confirmation**.

## Infrastructure and deployment

Nothing in the repository describes hosting, Docker, PM2, systemd, Bitbucket Pipelines, or cloud resources.

**Unknown / Requires Confirmation:** where (if anywhere) this service is deployed.

## Development and testing

| Command | Source | Notes |
|---|---|---|
| `npm start` | `package.json` | `node server.js` — fails as committed |
| `npm run dev` | `package.json` | `nodemon server.js` — same entry defect |
| Tests | — | No test script, no test files |

This inspection did not run `npm install` or start the server against a live MongoDB.

## Dependency notes

From `package.json` ranges (lockfile pins exact versions; representative directs):

- `express` ^4.19.2
- `socket.io` ^4.7.5
- `mongoose` ^8.4.1
- `dotenv` ^16.4.5
- `axios` ^1.7.2 (unused in source)
- `nodemon` ^3.1.3 (dev)

Mongoose 8 no longer requires `useNewUrlParser` / `useUnifiedTopology`; their presence is legacy options on a Mongoose 8 dependency range. Provenance of “legacy”: **Inferred** from the dependency major vs the options in `server.js`.

## Defects and inconsistencies (summary)

1. `require('./socket')` vs actual path `socket_handlers/index.js`.
2. `socketSetup(io)` before `const io = socketIo(server)`.
3. Duplicate socket handler definitions if both paths were wired.
4. `package.json` `"main": "index.js"` with no `index.js`.
5. `User.tenantId` refs missing `Tenant` model.
6. `axios` unused.
7. `.env` tracked; `.gitignore` does not list it.
8. Scan-host Sonar files not present in git.

## Related Silicon Ark context (not evidence from this repo)

Other Silicon Ark directories document Simpleflow email / Intersect Cloud behaviour (for example `intersect_lambda`). Those documents are **not** requirements for this repository unless a human confirms a product link. The only in-repo name link is the slug substring `simpleflow`.