# Project plan — crimemapping-webportal

Evidence date: 2026-10-18.

Source repository: `git@bitbucket.org:overdrive/crimemapping-webportal.git`.

Inspected revision: `master` at `f8a20d417360a299dcb1ba1ab4ef2ddcfce4d95b` (`f8a20d4`, 2024-02-05 11:02:03 +0200, JacquesOverdrive, "Add notes to export crime log"). `origin/HEAD` is `master`. This matches the tip recorded on OVER-77.

The scan-host path `~/projects/sonar_scan/repos/crimemapping- webportal` was not on this machine. The tree was read from a clone of `origin/master`. The onboarding issue spells the folder with a space (`crimemapping- webportal`). The Bitbucket slug, the README document root, and this Silicon Ark directory do not. The space is treated as a scan-path artefact.

Fetched history on this clone is 52 commits, from `66cdbb4` (2023-04-04, Russel, "Update User Profile validation alert styling") through `f8a20d4`. Migrations are dated 2022-11-20, so the repository existed before the fetched window. History older than 2023-04-04 was not retrieved. No tags were inspected. Authors visible in the fetched window include JacquesOverdrive and Russel.

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

There was no `crimemapping-webportal/` directory in Silicon Ark before this document set. The README is the CodeIgniter "Admin Overdrive Starter" text plus a WAMP vhost named `crimeMappingWebportal.local`. It does not state a customer problem.

## Product

Staff use a browser to record crime incidents against organisations, place them on a map, and export the log. A JSON API lets a mobile or vendor client register a person, sign in with a cellphone number, and submit a crime with photos. A second map page loads a Stellenbosch University GIS script.

Provenance: **Implemented**, recovered from controllers, views, and the API. No product brief exists in the repository.

The sidebar brand and the live menu titles are database rows (`user_menu`), not hard-coded in the seeded menu. The seeded menu is still the starter set: Dashboard, Users, Menu Management, CRUD Generator.

A related Silicon Ark set, `crimemapping_website` (OVER-78), documents a later repository whose admin README uses the same local vhost name `crimeMappingWebportal.local` and whose public page titles itself Crimemapping. That repository's inspected tip is 2025-11-14. Whether `crimemapping-webportal` is an ancestor of that admin, a split deploy, or a separate line is **Unknown / Requires Confirmation**. This plan covers only `crimemapping-webportal` at `f8a20d4`.

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

No project plan exists in the repository. The following are **Inferred**:

- Let an organisation's staff record a crime: who reported it, when, where (latitude, longitude, address), which incident types apply, and a note.
- Let staff mark a crime verified, and keep that verified state once it is set.
- Let staff group same-day crimes by setting a parent id.
- Show crimes on a Google Map, filtered by date, incident type, and an "attempted" flag, and limit an organisation-scoped role to its own organisation.
- Let staff export the log to copy, CSV, Excel, PDF, or print from the browser.
- Let a client create a user and post a crime with JPEG or PNG photos over HTTP, using a bearer token.
- Let a GIS vendor list towns and page through crimes for a town as point features.
- Keep organisations in a parent/child tree and attach suburbs from a locations catalogue.

The README links a Jira board (`SI`, board 12) and a Confluence space (`AO`). A commit message cites `CRIM-49`. The contents of those trackers are not in the repository.

## Scope

In this repository:

- CodeIgniter 4 staff UI under `app/` with the document root `public/`.
- Session login, role menu permissions, users, roles, organisations, locations, incident types, crime log, crime map, crime-map GIS page, crime-log export, activity log, menu management, and a CRUD generator.
- JSON resources `apiusers`, `apicrimes`, `apiincidents`, `apiorganisations`, and `apigis`.
- MySQL schema created by migrations dated 2022-11-20 and 2022-11-25, plus tables the PHP uses that those migrations do not create (`locations`, `org_location_map`, and several columns). See technical documentation.
- Bitbucket pipeline: SonarQube scan, then `git ftp push` of `master`.

Out of this repository, as far as the tree shows:

- The mobile client that calls the API. **Unknown**.
- The GIS application served from `https://sungis10.stb.sun.ac.za/crimestatic/`. Only the script tags are in this repo.
- Production hostname, FTP host, and the live database name. The example `env` sets `database.default.database = adminoverdrive` and `app.baseURL` commented as `http://localhost:8080`.

## System architecture

