# Project plan — gsa

Evidence date: 2026-10-13.

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

Inspected revision: `master` at `ebb9cca93051bcd23a569d2b0a243a8d465bb740` (2020-08-26 16:51:40 +0200, "Email validation, email excel export, contract history display issues"). The scan-host path `~/projects/sonar_scan/repos/gsa` was not on this machine. The tree was read from a clone of that revision. Committed database passwords in `include/system.inc.php` and `include/systemLive.inc.php` are named by file and are not reproduced.

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

## Product

The page title and home heading are **GSA**. The footer reads `GSA System [v0.0A, 2008]`. The login image alt text is **The GSA**. Email copy in `cron.daily.php` calls the monthly mail "The GSA Star (selling travel action report)" and names addresses at `thegsa.co.za` and `the-gsa.co.za`.

The runnable application is a PHP server-rendered system for magazine advertising. Staff keep advertisers (companies), contacts, sales people, and advertising contracts. A contract is a booking in a publication for a position, size, colour, and shape, split into monthly contract items. Staff log calls, produce operational reports, and generate renewal documents and PDFs.

Provenance: **Implemented Behaviour**, except the footer version string, which is **Documented** in `include/version.inc.php`.

There is no README, product requirements document, project plan, or feature list in the source repository. Silicon Ark had no `gsa/` directory before this onboarding.

### Related Silicon Ark project

Silicon Ark already contains documentation for **`thegsa`** (`silicon_ark/thegsa/`), sourced from `git@bitbucket.org:overdrive/thegsa.git` at a 2025 revision. That product shares branding, cookie name, table names, and screen structure with this repository. Whether `gsa` is an older snapshot, a sibling deploy, or a superseded line is **Unknown / Requires Confirmation**. This onboarding documents **this** repository only.

## Objectives visible in the code

These are inferred from what the code does, not from a written goal statement.

1. Record advertisers, their contacts, and the sales person responsible for them.
2. Record advertising contracts against a publication, with position, size, colour, shape, amount, discount, payment type, and a run of monthly items.
3. Mark contract items cancelled, skipped, or given an update label, and keep a per-item amount.
4. Log contact activity (type, status, discussion, action, follow-up date, linked publications, optional contract).
5. Restrict who may see and change each screen, and which sales people a user may edit.
6. Produce planning, invoice, cancellation, move, prospect, commission, expiry, contact, spend, income, follow-up, totals, and advert-update reports.
7. Build renewal documents and a renewal PDF.
8. Send a monthly STAR newsletter for publications flagged `blnSTAR`. That script exits before any mail is sent (`die("site inactive 20180108")`).

## Scope

### In the repository

- Root PHP pages for login, home, advertisers, contacts, contact logs, contracts, search, reports, lookups, renewal documents, and imports.
- Domain classes under `include/` and report classes under `include/reports/`.
- SQL builders in `include/database/sql.inc.php`.
- MySQL access in `include/database/mysql.cls.php`.
- Mail class `_nemo.email.gsa.cls.php` and the `include/mailer/` MIME/SMTP library.
- PDF via bundled FPDF (`include/fpdf.php`, `include/reports/fpdf.php`, `htmltopdf2/`), mPDF (`mpdf/`, `include/mpdf/`), and Dompdf (`dompdf/`). There is no root `composer.json`.
- Lookup maintenance pages (branch, colour, magazine, payment type, position, sales person, shape, size, statuses, title, update label, user, email template).
- `cron.daily.php` for the STAR newsletter.
- `ximport.php` and `zimport.php` one-off data loaders.
- Bundled MySQLDumper under `mysqldumper/`.
- A committed SQL dump `db/gsa_20200811.sql` and a zip `data.thegsa.co.za.zip`.
- Files under `uploads/`.

### Out of scope of this repository

- The live menu labels and security rows. They live in MySQL (`tblmenulevel0`, `tblmenulevel1`, `tblSecurity`, `tblSecurityItem`) and are not defined as application code; a dump snapshot exists in `db/gsa_20200811.sql`.
- Hosting, DNS, and the cron schedule that would call `cron.daily.php`.
- Whether `gsa` on `localhost` is the database this revision is meant to use in production (a dump header names `thegsegszw_db6` on `dedi483.jnb2.host-h.net`).
- CI / SonarQube — this repository has no `bitbucket-pipelines.yml` or `sonar-project.properties`.

