# Project plan — laravel

Evidence date: 2026-10-10.

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

Inspected revision: `master` at `10c0b9fa` (2023-08-15, Wessels, "Restore prod .env"). The scan-host path `~/projects/sonar_scan/repos/laravel` was not on this machine. The tree below was read from that git revision.

`vendor/`, `bvendor/`, `public/` (154,196 files), and `storage/` (34,145 files) were not checked out. Counts come from `git ls-tree`. Application code, configuration, routes, migrations, scripts, tests, and root files were read. Committed secrets are named in the security notes and are not reproduced.

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

## Product

The committed production environment names the application **Freshtrade** (`APP_NAME`) and sets `APP_URL` to `https://market.hellochoice.co.za`. `config/application.php` sets `site_name` and `fromName` to **HelloChoice**.

CodeDeploy copies the tree to `/mnt/efs/www/html/market.hellochoice.co.za/`.

There is no README and no product requirements document in the source repository. There is no prior Silicon Ark folder for this project. `composer.json` still says the package name is `laravel/laravel` and the description is "The Laravel Framework."

**Implemented.** A logged-in buyer, seller, guest, or "both" user who opens `/` receives the dashboard (`HomeController@index`). The marketplace lists lots. Sellers publish bid lots, bin (buy-it-now) lots, special offers, donations, agent loads, and price-on-application lots. Buyers bid, place proxy bids, fill a bin cart, and reserve relief lots. Administrators maintain the catalogue under `/admin`. A JWT API under `/api` covers the same trading actions for a mobile client.

**Unknown / Requires Confirmation:** whether the market is still operated. The newest commit is 2023-08-15. No later branch exists in this repository.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `10c0b9fa` | 2023-08-15 | Production env restored after the `local-dev` merge |
| `local-dev` | `95f5a2e4` | 2023-08-14 | Stops at "Generate access key for dev" |

History on `master`:

| Commit | Date | Author | Message |
|---|---|---|---|
| `01ed0807` | 2023-08-11 | Jaco Brits | Initial commit |
| `ad78d7a6` | 2023-08-14 | Wessels | Initial Commit - NOT PROD READY |
| `95f5a2e4` | 2023-08-14 | Wessels | Generate access key for dev |
| `645a4649` | 2023-08-14 | Wessels | Initial commit |
| `8d527dce` | 2023-08-14 | Wessels | Merge branch `local-dev` |
| `10c0b9fa` | 2023-08-15 | Wessels | Restore prod .env |

Between `origin/local-dev` and `master`, excluding `vendor`, `bvendor`, `public`, and `storage`, the diff is `.env`, deletion of `BAK.env`, addition of `DEV.env`, and committed `bootstrap/cache/packages.php` and `bootstrap/cache/services.php`. Application PHP did not change on that range.

`BAK.env` is on `local-dev` and is absent from `master`. Its contents were not read.

`.revision` contains `47765854f9ae0f151de80ad81e32742858261643`. That object is not a commit in this repository.

**Discrepancy:** the task-creation scan listed `sonar-project.properties` and `sonarqube_scan.bat` at the repository root. Neither file is in git at `10c0b9fa`. Provenance: **Unknown** — they may have been untracked files on the scan host.

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

- Run the HelloChoice fresh-produce market at `https://market.hellochoice.co.za`.
- Let sellers list produce and buyers buy it by auction, fixed price (bin), offer, tender, or price-on-application.
- Carry special-offer and donation lots for relief partners.
- Expose the same trading actions to a mobile client through `/api`.
- Push live lot and bid changes to Firebase and notifications through FCM.
- Give administrators a catalogue, user, and lot console under `/admin`.

No written project plan, milestone list, or roadmap is in the repository. The commit message "NOT PROD READY" (2023-08-14) and "Restore prod .env" (2023-08-15) are the only status statements in history.

## Scope

### In scope of `master`

1. Laravel 5.5 application (`php: >=7.0.0`, locked `laravel/framework` `v5.5.50`).
2. Web UI in Blade under `resources/views/`, session auth, Spatie roles.
3. JWT API in `routes/api.php`.
4. MySQL with table prefix `ft_` (from the committed production `.env`).
5. Artisan commands that advance lot status, proxy bids, mail, notifications, and bin carts.
6. AWS CodeDeploy spec to an EFS path, owner `abhishek`.
7. Committed `vendor/`, `bvendor/`, `public/`, `storage/`, and a production `.env`.

### Out of scope of this repository

- The WordPress site that calls `GET /get_all_market_lots`. The route comment says it is for the WordPress site. That site is not in this repo.
- The mobile app that calls `/api`. Only the server routes are here.
- A written test plan. `tests/` holds the Laravel example tests. There is no project `phpunit.xml` and no Bitbucket Pipelines file.

## System architecture

