# Project plan — edi_shopfront (EDI ShopFlow / Transactflow Shopfront)

Evidence date: 2026-10-16.

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

Inspected revision: `main` at `9d1d726` (2025-11-24, "Merged in qa (pull request #289)").

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

## Product

The Git repository is named **edi_shopfront**. The Composer package description is **Transactflow**. Runtime branding and database names use **EDI ShopFlow** / **EDI Shopfront** / `shopflow_local` / `edi_shopfront`. The README still titles the tree **Admin Overdrive Starter**.

| Source | What it calls the product |
|---|---|
| Repository name and origin | `edi_shopfront` |
| `composer.json` description / homepage | Transactflow / `https://www.overdrive.co.za` |
| `composer.json` package name | `codeigniter4/adminstarter` |
| `overview.md` | Transactflow, hosted by Overdrive |
| `README.md` | Admin Overdrive Starter |
| `app/env` (template) | `app.baseURL` `edishopfront.local`; database `edi_shopfront` |
| `app/Config/Database.php` | Default DB name `shopflow_local` |
| Seller order PDF export | Branding references EDI ShopFlow / EDI Shopfront (`SellerPortal/SellerOrders.php`) |
| `sonar-project.properties` | Sonar key beginning `overdrive_edi_shopfront_` |
| Bitbucket pipeline branch `storefront` | Deploy step named "shop qa" |

**Implemented** behaviour is a multi-tenant B2B shopfront and EDI exchange platform: buyers order products by store; sellers manage catalog and fulfilment; admins configure companies, stores, price files, transport methods, and cron-driven EDI import/export toward retailers (folder XML, Pick n Pay SOAP, Shoprite REST, M2North SOAP) and an external Transactflow Store API (TAF).

**Documented** in `README.md` as a generic admin starter (auth, authorization, registration, menu management). That README does not describe the shop or EDI domain.

