# Project plan — crimemapping

Evidence date: 2026-10-18.

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

Inspected revision: `master` at `5927ab49dc787157e8742cd12e5a3a1d2afa5233` (`5927ab4`, 2023-12-06, JacquesOverdrive, "update"). `origin/HEAD` is `master`. No other remote branches and no tags were present.

The scan-host path `~/projects/sonar_scan/repos/crimemapping` was not on this machine. The tree was read from a clone of that git revision. OVER-76's recorded tip matches this commit. `sonarqube_scan.bat` was listed in the issue's scan inventory and is not in `git ls-files` at `5927ab4`.

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

There was no `silicon_ark/crimemapping/` directory before this document set. The README is a Create React App getting-started page titled "Crime Mapping Web Application", plus Firebase credential and deploy steps. It does not state a customer problem.

## Product

The HTML title is **Crime Mapping Org** (`public/index.html`). The web app manifest short name is **Crime Mapping** and the full name is **Crime Mapping Mobile Application** (`public/manifest.json`). The in-app theme name is **Crime Map** (`src/lib/theme.js`). The npm package name is `client` at version `0.3.2` (`package.json`).

Provenance of the names: **Implemented** in those files. **Documented** title: README heading "Crime Mapping Web Application".

This repository is the React source for the mobile reporting client. It is not the marketing site, the CodeIgniter admin, or the MySQL API. Those live in `git@bitbucket.org:overdrive/crimemapping_website.git`, documented in Silicon Ark as `crimemapping_website`. That tree commits a production build under `app.crimemapping.co.za/` and states that the React source was not in that repository. This repository is that source. Whether the committed build was produced from `5927ab4` is **Unknown / Requires Confirmation**.

## Objectives

No project-plan file in this repository states objectives. The following are taken from the README title, the screens, and the API calls:

1. Give a signed-in person a phone-width web app for reporting a crime. **Inferred** from the 400px layout, the manifest, and the home action "Report a Crime".
2. Sign in with a cellphone and password, and register a user against an organisation. **Implemented** in `Login.js`, `Signup.js`, and `AuthContext.js`.
3. Capture a crime with a date and time, one or more incident types, notes, a map position, an address, and photos, and post it to an HTTP API. **Implemented** in `CreateEvent.js` and `DatastoreContext.js`.
4. Install and cache the app as a progressive web app. **Implemented** in `manifest.json`, `src/index.js`, and `public/index.html`. The two service-worker registrations do not use the same file name. See technical documentation.

Whether these are the approved product goals is **Unknown / Requires Confirmation**.

## Branch reality

| Line | Tip | Date | What it is |
|---|---|---|---|
| `master` (default; `origin/HEAD`) | `5927ab4` | 2023-12-06 | The only branch. CRA client, API auth, crime report form, unused Firestore review screens |

History runs from `c4fa285` (2022-11-21, "Initial commit") through `5927ab4`. Authors in the log: HeinLie, Jaco Brits, JacquesOverdrive. No commits after 2023-12-06. Whether any deployed site still serves a build of this tree is **Unknown / Requires Confirmation**.

Observable milestones from commit subjects (not a written plan):

| Commit | Date | Author | Subject |
|---|---|---|---|
| `c4fa285` / `54d4cfc` | 2022-11-21 | Jaco Brits | Initial commit; "v0.3.0 source code" |
| `24c48d1` / `566aa8f` | 2022-11-30 | Jaco Brits | Bitbucket Pipelines and `sonar-project.properties` |
| `79ceda6` | 2022-12-13 | Jaco Brits | "New chanes from paul" |
| `5d9e8a6` | 2023-02-08 | HeinLie | Added Google Maps API |
| `26ee9ca` | 2023-02-13 | HeinLie | Signup done |
| `c0691db` | 2023-02-20 | HeinLie | Initial commits (auth persistence and file uploads are nearby on 2023-02-22) |
| `b4934ca`–`048f707` | 2023-03-01–02 | Jaco Brits | Pipeline and build-script edits |
| `bc0c4df` | 2023-03-03 | Jaco Brits | "Removed firebase" |
| `71330c2` | 2023-03-27 | HeinLie | Signup fixes, geolocation package, number verification |
| `2119323` | 2023-04-24 | HeinLie | "remove review crimes." |
| `5a8a01c` / `770e79d` | 2023-05-10–11 | HeinLie | Auth fix; null fix |
| `2cb33e2` | 2023-07-20 | JacquesOverdrive | Update icons |
| `5927ab4` | 2023-12-06 | JacquesOverdrive | update |

