# Technical documentation — edi_shopfront (EDI ShopFlow / Transactflow Shopfront)

Evidence date: 2026-10-16.

Source: `git@bitbucket.org:overdrive/edi_shopfront.git`, `main` at `9d1d726`.

Secrets may exist in env templates or committed config. This document names variable keys and file kinds. It does not copy passwords, tokens, webhook URLs, or keys.

## Stack

| Item | Evidence |
|---|---|
| Language | PHP `^8.0` (`composer.json`). README claims PHP 8.3 — **conflict** |
| Framework | `codeigniter4/framework` `^4.0` |
| Web root | `public/` (`public/index.php`, README vhost examples) |
| Database | MySQL via MySQLi. Template DB names `edi_shopfront` (`app/env`) / `shopflow_local` (`app/Config/Database.php`). Tests: SQLite3 memory |
| HTTP client | `guzzlehttp/guzzle` `^7.9` |
| PDF | `mpdf/mpdf` `^8.1` |
| Spreadsheets | `phpoffice/phpspreadsheet` `^1.25`, `league/csv` `^9.16` |
| XML | `ext-simplexml`; SOAP via PHP `SoapClient` |
| OpenAI | `orhanerday/open-ai` `^3.5` + `chatgpt_helper.php` |
| AWS SDK | `aws/aws-sdk-php` `^3.254` — required; **no usage found under `app/`** |
| JWT | Custom `app/Libraries/JwtLibrary.php` |
| Tests | PHPUnit `^9.1`, script `composer test` |
| Licence | MIT (`LICENSE`) |
| Package name | `codeigniter4/adminstarter` |
| Description | Transactflow |

README also lists ext-intl, ext-mbstring, ext-mysqlnd, ext-json, ext-xml, and libcurl.

## Application structure

```text
app/
  Commands/           DeactivateExpiredAdverts, MonitorSystemUsage
  Config/             Routes, Filters, Database, StoreApi, PermissionConfig, …
  Controllers/        58 PHP controllers including SellerPortal/ and Developers/
  Database/
    Migrations/       146 migrations (2022–2025)
    Seeds/            Users, roles, menus, products, industries, transport methods, …
  Filters/            Authentication, Authorization, Cors
  Helpers/            mail, menu, useraccess, chatgpt, slack, salesforce (stub), africastalking (stub)
  Libraries/          JwtLibrary
  Models/             44 models
  Services/           ExternalOrderService, PermissionService, PriceFileTransformationService
  Views/              shop, seller portal, admin, system settings, …
  Validation/, Language/, Contracts/
public/               Front controller and assets
tests/                Scaffold PHPUnit only
writable/             logs, cache, session, XML order/invoice templates
bitbucket-pipelines.yml
composer.json
phpunit.xml.dist
sonar-project.properties
overview.md, README.md
```

Auto-routing is enabled (`$routes->setAutoRoute(true)` in `Routes.php`). Explicit routes cover auth, seller portal, shop, partner management, price files, system settings, store-api, cronJobs, organisations, developers tools, and more. Controllers remain reachable by conventional CI4 auto-routes subject to filters.

## Controllers (inventory)

**Core / auth:** `Welcome`, `Home`, `UnlockController`, `LoginHistory`

**Shop:** `Products`, `Orders`, `Carts`, `JabOrders`, `Store`

**Seller portal:** `SellerPortal\SellerAuth`, `SellerHome`, `SellerProducts`, `SellerOrders`, `SellerAnalytics`, `SellerSettings` (+ portal `BaseController`)

**Partner / catalog:** `SellerManagement`, `SellerGroupsManagement`, `BuyerGroupManagement`, `StoreManagement`, `IndustryManagement`, `Company`, `CompanyUsers`, `PriceFiles`, `PriceFileApplications`, `PriceFileMappingRules`, `PriceFileData`

**Platform:** `Users`, `SystemUsers`, `RolesPermissions`, `SystemSettings`, `SystemNotifications`, `AdvertsManagement`, `Reports`, `FaultFinder`, `ServerMonitoring`, `SiteHealth`

**EDI / integrations:** `GetXMLData`, `Soap`, `Rest`, `StoreApi`, `CronJobs`, `Email`, `EmailPixelTracking`, `Slack`, `Csv`, `Upload`, `UploadedFile`, `File`

**Developer / misc:** `Developers\MenuManagement`, `CRUDGenerator`, `DbTableDataView`, `ChatGPT`, `Test`, `TestLog`, `DbAdmin`, `ApiSimulation`, `BaseController`

## Filters and security

| Filter alias | Class | Global use |
|---|---|---|
| `isLoggedIn` | `App\Filters\Authentication` | Before, with large exception list |
| `isGranted` | `App\Filters\Authorization` | Before, with exception list |
| `csrf` | CI CSRF | Aliased; **commented out** of globals |
| `honeypot` | CI Honeypot | Aliased; **commented out** |
| `toolbar` | DebugToolbar | After (except `chatGPT/*`) |
| Cors | `App\Filters\Cors` | Present; not aliased in Filters.php globals |

Unauthenticated surfaces include `cronJobs`, `store-api/*`, `organisations`, `tracking-pixel`, and auth recovery routes. Treat these as security-sensitive when reviewing.

## Routing highlights

| Prefix / path | Purpose |
|---|---|
| `/`, login, 2FA, password reset, portal-selection | Auth |
| `seller/*` | Seller portal |
| `shop/*`, products, orders, carts, jab-orders | Buyer shop |
| `productmanagement/*` | Admin product / price files |
| `seller-management/*`, `seller-groups-management/*`, `buyer-group-management/*`, `store-management/*`, `industrymanagement/*` | Master data |
| `company_users`, `system_users`, `users/*`, `roles-permissions` | Users / RBAC |
| `system_settings/*`, `system_notifications/*` | Platform config |
| `adverts-management/*` | Adverts |
| `faultfinder/*`, `monitoring/*`, `reports/*` | Ops |
| `store-api/*` | External StoreFront proxy (filter-excepted) |
| `cronJobs` | Cron runner (filter-excepted) |
| `organisations` | REST + token login |
| `tracking-pixel` | Email open tracking |
| Developers menu / CRUD routes | Code generation tools |

