# Project plan — wca_dms (Admin Overdrive)

Evidence date: 2026-09-29.

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

Inspected revision: `main` at `9f51c26` (2025-09-01, "sonar-project.properties edited online with Bitbucket").

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

## Product

The repository is named **wca_dms**. The application brand in views, mail, and `composer.json` is **Admin Overdrive**. The committed environment template sets the MySQL database name to `wca_dms`. `README.md` titles the project "WCA DMS (Admin Overdrive)".

What the letters WCA expand to is **Unknown / Requires Confirmation**. No expansion was found in code or in the documents that exist in the tree.

`app/Views/edioverdrive/readme.txt` says "Put all EDI Overdrive views in here". Implemented integration code talks to Pick n Pay EDI (SOAP) and Shoprite (REST) and writes order XML under `writable`. Views and routes also refer to companies, products, stores, orders, invoices, and a fault finder. Controllers and models for those domain screens are not in this tree. See [Current project status](#current-project-status).

Provenance: **Documented** in `README.md`, `composer.json`, and `env`. **Implemented** branding in views and mail. Domain EDI behaviour is **Implemented** only in `app/Controllers/Rest.php` and `app/Controllers/Soap.php`, and those methods have no caller in this tree.

External links in `README.md`, not verified from this repository:

- Jira board: `https://siliconsoftware.atlassian.net/jira/software/projects/SI/boards/12`
- Confluence space: `https://siliconsoftware.atlassian.net/wiki/spaces/AO/overview`

## Branch reality

Default branch is `main`. `origin/HEAD` points at `main`. No other remote branches were present at inspection.

| Commit | Date | Subject |
|---|---|---|
| `57b2fe8` | 2025-09-01 | Initial commit |
| `4d65114` | 2025-09-01 | Core checkout |
| `86fad8c` | 2025-09-01 | update to bootable version |
| `4252832` | 2025-09-01 | Cleanup dashboard |
| `9f51c26` | 2025-09-01 | sonar-project.properties edited online with Bitbucket |

Five commits, all on the same day. There is no longer history in this clone. Whether this repository was copied from a larger Admin Overdrive codebase is **Inferred** from the commit subject "Core checkout", leftover EDI views, and routes that name controllers that are not in the tree. That origin is **Unknown / Requires Confirmation**.

## Scope in the repository

In scope of what is present on `main`:

- A CodeIgniter 4 application (`codeigniter4/framework` `^4.6`) branded Admin Overdrive.
- Session login, email two-factor codes, password reset, IP block list, and login history.
- Role and menu permissions (seeded roles: Developer, Admin, Company Admin, Company User).
- User administration screens and system-settings screens (cron, email templates and logs, general settings, holidays, login history, blocked list).
- A reports screen whose tabs call endpoints that are not defined on `Reports`.
- EDI pull/confirm helpers for Pick n Pay SOAP and Shoprite REST, with no in-repo caller.
- Cron HTTP entry point, scheduled email send, and server-usage alerting.
- A CLI loop `php spark monitor:system`.
- Developer screens: menu management and a CRUD generator.
- ChatGPT page that calls OpenAI completions.
- SonarQube scan on the `main` branch via Bitbucket Pipelines.

Out of scope of the code that was found, or present only as views, routes, or `use` statements:

- Controllers `Products`, `Orders`, `Company`, `FaultFinder`, `LabelStatus`, `LabelUserGroups`, `LabelEmailTemplates`, `GetXMLData`, `StoreApiController`, and `Organisations`.
- Models `InvoicesModel`, `OrdersModel`, `ProductsModel`, `CompanyModel`, `CompanyStoresModel`, `EmailPixelTrackingModel`.
- Migrations for domain tables the code queries (`companies`, `company_users`, `products_master` via a missing model, `password_reset`, `uploaded_file`, `server_monitoring_log`, `site_health`, `test`, `test_log`, `app_session`, `files`, and others).
- Row-level security. Named only in `README.md`.
- AWS SDK, mPDF, and PhpSpreadsheet usage in application code. They are Composer requirements only.
- Salesforce and Africa's Talking. Helper bodies are empty or fully commented.
- Self-registration. `Welcome::register()` is empty. A comment says registrations are not done on this application.
- Documents named by `README.md` that are not in the tree: `PROJECT_RULES.md`, `CHANGELOG.md`, `NewKnowledgeBase.md`.

## System architecture

```text
Browser
  → Apache or `php spark serve` (public/ is the web root)
      → CodeIgniter 4
          → Filters: session login, then menu grant
          → Controllers under app/Controllers
          → Models under app/Models
          → MySQL database name wca_dms (from env template)
          → Views (AdminKit PRO, Bootstrap 5, DataTables, Feather)

Unauthenticated HTTP
  → GET cronJobs (CronJobs::index) — weekday window, optional production key
  → GET slack (Slack::sendMessage)
  → GET tracking-pixel
  → resource routes organisations and store-api (controller classes absent)

CronJobs / spark monitor:system
  → MySQL (cronjob_actions, sent_queue, server_monitoring_log)
  → SMTP smtp.overdriveqa.co.za
  → Linux `top` (monitor command only)

Rest.php / Soap.php (no in-repo caller)
  → Shoprite HTTP XML
  → Pick n Pay SOAP PullService
  → writable XML files
```

Menu items are rows in `user_menu` / `user_submenu`, not a fixed sidebar. The seed inserts Dashboard, Users, Media Files, System Settings, Menu Management, and CRUD Generator.

## Major components

| Component | Location | Role |
|---|---|---|
| Login and account recovery | `app/Controllers/Welcome.php` | Login, 2FA, reset, logout, forbidden page |
| Session gate | `app/Filters/Authentication.php` | Redirects to `/` when `isLoggedIn` is not true |
| Menu gate | `app/Filters/Authorization.php` | First URL segment must match a menu row the role can access |
| Users and roles | `app/Controllers/Users.php`, `SystemUsers.php` | Users, roles, menu grants, company-user flags |
| Settings | `app/Controllers/SystemSettings.php` | Cron, mail, holidays, history, block list, key/value settings |
| Reports UI | `app/Controllers/Reports.php`, `app/Views/reports/` | Renders tabs. Data endpoints are not implemented on the controller |
| EDI clients | `app/Controllers/Rest.php`, `Soap.php` | Pull and confirm retailer orders |
| Jobs | `app/Controllers/CronJobs.php`, `app/Commands/MonitorSystemUsage.php` | Email queue and host metrics |
| Mail | `app/Helpers/mail_helper.php`, `app/Config/Email.php` | HTML mail via SMTP |
| Developer tools | `app/Controllers/Developers/` | Menu builder and CRUD generator |

## Milestones visible in Git

There is no project plan, roadmap, or changelog in the repository. The only timeline is the five commits on 2025-09-01:

1. Initial commit.
2. "Core checkout".
3. "update to bootable version".
4. "Cleanup dashboard".
5. SonarQube project properties edited in Bitbucket.

What "bootable" included, and which later Admin Overdrive work was left out, is **Unknown / Requires Confirmation**.

## Known dependencies

Runtime, from `composer.json` and `README.md`:

- PHP. `composer.json` requires `^8.0`. `README.md` says PHP 8.3 is required. Extensions named in the README: intl, mbstring, mysqlnd, json, xml, and libcurl if HTTP\CURLRequest is used. `ext-simplexml` is a Composer requirement.
- CodeIgniter 4.6 (`^4.6`).
- MySQL via MySQLi. Database name in `env`: `wca_dms`. Host `localhost`, user `root`.
- `league/csv` `^9.16`, used by `Csv`.
- `orhanerday/open-ai` `^3.5` is required. The ChatGPT helper uses curl against `https://api.openai.com/v1/completions` and does not call that package.
- `aws/aws-sdk-php`, `mpdf/mpdf`, `phpoffice/phpspreadsheet` are required. No application call site was found.
- PHPUnit 9 and Faker are dev requirements. Tests under `tests/` are the CodeIgniter examples plus `HealthTest.php`.

Frontend assets under `public/assets/`: AdminKit PRO v3.0.2, Bootstrap 5 (v5.1.1 in `bootstrap.min.css`; `app.css` header says Bootstrap v5.0.1), DataTables with Bootstrap 5 styling, Feather icons.

## Implementation plan

No implementation plan is stored in the repository. `README.md` setup steps are: copy `env` to `.env`, `composer install`, `php spark db:create`, `php spark migrate`, `php spark db:seed users`, `php spark key:generate`, `php spark serve`. An Apache vhost example uses document root `c:/wamp64/www/adminOverdrive/public` and host `adminOverdrive.local`. The same README also gives test URL `http://localhost/wca_dms/`.

`README.md` says developers must use MySQL MCP, Playwright MCP, and Context7 MCP. Those tools are not configured in this repository.

## Current project status

**Implemented Behaviour:** a CodeIgniter admin shell with authentication, menus, settings, mail, cron, monitoring, and two retailer EDI clients that nothing in the tree invokes.

**Incomplete relative to its own routes and views.** `app/Config/Routing.php` sets `$autoRoute = false`, so only explicit routes run. Several routes name classes that are not in `app/Controllers`. Several views call URLs that are not in `Routes.php`. Several controllers import models that are not in `app/Models`. Several queries use tables that have no migration in `app/Database/Migrations`.

A fresh `php spark migrate` plus `db:seed users` therefore cannot, from this repository alone, create every table the running code expects. Whether production uses a database that was migrated elsewhere is **Unknown / Requires Confirmation**.

**Security items that require human review** (values are not copied into this document):

- `app/Config/Email.php` contains an SMTP password.
- `app/Helpers/chatgpt_helper.php` contains an OpenAI bearer token.
- `app/Controllers/Slack.php` contains a Slack webhook URL.
- `env` contains an `encryption.key`.
- `app/Database/Seeds/Users.php` and `README.md` contain a local developer password.
- `Rest.php` hardcodes a Shoprite `ContractID`.
- CSRF and honeypot filters are commented out in `app/Config/Filters.php`.
- `GET slack` and `GET cronJobs` are outside the login filter.

Bitbucket Pipelines on `main` runs only a SonarQube scan (`sonarsource/sonarqube-scan:3.0.2`). It does not deploy, test, or migrate.