## System architecture

Server-rendered PHP. Each screen is a root script. It includes `include/system.inc.php`, checks the `ckyGSA` cookie (except login, the STAR cron, several report entry scripts with `checkLogin` commented out, the import scripts, and `renewalpdf.php`), then switches on `act` and prints HTML.

```text
include/header.inc.php
  title GSA, styles, jquery.js
include/menu.inc.php
  menu from tblSecurity for the cookie user
include/footer.inc.php
      ^
page script (advertiser.php, contract.php, ...)
  include/*.cls.php
      ^
include/system.inc.php
  copy GET/POST/COOKIE into globals
  open MySQL
  checkLogin / getAccess
      ^
include/database/mysql.cls.php
include/database/sql.inc.php
```

There is no router, no front controller, no Composer autoload at the application root, and no test suite. `index.php` is the post-login home. It prints the heading "GSA" and the menu.

An alternate bootstrap `include/systemLive.inc.php` also targets database `gsa` on `localhost`, with a shorter cookie lifetime (3600 seconds vs 3600000 in `system.inc.php`). Root pages include `system.inc.php`. Which file production uses is **Unknown / Requires Confirmation**.

## Major components

| Component | Role | Evidence |
|---|---|---|
| Session cookie | `ckyGSA` holds `UserID\|username` | `login.php`, `checkLogin` in `include/system.inc.php` |
| Advertiser | Company record, contacts, contract history | `advertiser.php`, `include/advertiser.cls.php`, `tblCompany` |
| Contact | Person at an advertiser, default flag, subscribe status | `contact.php`, `include/contact.cls.php`, `tblContact` |
| Contact log | Call or meeting, follow-up, linked magazines | `contactlog.php`, `include/contactlog.cls.php` |
| Contract | Booking header plus monthly items | `contract.php`, `include/contract.cls.php`, `include/contractitem.cls.php` |
| Search | Company search that reuses contact editing | `search.php`, `include/search.cls.php` |
| Reports | Console plus one script per report | `reports.php`, `include/reports/` |
| Renewal | HTML renewal document and FPDF output | `renewaldoc.php`, `renewalpdf.php` |
| Lookups | CRUD pages for reference data | `branch.php`, `magazine.php`, and the other lookup scripts |
| Users | Login account, menu access, sales-person links | `user.php`, `include/user.cls.php` |
| STAR mail | Monthly newsletter, currently aborted | `cron.daily.php` |
| Imports | Unauthenticated bulk loaders | `ximport.php`, `zimport.php` |

## Milestones and implementation plan

No roadmap, milestone list, or implementation plan exists in the repository.

Git history in this clone has two commits:

| Commit | Date | Message |
|---|---|---|
| `a8ad56d` | (first commit on `master`) | First Commit |
| `ebb9cca` | 2020-08-26 | Email validation, email excel export, contract history display issues |

The tip commit touches advertiser/contact/contract display and several report classes (email validation / Excel export / contract history display). Earlier history beyond these two commits is **Unknown** in this clone.

## Known dependencies

| Dependency | Role | Evidence |
|---|---|---|
| PHP with mysqli | Runtime | `include/database/mysql.cls.php` |
| MySQL | Data store | `system.inc.php` / dump |
| jQuery | Client scripts | `jquery.js`, `include/header.inc.php` |
| FPDF / HTML2FPDF | Report and renewal PDFs | `include/fpdf.php`, `include/reports/fpdf.php` |
| Dompdf (vendored) | Present; usage in spend/income reports is commented | `dompdf/` |
| mPDF (vendored) | Present under `mpdf/` and `include/mpdf/` | tree |
| PHP `mail()` | Outbound mail via `NemoEmail` | `_nemo.email.gsa.cls.php` |
| MySQLDumper | Bundled DB admin tool | `mysqldumper/` |

## Current project status

**Inferred** from evidence:

- The application code is present and coherent as a staff CRM for advertising bookings.
- Last git activity on the inspected tip is 2020-08-26.
- STAR newsletter code is hard-stopped since 2018-01-08.
- Several report entry scripts and `renewalpdf.php` / imports leave `checkLogin()` commented out.
- No CI configuration is committed.
- Relationship to the later `thegsa` repository and whether this line is still deployed: **Unknown / Requires Confirmation**.