# Project plan — stock_system

Evidence date: 2026-10-02.

Source: `git@bitbucket.org:overdrive/stock_system.git`, branch `main`, commit `02b62e87b9595ab3a8cfa8352809cc2173e92284` (2026-07-01, Joshua G-D, "Merged in josh_work (pull request #1)").

No `silicon_ark/stock_system/` directory existed before this set. The source repository already contains a large `docs/` tree (task logs, shop schema, sync contract, DMS, mailbox, scheduler, support). This plan summarises that material and the code. It does not replace those files.

History deeper than the tip commit was not fetched. Statements about "recent" work rely on dated files inside the tree (migrations, `docs/tasks/`, README "Recent Changes"), not on a full git log.

## Product identity

The Git slug is `stock_system`. The running product is not a stock-level or warehouse system.

| Name found | Where | What it refers to |
|---|---|---|
| stock_system | Git remote; local base path `annies_stock_system` in `app.baseURL` | Repository and one local URL path |
| Annie's Angels | `docs/tasks/TASK-015.md`, storefront copy | Public costume-hire catalogue and enquiry |
| Admin Overdrive / Admin Overdrive v2 | `composer.json` description, `README.md` title, `docs/index.md`, Sonar project key `overdrive_admin-overdrive-v2_…` | Shared CodeIgniter admin platform this app is built on |
| annies | Active database name in the tracked `.env` | Local MySQL schema name |
| SAWIS: Label | Hard-coded `$project` in `public/deploy.php` | Deploy script label. Does not match Annie's Angels |

**Documented** in `docs/db_docs/shop_products.md`: the shop schema is a catalogue mirror plus enquiry capture for costume hire. It does not model inventory, stock levels, variants, SKUs, reservations, or suppliers.

**Unknown / Requires Confirmation:** whether "stock_system" is only a folder name, or whether a future release is expected to track physical stock.

## Objectives

Recovered from repository docs and code. These are not a new product decision.

1. Give the public a costume catalogue (home, search, item, cart) that does not show hire prices. **Implemented** for visible products.
2. Capture a rental enquiry (name, email, start date, days) and email staff and the customer. **Implemented.**
3. Accept a one-way catalogue sync from an office SQL Server Express database, logged in this app. **Partly implemented:** this repo records sync runs and stores products. The .NET Sync Coordinator described in `docs/sync_docs/` is not in this tree.
4. Keep the Admin Overdrive staff tools that already live in the same codebase: login, roles, documents, mailbox, bulk email, WhatsApp support desk, scheduler, chat. **Implemented** as modules, subject to menu grants in the database.

## Scope

### In this repository

- CodeIgniter 4 PHP application (`app/`, `public/`, `spark`).
- MySQL schema via migrations under `app/Database/Migrations/`.
- Public storefront and staff admin UI.
- PHPUnit tests under `tests/`.
- Markdown under `docs/`.

### Referenced but not in this tree

- .NET Framework 4.8 Sync Coordinator (`SyncEngine.sln` is named in `docs/sync_docs/index.md`; no `.sln` or `.csproj` is present).
- WAHA (WhatsApp HTTP API), documented as an external process. `docs/support_env.md`.
- Office SQL Server Express and Microsoft Access `.mdb`, documented as the catalogue source.
- Google Drive image URLs, stored on product rows. No Drive client is in this repo.

### Out of scope for the current code

Staff product admin, image-publish pipeline, and wiring the coordinator's product upsert are listed as deferred in `docs/tasks/TASK-015.md` (Epics 2, 6, and 7). No later task file supersedes that list.

## Architecture

```text
Public browser
  → CodeIgniter storefront (/, /search, /item/{slug}, /cart, enquiry)
  → MySQL shop_* tables
  → SMTP enquiry mail

Staff browser
  → /login (session)
  → menu permission check
  → documents, mailbox, bulk email, support, scheduler, shop-sync, chat, users, settings

External Sync Coordinator (.NET, not in this repo)
  → reads Access / SQL Express (documented)
  → upserts shop_products (documented contract; writer not in this repo)
  → POST /api/shop-sync/log (implemented receiver)

WAHA
  → POST /support/webhook/waha
  → support ticket tables

IMAP
  → php spark mailbox:poll
  → mailbox ticket tables
```

Major components:

| Component | Location | Role |
|---|---|---|
| Storefront | `app/Controllers/Storefront/`, `app/Libraries/Shop/`, `app/Views/storefront/` | Public catalogue, cart, enquiry |
| Shop data | `app/Models/Shop/`, shop migrations | Products, images, orders, sync log |
| Auth and menus | `app/Filters/Authentication.php`, `Authorization.php`, `app/Controllers/Welcome.php`, `Users.php` | Session login, role, menu grant |
| Documents | `app/Controllers/Documents.php`, `Admin/Documents.php` | Upload, search, viewer assignment |
| Mailbox | `app/Controllers/Mailbox.php`, `app/Libraries/Mailbox*` | IMAP tickets |
| Bulk email | `app/Controllers/BulkEmail.php` | Campaigns, templates, tracking |
| Support desk | `app/Controllers/Support.php`, `SupportWebhook.php` | WhatsApp via WAHA |
| Scheduler | `app/Controllers/Scheduler.php`, `CronJobs.php`, `app/Libraries/SchedulerService.php` | Timed jobs |
| Chat / RAG | `app/Controllers/Chat.php`, `ChatGPT.php`, `RagStatus.php` | OpenAI-backed search and chat |