Intermediate diffs were not reviewed commit by commit. Provenance: **Implemented** (git history).

## Scope in the repository

In scope of what is on `master`:

- Create React App client (`react-scripts` 5, React 18) with public auth screens and a private home plus crime-report screen.
- Calls to `REACT_APP_PUBLIC_API_URL` for users, organisations, incidents, and crime create. The API implementation is not in this repository.
- Google Maps via `@react-google-maps/api` and reverse geocoding via `react-geocode`, using `REACT_APP_GOOGLE_API_KEY`.
- A phone-width layout (`maxWidth: 400px`) and a PWA manifest.
- Bitbucket Pipelines: `yarn` build, then FTP upload of `build/` with `ncftp`. A SonarQube step is defined and is not referenced by `pipelines.default`.
- Firebase hosting files (`.firebaserc` project `crime-mapping-org`, `firebase.json`) and a README that still describes Firebase deploy. `src/lib/firebase-config.js` has empty config strings after the "Removed firebase" commit.

Out of scope of the code that was found, or not present as a working route:

- The CodeIgniter admin, MySQL schema, and marketing site (`crimemapping_website`).
- Routes `/all-crimes`, `/view-crime`, and `/debug`. The page files exist. The route elements in `PrivateRoutes.js` are commented out. The home "Review Crimes" button is commented out.
- A native iOS or Android project. The manifest calls the app a mobile application. The implementation is a website.
- Automated tests that exercise the product. `src/components/App.test.js` looks for the Create React App sample text "learn react", which this app does not render.
- The scan-host file `sonarqube_scan.bat`.

## System architecture

```text
Browser (phone-width layout, max 400px)
  → https://app.crimemapping.co.za/     (PUBLIC_URL in the production build script)
       Public routes: /login, /signup, /forgot-password, /unauth
       Private routes: /, /report-crime

React client (this repository)
  → REACT_APP_PUBLIC_API_URL
       POST /apiusers/login
       POST /apiusers/create
       GET  /apiorganisations
       POST /apiusers/logout          (Bearer)
       POST /apiusers/getUser         (Bearer)
       GET  /apiusers/{id}            (Bearer)
       GET  /apiincidents             (Bearer)
       POST /apicrimes/create         (Bearer, multipart)
  → Google Maps JavaScript API and Geocoding (REACT_APP_GOOGLE_API_KEY)
  → navigator.geolocation

Bitbucket Pipelines (node:lts), default pipeline
  → yarn && yarn build
  → ncftpput of build/* to $FTP_HOST $FTP_SITE_ROOT_DEV

Firebase project crime-mapping-org
  → firebase.json hosting of build/ with SPA rewrite
  → not the pipeline's deploy step
```

The sibling repository's committed app `.env` sets `REACT_APP_PUBLIC_API_URL` to `https://admin.crimemapping.co.za/public`, and its built bundle hardcodes that host. This source reads the variable and does not hardcode the host. Whether production was built from this variable or from a later hardcoded bundle is **Unknown / Requires Confirmation**.

Hosting product, FTP site root, and whether `app.crimemapping.co.za` is still this app were not in this repository. **Unknown / Requires Confirmation.**

## Major components

