# Project plan — quickbooks_integration

Evidence date: 2026-10-05.

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

Inspected revision: `master` at `4ff6e81` (2020-04-30, message: "API redirects, Improved session handling for invoices"). The scan-host path `~/projects/sonar_scan/repos/quickbooks_integration` was not on this machine. The tree was read from that git revision. Credential values that appear in source are omitted.

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

Prior Silicon Ark set: none. Source documents that were incorporated: `README.md`, `README.txt`.

## Product

A PHP application that posts invoices into QuickBooks for Silicon Overdrive internal systems. The tree contains **two generations** of integration:

1. **QuickBooks Desktop (QBFS) via Intuit Web Connector.** ConsoliBYTE / Keith Palmer PHP DevKit (`QuickBooks.php` and a second copy under `AddClientService/`). SOAP endpoints `qbwc.php`, `qbwcEIT.php`, `qbwcTS.php` pull queued work from MySQL `quickbook_webservice` and send qbXML `InvoiceAdd` / `InvoiceQuery` (and in `AddClientService`, `CustomerAdd`).
2. **QuickBooks Online via Intuit REST v3.** Composer package `quickbooks/v3-php-sdk` 5.3.5, OAuth2 in `auth.php`, invoice POST in `invoice.php` / `index.php`. Documented in `README.md` as March 2020, Intuit app name **eit**, host `qb.overdrive.co.za`.

Callers named in code: Quotes (`quoteslive`), EIT billing (`eitlivedb`), Timesheet (`tmpQBImport` / `strApplication = 'TS'`).

Provenance: **Documented** (`README.md`, `README.txt`) and **Implemented**.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `4ff6e81` | 2020-04-30 | Only remote branch observed |

A shallow clone of `master` showed this single tip. Whether earlier history exists on Bitbucket but was not fetched is **Unknown**. Inline comments date Desktop work from at least 2014 (pj) through 2018 (mysqli / Hetzner credential reset comments). Those comments are older than the inspected commit message.

**Discrepancy with the 2026-09-28 onboarding scan:** the scan last-commit record matches `4ff6e81`. The scan listed a truncated root; the git tree also contains `vendor/`, `AddClientService/` (full ConsoliBYTE kit plus Maven POM), `WebConnector/`, `XMLOutput/`, and committed logs.

## Objectives (inferred from implementation and README, not from a written plan)

- Queue invoices from Quotes, EIT month-end / ad-hoc billing, and Timesheet imports, then let QuickBooks Desktop Web Connector apply them.
- After Desktop invoice add, write the QuickBooks invoice number back onto the Quotes row (`strStatus = '4. Invoiced'`). Query unpaid queued invoices and, when QuickBooks reports `IsPaid`, set Quotes to `5. Credited` is **not** what the paid path does — paid sets `5. Paid`.
- Optionally add placeholder customers into Desktop from `customer_table`.
- Authenticate to QuickBooks Online and create a ZAR sales invoice for a customer and item list (2020 Online path).

## Scope

### In scope of `master`

- SOAP Web Connector servers for Quotes, EIT, and Timesheet invoice add + invoice query.
- HTTP enqueue scripts `handler.php`, `handlerEIT.php`, `handlerTS.php`.
- Hourly queue-status reset `cron.hourly.php`.
- Credit/delete path `credited.php` (Quotes).
- Customer-add Web Connector under `AddClientService/`.
- QWC XML application definitions pointing at `https://qb.overdrive.co.za/...`.
- Online OAuth2 + invoice create (`auth.php`, `invoice.php`, `index.php`, `.htaccess` rewrites).
- ConsoliBYTE framework files, Intuit SDK under `vendor/`, example docs, XML dumps, PHP error logs.

### Out of scope of this repository (callers)

- The Quotes UI that hits `handler.php` (`http://quote/quote.php` in comments).
- The EIT billing UI that calls `handlerEIT.php?Action=Month End|Ad Hoc`.
- The Timesheet UI that fills `tmpQBImport`.
- QuickBooks company files, Web Connector installer, SSL certificates.

Provenance: **Inferred** from URLs, SQL catalogs, and comments.

## System architecture (as implemented)

```text
Quotes / EIT / Timesheet (external PHP apps)
        | HTTP GET (handler*.php)
        v
MySQL quickbook_webservice  -- invoice_table + ConsoliBYTE queue tables
        ^
        | SOAP (qbwc*.php)
QuickBooks Desktop Web Connector on a workstation with QBFS
        v
QuickBooks Desktop company file

--- parallel 2020 path ---

Caller (EIT or similar) --> GET /auth/  --> OAuth2 (Intuit) --> session token
                         --> GET /invoice/ --> QBO sandbox REST invoice
```

Timezone in `config.php.bak`: `Africa/Johannesburg`. `config.old.php` uses `Europe/Minsk`. Live `config.php` is gitignored.

## Major components

| Component | Role |
|---|---|
| `qbwc.php` + `functions.php` + `quote.connection.php` | Quotes Desktop invoice SOAP |
| `qbwcEIT.php` + `functionsEIT.php` + `eit.connection.php` | EIT Desktop invoice SOAP |
| `qbwcTS.php` + `functionsTS.php` + `ts.connection.php` | Timesheet Desktop invoice SOAP |
| `handler.php` / `handlerEIT.php` / `handlerTS.php` | Enqueue into `invoice_table` + `quickbooks_queue` |
| `AddClientService/qbwc*.php` | CustomerAdd SOAP |
| `auth.php` / `invoice.php` | QBO OAuth2 and invoice POST |
| `QuickBooks.php` | ConsoliBYTE DevKit |
| `vendor/quickbooks/v3-php-sdk` | Official QBO PHP SDK 5.3.5 |
| `*.qwc` | Web Connector application files |

## Implementation plan

No milestone plan, issue tracker, or CI pipeline is in the repository. **Unknown / Requires Confirmation** whether Desktop, Online, or both are still production.

## Known dependencies

- PHP with mysqli (and leftover `mysql_*` calls on some EIT response paths).
- PHP >= 5.6 for the v3 SDK (`composer.lock`).
- MySQL: `quickbook_webservice` (Hetzner `sql27.jnb1.host-h.net` in live connection strings; localhost variants in backups). `quoteslive` on `sql24.jnb1.host-h.net`. `eitlivedb` on `sql24.jnb1.host-h.net`.
- Intuit QuickBooks Desktop + Web Connector 2.x (`README.txt`).
- Intuit QuickBooks Online sandbox API (`sandbox-quickbooks.api.intuit.com`).
- Apache `mod_rewrite` and CORS headers in `.htaccess`.

## Current project status

**Implemented** as of 2020-04-30. No later commit on the inspected `master`. Whether the service at `qb.overdrive.co.za` still runs this tree is **Unknown / Requires Confirmation**.