# Project plan — dbdaigram (DB Diagram)

Evidence date: 2026-10-17.

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

Inspected revision: `main` at `c6e0389` (2026-07-07, jacobrits1, "docs: add Dokploy production deployment details"). The scan-host path `~/projects/sonar_scan/repos/dbdaigram` was not on this machine. The tree below was read from a clone of that git revision.

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

## Product

The README titles the product **DB Diagram — Internal** and describes it as a self-hosted replacement for dbdiagram.io, for internal team use. The browser title and login heading are **DB Diagram**. The repository slug is `dbdaigram`.

The MySQL database name in `api/config.php`, Docker Compose, and the README is also **`dbdaigram`**. The local WAMP URL in the README is `http://localhost/dbdaigram/`. The Dokploy project name in the README is `dbdaigram`. The production hostname in the README is `dbdesign.appnotify.co.za`. The README names the Bitbucket repository as `overdrive/dbdaigram`.

Provenance: **Documented** in `README.md` and **Implemented** in `api/config.php`, `docker-compose.yml`, and `index.html`.

There is no separate product requirements document, roadmap, or ticket list in the repository.

## Related repository

Silicon Ark already has a `db_design/` set (issue OVER-88) for `git@bitbucket.org:overdrive/db_design.git`. That write-up lists commits `334e2aa` and `c6e0389`, which are the only two commits in **this** repository, and a later merge `992fbe3` ("merge: integrate app into overdrive/db_design repo").

This inspection did not re-read the `db_design` git tree. Whether the two repositories still hold the same application, and which one Dokploy builds, is **Unknown / Requires Confirmation**.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `main` (default; `origin/HEAD`) | `c6e0389` | 2026-07-07 | Only branch. Two commits. |

History, oldest first:

| Commit | Date | Author | Message | What landed |
|---|---|---|---|---|
| `334e2aa` | 2026-07-07 11:36 +0200 | jacobrits1 `<jaco@netstart.co.za>` | feat: add Docker deployment for Dokploy | The whole application, Dockerfile, Compose, and the first README (24 files, 3139 insertions). Co-authored by Cursor |
| `c6e0389` | 2026-07-07 11:46 +0200 | jacobrits1 `<jaco@netstart.co.za>` | docs: add Dokploy production deployment details | Production URL, Dokploy project name, DNS note, default-login reminder in `README.md`. Co-authored by Cursor |

The first commit message says "add Docker deployment". The diff is the entire product, not a Docker layer on an older app. No other local or remote branches were present. Nothing in history is a removed product feature.

The task-creation scan (2026-09-28) listed `api`, `assets`, `docker-compose.yml`, `Dockerfile`, `index.html`, and `README.md`. Those paths exist. Git also tracks `.htaccess`, `.dockerignore`, `.gitignore`, and the files under `api/` and `assets/`. The scan did not name a `sonar-project.properties` file, and none is in git at `c6e0389`.

## Objectives

Taken from `README.md` (**Documented**) and matched to code (**Implemented**):

- Let a signed-in person design a database schema in DBML and see a live diagram.
- Drag tables, draw relationships from the canvas, and keep positions with the diagram.
- Import a MySQL dump into DBML and export MySQL DDL, DBML source, or a PNG.
- Give each person a login, private diagrams, and a way to share a diagram with every signed-in user.
- Keep the last 50 explicit saves as restorable versions.
- Run on local WAMP (Apache + MySQL) or as a Dokploy Docker Compose stack (PHP 8.2 + Apache + MySQL 8).

No written objective beyond the README was found.

## Scope

### In scope of `main`

1. A single-page browser application: login, DBML editor, diagram canvas, diagram list, version history, SQL import, export, user management.
2. Two PHP JSON endpoints: `api/auth.php` and `api/diagrams.php`.
3. MySQL schema created on first connection if the `users` table is missing, including a seeded admin account.
4. Docker image (`php:8.2-apache`) and Compose file (app + MySQL 8.0).
5. README instructions for local WAMP, LAN exposure, backup, and Dokploy.

### Out of scope of the committed tree

- Automated tests, a CI pipeline file, Sonar configuration, Composer, npm, and a front-end build step.
- Email, password reset by the user, SSO, or an identity provider.
- Databases other than MySQL as an export/import target. The parser accepts a `Project` block `database_type`, and the canvas does not use it.
- A junction-table generator for many-to-many refs. Export writes a SQL comment instead.
- Dokploy domain, TLS, and auto-deploy settings. The README describes them. They are not files in this repository.