| Component | Path | Role |
|---|---|---|
| App shell | `src/components/App.js`, `src/index.js` | Auth gate, router, Bootstrap, service worker |
| Public screens | `src/pages/public/` | Login, signup, forgot password, unauthorised redirect |
| Private screens | `src/pages/private/` | Home, create crime; review, view, and debug files are unrouted |
| Auth | `src/Context/AuthContext.js` | Cellphone login, signup, logout, session restore |
| API datastore | `src/Context/DatastoreContext.js` | User row, incident list, crime create |
| Firestore leftover | `src/Context/FirestoreContext.js` | CRUD and Storage helpers. Provider is not mounted |
| Map | `src/components/MapView/MapMain.js` | Google Map and draggable centre marker |
| Crime catalogue (old) | `src/lib/EventConfig.js` | 25 hardcoded crime labels. Used by the unrouted review accordion |
| Roles and org (old) | `src/lib/appConfig.js` | Field Operator, Data Manager, Silicon Overdrive. Used only by unrouted Debug |
| Pipeline | `bitbucket-pipelines.yml` | Build and FTP |
| Hosting leftovers | `firebase.json`, `.firebaserc` | Firebase Hosting project `crime-mapping-org` |

## Milestones visible in git

No milestone document exists. The history supports this sequence. Provenance: **Inferred** from commit subjects and dates.

1. 2022-11-21 — client imported at a version message "v0.3.0". `package.json` is now `0.3.2`.
2. 2022-11-30 — pipeline and SonarQube properties added.
3. 2023-02 — Google Maps, signup, auth persistence, and file uploads.
4. 2023-03-03 — Firebase client config cleared. Firebase files and the README were left in place.
5. 2023-03-27 — geolocation and phone-number handling.
6. 2023-04-24 — review-crimes entry removed from the live UI.
7. 2023-05 — auth and null fixes.
8. 2023-07-20 and 2023-12-06 — icon and unspecified "update" commits. Diffs were not expanded.

## Implementation plan

There is no forward plan, TODO list, or ticket link in this repository. The README's development section is the Create React App script help, plus Firebase setup that the current `firebase-config.js` does not read.

## Known dependencies

- Node toolchain via `react-scripts` 5. Pipeline image `node:lts`. Local Node version is not pinned.
- React 18, React Router 6, React Bootstrap 5, `react-rainbow-components`, `react-select`.
- `axios` for the HTTP API.
- `@react-google-maps/api` and `react-geocode`.
- `firebase` 9 remains in `package.json`. The initialised config object is empty strings.
- `uuid` is imported by `CreateEvent.js` and `AllEvents.js` and is not listed in `package.json`.
- Build-time variables `REACT_APP_PUBLIC_API_URL` and `REACT_APP_GOOGLE_API_KEY`. Not committed (`.env` is gitignored).
- Pipeline secrets `FTP_USERNAME`, `FTP_PASSWORD`, `FTP_HOST`, `FTP_SITE_ROOT_DEV`. Sonar variables `SONAR_HOST_URL` and `SONAR_TOKEN` are referenced only by the unused step.
- Production `PUBLIC_URL` `https://app.crimemapping.co.za/` in the `build` script.

## Current project status

**Implemented** on the live routes: signup, login, logout, session token in `localStorage`, home, and crime report with map, incidents, notes, and photos.

**Present but not routed:** review list, single-event view, debug screen, Firestore provider, hardcoded `EventConfig` crimes, `appConfig` roles.

**Stale relative to the code:** README Firebase env vars and `npm run deploy` (the script that exists is `deploy:dev`). `fb:logout` runs `firebase login`. `firebase-config.js` does not read `REACT_APP_FB_*`.

**Last commit:** 2023-12-06. No open branch besides `master`.

## Human confirmation

- Whether `5927ab4` is what `https://app.crimemapping.co.za/` serves, or whether the build inside `crimemapping_website` is the live client.
- The production value of `REACT_APP_PUBLIC_API_URL` and `REACT_APP_GOOGLE_API_KEY`.
- Whether FTP (`FTP_SITE_ROOT_DEV`) or Firebase project `crime-mapping-org` is the host that should receive new builds.
- Whether Field Operator (1) and Data Manager (2) in `appConfig.js` are still real roles. The admin seed in `crimemapping_website` names role id 1 "Developer" and treats role id 4 as organisation-scoped.
- Whether public signup is allowed. This client calls `POST /apiusers/create` with no bearer token. The admin API notes say user create sits behind JWT.
- Whether the review, merge, and Firestore event model should stay in the tree.
- A commented line in `CreateEvent.js` contains a Google API key literal. The value is not copied here. Confirm whether that key is still valid and should be removed from git history.