```text
Browser (Blade, session)
        |
        +-- routes/web.php -- middleware user / role / admin
        |
Mobile client (JWT, device headers)
        |
        +-- routes/api.php -- middleware api, check-jwt, jwt.auth
        |
Laravel 5.5 (PHP)
        |
        +-- MySQL connection mysql   (market data, prefix ft_)
        +-- MySQL connection mysql2  (online users, user history)
        +-- File sessions, file cache, sync queue
        +-- SMTP mail.freshtrades.co.za
        +-- Firebase Realtime paths for lots and bids
        +-- FCM via brozot/laravel-fcm
        +-- Pusher config (broadcast driver in production .env)
        |
Artisan schedule (when APP_ENV is not dev)
        |
        +-- every minute: lot status, proxy bids, mail, notifications, bin cart, bulletin, offer reminders
        +-- daily: temp images, temp my-products
        |
CodeDeploy
        |
        +-- /mnt/efs/www/html/market.hellochoice.co.za/
```

Provenance: **Implemented** in the files named in `technical-documentation.md`. Whether a scheduler process and a web server are actually running on the EFS host is **Unknown**.

## Major components

| Area | Location | Role |
|---|---|---|
| Web routes | `routes/web.php` | Dashboard, marketplace, seller lots, buyer bids, admin |
| API routes | `routes/api.php` | Login, register, lots, bids, bin, profile, notifications |
| Domain config | `config/application.php` | Roles, statuses, limits, emails, Firebase paths |
| Models | `app/Models/` (102 classes) | Lots, users, bids, orders, catalogue |
| Web controllers | `app/Http/Controllers/` | Marketplace, lots, orders, reports |
| Admin controllers | `app/Http/Controllers/Admin/` | Catalogue and operations console |
| API controllers | `app/Http/Controllers/Api/` | Mobile counterparts |
| Commands | `app/Console/Commands/` | Status, proxy bid, mail, notifications |
| Views | `resources/views/` | Blade screens listed in the technical document |
| PDF | `app/Library/tcpdf` | Bulletin and marketplace-filter PDFs |
| Deploy | `appspec.yml`, `scripts/` | CodeDeploy onto EFS |

## Milestones

No milestone document exists. Git history is six commits across 11–15 August 2023, ending with a production `.env` restore. Earlier product history is not in this repository. The migration filenames run from the Laravel 5.5 users table through `2022_06_23` (transporters, truck sizes, loading points), so the schema was built over several years before this git history starts.

**Unknown / Requires Confirmation:** where the pre-2023 history lives, and whether this Bitbucket repo replaced an older remote.

## Known dependencies

Runtime, from `composer.json` / `composer.lock`:

- PHP `>=7.0.0`. Root `.htaccess` selects cPanel `ea-php70`.
- `laravel/framework` 5.5.50.
- `spatie/laravel-permission` ^2.6, `tymon/jwt-auth` `dev-develop`.
- `brozot/laravel-fcm` ^1.2, `kreait/firebase-php` ^4.0, `pusher/pusher-php-server` ^3.2.
- `maatwebsite/excel` ~2.1.0, `intervention/image` ^2.4, `doctrine/dbal` ^2.5.
- `mailgun/mailgun-php` ^2.6, `laravelcollective/html` ^5.4, `laracasts/flash` ^3.0.
- TCPDF copied under `app/Library/tcpdf` (not a Composer package).

Front end, from `package.json`: Laravel Mix 1, Vue 2.5, Bootstrap Sass 3.3, jQuery 3.2, Axios 0.17. The compiled Mix entry only registers `example-component`. The trading UI is Blade.

`bcomposer.json` is a second manifest. It omits `tymon/jwt-auth`, `brozot/laravel-fcm`, and `http-interop/http-factory-guzzle`. `composer.json` is the manifest that matches the current API and FCM code.

External systems are listed in `technical-documentation.md`. Credentials for them are committed and are not copied here.

## Implementation plan

There is no implementation plan in the repository. The code on `master` is the whole delivered system. Commented routes and a commented scheduler entry are recorded in `features.md` as present-but-disabled, not as an approved backlog.

## Current project status

| Item | Evidence | Status |
|---|---|---|
| Trading web app and API | Routes, controllers, models, 238 migrations | Implemented on `master` |
| Production env file | `APP_ENV=production`, `APP_DEBUG=false` | Committed. Secrets not reproduced |
| Deploy spec | `appspec.yml` | Implemented. Hook scripts do not start `httpd` |
| Automated tests | Example PHPUnit tests only | Present. They do not cover trading |
| CI | No pipeline file in git | Absent |
| Written plan / PRD | None in the source repo | Absent before this Silicon Ark set |

## Human confirmation

- Is HelloChoice / Freshtrade still the live market, and is `master` what production runs?
- Should the committed production `.env`, the Mailgun key, and the Google Maps key in `config/application.php` be rotated and removed from git?
- Are the unauthenticated Artisan trigger URLs in `routes/web.php` an approved cron interface?
- Which lot-status map is authoritative where the model constants and `config/application.php` disagree?
- Were `sonar-project.properties` and `sonarqube_scan.bat` ever part of this project?