```text
Browser (staff)
  session cookie, database-backed sessions
  CodeIgniter 4 (PHP 8, auto-routing on)
        |
        +-- MySQL (MySQLi): users, roles, menus, organisations,
        |     locations, crime_log, incident_type, images, activity_log
        |
        +-- Google Maps JavaScript (key from GOOGLE_MAP_API_KEY)
        +-- DataTables Buttons (client-side export)
        +-- OpenLayers bundle on sungis10.stb.sun.ac.za (GIS page only)

HTTP client (mobile or GIS vendor)
  Authorization: Bearer <JWT signed with the library default secret>
  same CodeIgniter app, filters skip login for /api* routes
  crime photos written under assets/img/crime_images/{organisation}/{crime}/
```

There is no queue, no cron, and no background worker in the tree.

## Major components

| Area | Where | Role |
|---|---|---|
| Staff shell | `app/Controllers/Welcome.php`, `Home.php`, `app/Views/layouts/` | Login, empty dashboard, sidebar from menu tables |
| Crime log | `CrimeLog.php`, `CrimeLogModel.php`, `common/crimeLogList.php` | Create, update, delete, incidents, child crimes, images lookup |
| Export | `CrimeLogExport.php`, `common/crimeLogListExport.php` | Read-only table with DataTables export buttons, including Notes |
| Map | `CrimeMap.php`, `public` script `assets/js/crimeMap.js` | Google Map markers for a date range |
| GIS map | `CrimeMapGis.php`, `common/crimeMapGis.php` | Hosts the external Stellenbosch script |
| Organisations | `Organisations.php` | Parent/child orgs and suburb links |
| API | `apiUsers.php`, `apiCrimes.php`, `ApiIncidents.php`, `ApiOrganisations.php`, `Apigis.php` | JSON for clients and the GIS vendor |
| Access | `Filters/Authentication.php`, `Filters/Authorization.php`, `Users.php`, `UserRoles.php` | Session gate and per-menu grant |
| Starter tools | `Developers/MenuManagement.php`, `Developers/CRUDGenerator.php` | Build menus and scaffold CRUD |

## Milestones visible in the fetched history

These are commit subjects, not an approved roadmap.

| When | Commit | What landed |
|---|---|---|
| 2023-04-04 | `66cdbb4` and neighbours | Profile validation and password-field cleanup (oldest fetched commits; Russel) |
| 2023-06-23 | `92785fd` | Export page and crime-date fix |
| 2023-07-12 | `ccc1dd4` | Delete-button changes (Russel) |
| 2023-07-13 | `bbe9f75` | Geo API |
| 2023-07-20 | `7c2f075` | Linking crimes |
| 2023-07-24 | `3b92c10` | "theo map" (the GIS page) |
| 2023-07-25 | `64847b2` | Delete restrictions and export update |
| 2023-12-01 | `afab9d0` | New GIS API call |
| 2023-12-06 | `7e3d7b9` | Geocoding disabled |
| 2024-02-05 | `004b521`, `38b40a9`, `0427601`, `f8a20d4` | Suburb list on organisations, attempted incidents, incident ordering, notes column on the export |

Nothing in the fetched history is newer than 2024-02-05. Current status: **the `master` tip has not moved since that date**, as far as this clone shows. Whether a deploy is still serving this tree is **Unknown / Requires Confirmation**.

## Implementation plan

There is no forward plan in the repository. The README lists two external boards and an empty "CRUD automation scrips" heading. `ApiUsers::ForgotPassword` and `ApiUsers::ChangePassword` are empty methods. Commented blocks remain for crime update/delete on `apiCrimes` and for an email/password API login.

## Known dependencies

- PHP `^8.0`, CodeIgniter 4.3.2 (installed under `vendor/`).
- MySQL via MySQLi. Example database name `adminoverdrive`.
- `aws/aws-sdk-php`, `mpdf/mpdf`, and `phpoffice/phpspreadsheet` are in `composer.json`. No `app/` PHP file references them. Export is done in the browser by DataTables Buttons.
- Google Maps JavaScript API. The key is read from `$_ENV['GOOGLE_MAP_API_KEY']`. That variable is not in the committed `env` example.
- DataTables 1.13.2 and Buttons 2.3.6 from CDN, plus copies under `public/assets/js/`.
- Stellenbosch host `sungis10.stb.sun.ac.za` for the GIS page.
- Bitbucket Pipelines variables `SONAR_HOST_URL`, `SONAR_TOKEN`, `FTP_USERNAME`, `FTP_PASSWORD`, `FTP_HOST`.

## Current project status

| Item | State |
|---|---|
| Staff crime log, map, export, organisations, users | Implemented on `master` |
| Mobile/vendor JSON API | Implemented, with gaps called out in the PRD |
| Written requirements | Absent from the repo and from Silicon Ark before this set |
| Automated product tests | Absent. `tests/` is the CodeIgniter example suite |
| Production URL and whether FTP deploy is still used | Unknown / Requires Confirmation |
| Schema vs migrations | Diverged. See technical documentation |