## Configuration and environments

Boot files exist for development, production, and testing under `app/Config/Boot/`.

Environment template observed as `app/env` (README still says copy root `env` to `.env` — **documentation conflict**).

Notable keys (names only):

| Key / area | Use |
|---|---|
| `app.baseURL` | e.g. `edishopfront.local` in template |
| Database host/name/user/pass | MySQL `edi_shopfront` / `shopflow_local` |
| Session handler | DatabaseHandler / `sessions` |
| SMTP / SendGrid related keys | Outbound mail |
| `OPENAI_API_KEY` | ChatGPT |
| Google Maps key placeholder | Unknown usage extent |
| `STORE_API_BASE_URL`, `STORE_API_KEY`, `STORE_API_ORG_NAME` | Used by `Config/StoreApi.php` (may be missing from incomplete env templates) |

`StoreApi` constructor reads Store API vars via `getenv`. Default `verifySSL = false`.

## Data layer

- **146 migrations** under `app/Database/Migrations/`.
- **44 models** under `app/Models/`.
- **Seeds:** Users/UserSeeder, UserRole, UserAccess, UserMenu*, Organisations, Products, Categories, SubCategories, Brands, Industries, Holidays-related, TransportMethodOptions, FaultType, Settings, SystemNotifications, UploadedFile, ErrorCheckStatus, etc.

Important entity groups (non-exhaustive): users/roles/menus/sessions; organisations/companies/company_users; stores/store_users; seller_groups / supplier_store; industries; products/variations/categories/brands; carts/cart_items; orders/order_items; payments; price_files and related mapping/application tables; adverts; system_notifications; cronjob_actions/cronjob_log; sent_queue/email_logs; login_history; blocked_users_list; password_reset; email_authentication_codes; fault_finder_log; media_file; settings.

## Services and libraries

| Class | Role |
|---|---|
| `ExternalOrderService` | Validate/prepare/submit orders to Store API; retries; circuit breaker |
| `PriceFileTransformationService` | Price file transform pipeline |
| `PermissionService` | Page-action permission helpers |
| `JwtLibrary` | Token support for organisations / API simulation |

## Background processing

| Mechanism | Details |
|---|---|
| HTTP cron | `GET cronJobs` → `CronJobs::index` |
| Job config | Table `cronjob_actions` |
| Email queue | `sent_queue` processed by cron/email methods |
| Spark | `adverts:deactivate-expired`, `monitor:system` (long-running monitor with PID file) |
| Message brokers | None found (no Redis/Beanstalk queue product) |

## External integrations (technical)

| Integration | Implementation touchpoints |
|---|---|
| Transactflow Store API | `StoreApi` controller/config, `ExternalOrderService`, Guzzle |
| PnP SOAP | `Soap.php` WSDL clients |
| Shoprite REST | `Rest.php` / `GetXMLData` |
| M2North SOAP | `Soap.php` |
| Folder EDI | Filesystem under `writable/` + GetXMLData |
| Email | CI email / helpers; pixel route |
| Slack | Controller + helper |
| OpenAI | Helper + ChatGPT controller |

Default Store API host mentioned in exploration/config comments: `https://qa.transactflow.io` — confirm against live env.

## Deployment and CI

`bitbucket-pipelines.yml`:

| Branch | Deploy | Quality |
|---|---|---|
| `main` | `git ftp push` with `FTP_USERNAME` / `FTP_PASSWORD` / `FTP_HOST` | SonarQube scan step |
| `qa` | FTP with `*_QA` vars | SonarQube |
| `storefront` | FTP with `*_SHOPQA` vars ("shop qa") | SonarQube |

No Docker assets found. Sonar project properties in `sonar-project.properties`. Clone depth is `full` for Sonar.

Local README flow: composer install → migrate → seed Users → `key:generate` → `spark serve` or Apache vhost (examples still say `adminOverdrive.local`).

## Development and testing

| Aspect | Finding |
|---|---|
| Unit/integration tests | `tests/unit/HealthTest.php`, `tests/session/ExampleSessionTest.php`, `tests/database/ExampleDatabaseTest.php` only |
| Domain tests | None found for orders, EDI, auth, seller portal |
| Coverage config | `phpunit.xml.dist` covers `app/`, excludes Views/Routes |
| E2E / TestSprite | Not present in this repository |
| Quality | SonarQube via pipeline |

## Monitoring and operations

- `ServerMonitoring` UI + `MonitorSystemUsage` Spark command.
- `FaultFinder` for order/invoice/product fault investigation.
- `SiteHealth` controller.
- Cron logging tables.
- Slack alerts (optional).

## Security notes (implemented posture, not recommendations)

1. CSRF/honeypot disabled globally.
2. Auto-routing expands the attack surface beyond explicit routes.
3. Cron and store-api are publicly routable (cron keyed in production).
4. Store API SSL verify default false.
5. Env templates may contain secret placeholders; never commit real secrets into Silicon Ark docs.
6. Developer tools (CRUD/menu generators, DbAdmin, ChatGPT) exist in the same app — confirm production exposure.

## Related documentation in Silicon Ark

This directory:

- `project-plan.md`
- `prd.md`
- `features.md`
- `business-rules.md`
- `technical-documentation.md`

Source-repo docs: `README.md`, `overview.md`, `tests/README.md` (framework stock).