## Milestones visible in the tree

Dates are file dates and task-log dates, not a release calendar.

| When | What | Status in repo docs |
|---|---|---|
| 2023–2024 | Admin starter: users, settings, email queue, cron, login history, 2FA tables | Migrations exist. **Implemented** |
| 2025-01 / 2025-11 | Document management, OCR/RAG, viewer access, audit | Migrations and `docs/new/documents.md`. **Implemented** |
| 2026-04 | Password reset, TOTP columns | Migrations. **Implemented** |
| 2026-05 | Bulk email, mailbox tickets, document year/tabs | Migrations and port docs. **Implemented** |
| 2026-06-04 | Support desk (WAHA). `docs/tasks/TASK-013.md` | Marked completed in `docs/index.md` |
| 2026-06-07 | Scheduler module. `docs/tasks/TASK-014.md` | Marked completed in `docs/index.md` |
| 2026-06-08 | Annie's Angels public storefront phase 1 and shop-sync log. `docs/tasks/TASK-015.md` | Marked completed. Later epics deferred |
| 2026-06-17 | `sqlexpress_product_id` on `shop_products` | Migration. **Implemented** |
| 2026-07-01 | Tip commit merges `josh_work` | Git metadata only. Diff of that PR was not re-read beyond the tip tree |

`docs/index.md` lists no active task. Open blocker text there is only that WAHA must be reachable for live WhatsApp.

## Implementation plan still open inside the repo

From `docs/tasks/TASK-015.md` next steps, unchanged by any newer task file:

1. Wire the .NET Sync Coordinator to product upsert and to `POST /api/shop-sync/log`.
2. Staff admin for images, visibility, and the enquiry log.
3. Image publish pipeline. Partial support exists: `image_url_1/2/3` columns.

`docs/shop_sync_contract.md` also says new office products should default `is_visible = 0` until staff publish them. The migration default is `1`. See business rules. Staff publish UI is the deferred admin above.

## Dependencies

Runtime and libraries are listed in `technical-documentation.md`. External systems:

- MySQL (active local database name `annies` in tracked `.env`).
- SMTP (`email.*` keys).
- Optional OpenAI (`OPENAI_API_KEY`, package `orhanerday/open-ai`, `neuron-core/neuron-ai`).
- Optional Tesseract and Poppler for OCR (`README.md`).
- WAHA HTTP API.
- Sync Coordinator and SQL Server Express (documented, not in this repo).
- cron-job.org is named in `docs/scheduler.md` as an external ping option, not as a committed integration.

## Current status

**Implemented and present on `main`:** public storefront, enquiry checkout, shop tables, sync-log API and admin page, admin platform modules listed above, PHPUnit coverage for several of those modules.

**Not established:**

- Production URL, hosting, and who operates Annie's Angels.
- Whether the .NET coordinator has been deployed anywhere.
- Whether menu seeders have been applied on the `annies` database.
- A pipeline file. `docs/overview.md` says Bitbucket Pipelines exist. No `bitbucket-pipelines.yml` is in the tree.

## Discrepancies requiring human review

1. Repository name and deploy script say stock / SAWIS Label. Product copy and shop docs say Annie's Angels costume hire, and explicitly exclude stock levels.
2. Sonar project key and `docs/index.md` say Admin Overdrive v2. `app.baseURL` path is `annies_stock_system`. Tracked `WAHA_WEBHOOK_PUBLIC_URL` path is `admin_overdrive_v2`.
3. `docs/shop_sync_contract.md` wants new products hidden (`is_visible = 0`). Migration `2026-06-08-100000_CreateShopTables.php` defaults `is_visible` to `1`.
4. `docs/overview.md` claims Bitbucket Pipelines and PHP `^8.0`. No pipeline file is present. `composer.json` requires PHP `^8.2`. `README.md` says PHP 8.3.
5. `Routes.php` registers products, orders, labels, fault finder, company vendor numbers, `getXMLData`, a `store-api` resource, and an `organisations` resource. No matching controller classes were found.
6. `UserRole` seeder checks for a role named `Developer` and, when missing, inserts `System Admin` instead. Several menu seeders grant a `Developer` role that this seeder does not insert under that name.
7. Tracked `.env` and `public/deploy.php` contain live-looking secrets. `public/info.php` calls `phpinfo()`. `Slack.php` embeds a Slack webhook. Values are not copied into Silicon Ark. See technical documentation.