**Unknown / Requires Confirmation:** the official product name for customers and which branding (Transactflow vs EDI ShopFlow vs EDI Shopfront) is canonical.

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`. Remote branch names referenced by the pipeline include `main`, `qa`, and `storefront`.

| Commit | Date | Subject |
|---|---|---|
| `9d1d726` | 2025-11-24 | Merged in qa (pull request #289) |

Full history exists in the clone (shallow clone was not used for the inspection clone beyond a normal fetch). Milestones are inferred from migration dates (2022–2025) and feature controllers, not from a written roadmap in-repo.

## Scope in the repository

In scope of what is present on `main`:

- A CodeIgniter 4 application (`codeigniter4/framework` `^4.0`) with session auth, menu RBAC, optional email 2FA, buyer/seller portal selection, and company/store scoping.
- Buyer shop: products, multi-cart, standard orders, JAB multi-store orders, order history, regrets, print/export, external TAF submission with retry and circuit breaker.
- Seller portal under `/seller`: login, dashboard, products, orders (process/status/export), analytics, settings.
- Partner / master data: sellers, seller groups, buyer groups, stores, industries, companies and company users.
- Catalog and pricing: products/variations, price files, mapping rules, applications (approve/apply/revert).
- Platform admin: users, system users, roles/permissions, system settings (including transport methods, cron actions, email templates, holidays), system notifications, adverts.
- EDI and integrations: `GetXMLData`, `Soap`, `Rest`, `StoreApi`, `CronJobs`, email queue and pixel tracking, Slack helper, FaultFinder, reports, server monitoring.
- Developer tools: menu management (can write controller/view files), CRUD generator, DB table viewer, ChatGPT page, API simulation, DbAdmin.
- Bitbucket Pipelines: git-ftp deploy per branch + SonarQube scan.
- Spark commands: `adverts:deactivate-expired`, `monitor:system`.
- 146 migrations, 44 models, 58 controllers (including SellerPortal and Developers namespaces).

Out of scope of the code that was found, or only partially present:

- Payment gateway processing. A `payments` table/model surface exists; no card/gateway integration was found under `app/`.
- AWS SDK usage in application code. Package is required in Composer; no `S3Client` / Aws client usage found under `app/`.
- Salesforce and Africa's Talking. Helpers are stubs.
- Email transport type for EDI orders/invoices is marked incomplete in `GetXMLData` comments.
- Domain-level automated tests. PHPUnit suite is scaffold/example only.
- Docker. No Dockerfile or compose file found.
- CSRF / honeypot. Aliases exist; both are commented out of global filters.

## System architecture

```text
Browser (buyer shop / seller portal / admin UI)
  → Apache / WAMP vhost or `php spark serve` (public/ is the web root)
      → CodeIgniter 4 (auto-routing on)
          → Filters: session login (isLoggedIn), then menu grant (isGranted)
          → Controllers / Services / Models → MySQL
          → Outbound:
                - Transactflow Store API (Guzzle / ExternalOrderService)
                - Retailer SOAP (PnP, M2North) and REST (Shoprite)
                - Folder-based EDI XML under writable/
                - SMTP / email queue (sent_queue)
                - Slack webhooks (optional)
          → Inbound unauthenticated:
                - GET cronJobs (keyed in production)
                - store-api/* proxy routes
                - organisations REST + JWT
                - tracking-pixel, auth reset / 2FA routes
```

## Major components

| Component | Location | Role |
|---|---|---|
| Auth & portal selection | `Welcome.php`, `UnlockController.php`, filters | Login, 2FA, password reset, Buyer/Seller portal |
| Buyer shop | `Products`, `Carts`, `Orders`, `JabOrders` | Catalog browse, cart, place/schedule orders |
| Seller portal | `SellerPortal/*` | Seller-facing fulfilment UI |
| External orders | `Services/ExternalOrderService.php`, `StoreApi.php` | Submit orders to TAF StoreFront API |
| EDI engine | `GetXMLData.php`, `Soap.php`, `Rest.php`, `CronJobs.php` | Import/export orders and invoices |
| Price files | `PriceFiles*`, `PriceFileTransformationService` | Upload, map, approve, apply pricing |
| RBAC | `Authorization` filter, `RolesPermissions`, seeds | Menu and page-action permissions |
| Ops | `FaultFinder`, `Reports`, `ServerMonitoring`, Spark monitor | Diagnostics and reporting |

## Known dependencies

| Dependency | Purpose | Evidence |
|---|---|---|
| PHP `^8.0` (composer) / 8.3 claimed (README) | Runtime | Conflict — see unknowns |
| CodeIgniter 4 | Framework | `composer.json` |
| MySQL / MySQLi | Primary data store | `Database.php`, `app/env` |
| Guzzle | HTTP client for Store API | `composer.json`, services |
| mPDF / PhpSpreadsheet / League CSV | PDF and spreadsheet export/import | `composer.json`, controllers |
| OpenAI PHP client | ChatGPT feature | `composer.json`, helper |
| AWS SDK | Declared only | Unused under `app/` |
| Bitbucket + git-ftp + SonarQube | CI/CD | `bitbucket-pipelines.yml` |
| External TAF Store API | Order submission | `Config/StoreApi.php`, env `STORE_API_*` |
| Retailer endpoints | EDI partners | `Soap.php`, `Rest.php`, `GetXMLData.php` |

## Implementation plan / milestones (inferred from history)

There is no project-plan or roadmap file in the source repository. The following is **Inferred** from migrations and modules:

1. Admin Overdrive starter platform (auth, menus, users) — base of the tree.
2. Company / organisation / store master data and transport methods.
3. Buyer shop (products, carts, orders) and seller portal.
4. Price file pipeline and applications.
5. EDI cron import/export and FaultFinder.
6. External Store API integration with retry/circuit breaker.
7. Adverts, system notifications, JAB orders, monitoring commands (later migrations 2024–2025).

Exact milestone dates and whether each item was an approved product release are **Unknown / Requires Confirmation**.

## Current project status

| Aspect | Status |
|---|---|
| Application code | Active on `main`; last merge from `qa` 2025-11-24 |
| Deploy | Automated FTP deploy on `main`, `qa`, `storefront` |
| Quality gate | SonarQube scan after deploy step |
| Automated product tests | Not present (scaffold PHPUnit only) |
| In-repo product docs | Thin (`README` starter + generic `overview.md`) |
| Silicon Ark docs | This directory (`silicon_ark/edi_shopfront/`) — created 2026-10-16 |

## Open questions for humans

See the "Requires confirmation" sections in `prd.md`, `business-rules.md`, and the unknowns list in the completion report. Highest impact: official product name, PHP version target, payment feature intent, CSRF posture, and production Store API / retailer configuration ownership.