## Architecture

```text
Browser (index.html + assets/js)
    |  same-origin JSON, session cookie DBDAIGRAM_SESS
    v
Apache + PHP 8.2
    api/auth.php        login, session, users
    api/diagrams.php    diagrams and versions
    api/db.php          connect, create database, create tables, seed admin
    v
MySQL 8 (Docker) or local WAMP MySQL
    database name: dbdaigram
    tables: users, diagrams, diagram_versions
```

Parsing, diagram drawing, SQL import, and SQL export run in the browser. The server stores accounts, diagram text, layout JSON, and version rows. CodeMirror is vendored under `assets/vendor/`. The README states the app does not need internet access once it is hosted.

Provenance: **Implemented**, with the "no internet" sentence **Documented** in `README.md`.

## Major components

| Component | Path | Role |
|---|---|---|
| Page shell | `index.html` | Login view and editor view |
| App controller | `assets/js/app.js` | Auth, save, share, import/export, modals |
| DBML parser | `assets/js/dbml-parser.js` | DBML to an in-memory model |
| Canvas | `assets/js/canvas.js` | SVG diagram, drag, zoom, PNG |
| Editor | `assets/js/editor.js` | CodeMirror DBML mode |
| SQL export | `assets/js/sql-export.js` | Model to MySQL DDL |
| SQL import | `assets/js/sql-import.js` | MySQL DDL to DBML text |
| API client | `assets/js/api.js` | `fetch` wrapper |
| Auth API | `api/auth.php` | Session and users |
| Diagram API | `api/diagrams.php` | CRUD, share, versions |
| Schema bootstrap | `api/db.php` | Create database, tables, admin row |
| Config | `api/config.php` | DB settings, session, JSON helpers |
| Image | `Dockerfile` | PHP 8.2 Apache |
| Stack | `docker-compose.yml` | `app` + `mysql` |

## Milestones

There is no milestone list in the repository. The two commits above are the whole delivery history: one morning (2026-07-07), from an empty history to the application plus Dokploy notes.

**Unknown / Requires Confirmation:** whether later deploys happened after `c6e0389`, and whether they came from this repository or from `overdrive/db_design`. Git on this `main` has no newer commit.

## Dependencies

Runtime, from the Dockerfile, Compose file, and PHP `require` graph:

- PHP 8.2 with `pdo`, `pdo_mysql`, and `intl`. `intl` is installed in the image. No PHP file in the repository calls an `intl` function.
- Apache with `rewrite` and `headers` enabled. `.htaccess` turns rewrite on and adds a rule that does not map URLs to a front controller.
- MySQL. Compose pins image `mysql:8.0`. The README backup example uses a WAMP path under `mysql9.1.0`.
- Browser APIs used by the client: `fetch`, `localStorage`, SVG, Canvas `toBlob`, pointer events.

No `composer.json`, `package.json`, or lockfile is in the tree. CodeMirror ships as four minified files. The exact CodeMirror release is **Unknown** — the filenames do not include a version, and the minified banner that was inspected does not either.

## Current project status

**Implemented** and committed on `main` as of 2026-07-07: the editor, canvas, accounts, diagram storage, versions, import, export, and the Docker stack.

**Documented** deployment target: Dokploy project `dbdaigram`, URL `https://dbdesign.appnotify.co.za/`, Bitbucket repo `overdrive/dbdaigram`, DNS A record to `102.37.22.152`, push to `main` auto-deploys. This inspection did not open that URL or Dokploy. Whether that deployment is still current, and whether it tracks this repository or `overdrive/db_design`, is **Unknown / Requires Confirmation**.

Silicon Ark had no `dbdaigram/` directory before this onboarding.

## Known gaps (evidence, not a backlog)

- No test suite and no pipeline definition in the repository.
- Schema changes after the first boot are not applied: `bootstrap_schema` returns as soon as `users` exists.
- Admin rights are copied into the session at login and are not re-read from `users` on later API checks.
- Shared diagrams are editable by every signed-in user. The README states this explicitly.

## Human confirmation

- Which repository Dokploy builds: `overdrive/dbdaigram` at `c6e0389`, or `overdrive/db_design` after the merge described in Silicon Ark `db_design/`.
- Whether `https://dbdesign.appnotify.co.za/` still serves this stack, and whether the seeded administrator password was changed after first login.
- Whether the database name spelling `dbdaigram` is intentional.
- Whether the WAMP `mysql9.1.0` path in the README is the machine that hosts the local copy.