# Project plan — silicon_security

Evidence date: 2026-10-03.

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

Inspected revision: `main` at `514489afb1f349d985a7fa24ef2ca9a2ccaab928` (2025-12-15, jacobrits1, "Add Git workflow and browser testing requirements to project rules"). The scan-host path `~/projects/sonar_scan/repos/silicon_security` was not on this machine. The tree was read from a shallow clone of that tip. Credential values are omitted.

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

## Product

The repository is published as **silicon_security**. The application describes itself as **Admin Overdrive**.

| Source | What it calls the product |
|---|---|
| `composer.json` `name` | `codeigniter4/adminstarter` |
| `composer.json` `description` | Admin Overdrive |
| `composer.json` `homepage` | `https://www.overdrive.co.za` |
| `docs/README.md` title | Admin Overdrive Starter |
| `overview.md` | Admin Overdrive, hosted by Overdrive |
| `sonar-project.properties` `sonar.projectKey` | `overdrive_admin-overdrive-v2_…` |
| `docs/EMAIL_QUEUE_AND_CRON_SETUP.md` | Example cron URL uses path prefix `/dms/` |

**Documented** in those files. **Requires confirmation:** whether `silicon_security` is a dedicated deployment of Admin Overdrive, a DMS-only fork, or a scan copy of `admin-overdrive-v2`. No statement in the repository explains the repository name.

The behaviour that is actually wired in this tree is a CodeIgniter 4 admin application whose newer work is a document management system (upload, OCR, search, role-based access, time-limited sharing) plus a chat interface that uses OpenAI and a retrieval-augmented index. Older Admin Overdrive surfaces (orders, invoices, products, labels, fault finder, SOAP and REST order confirmation) remain as routes, views, helpers, and XML samples. Several of those routes have no controller in this tree.

There is no prior Silicon Ark set for this repository. Source documentation that was incorporated, not replaced, lives under `docs/`, `scope/`, and `overview.md`.

## Branch reality

Only `main` was inspected, at the tip above. History before that commit was not retrieved (shallow clone). The tip changes project rules (git workflow and browser testing), matching the task-creation note.

`docs/CHANGELOG.md` and `docs/README.md` record feature work dated 2025-11-07 (DMS and configuration fixes) and undated `2025-01-XX` entries (viewer profile, JavaScript null checks). `docs/CHAT_SECURITY_AUDIT.md` is dated 2025-11-11. Those dates are **Documented** in those files. They were not re-verified against full git history.

**Discrepancy.** The task-creation file list included `sonarqube_scan.bat` at the repository root. That file is not in this checkout of `514489a`. `sonar-project.properties` and `bitbucket-pipelines.yml` are present. Whether the batch file was untracked on the scan host is **Unknown**.

## Objectives

Recovered from `docs/README.md`, `scope/Task_viewer_user_profile.md`, and the implementation. Not from a written roadmap inside this repository.

- Provide a logged-in admin shell: users, roles, menu permissions, system settings, media files, and developer tools (menu management, CRUD generator). **Implemented** and **Documented** in the README feature list and menu seeder.
- Store and search documents of types Legislation, Labels, and Minutes, with OCR text and an optional semantic index. **Documented** in the README and changelog. **Implemented** in `app/Controllers/Documents.php` and `app/Neuron/DocumentRAG.php`.
- Let System Admin and System User accounts share documents with a viewer under a time limit, a login-active window, or permanent access. **Documented** in `scope/Task_viewer_user_profile.md`. **Implemented** in `app/Models/UserDocumentModel.php`.
- Answer questions over documents through a chat that keeps conversation memory. **Documented** in `docs/IMPLEMENTATION_SUMMARY.md`. **Implemented** in `app/Controllers/Chat.php`.
- Queue outbound email and send it from a cron HTTP endpoint. **Documented** in `docs/EMAIL_QUEUE_AND_CRON_SETUP.md`. **Implemented** in `app/Controllers/CronJobs.php`.

`docs/README.md` points operators at a Jira board (`siliconsoftware.atlassian.net`, project `SI`, board `12`) and a Confluence space `AO`. Those sites were not opened. Whether they are still the planning system is **Unknown / Requires Confirmation**.

## Scope

### In this repository

- CodeIgniter 4 application under `app/`, web root `public/`, CLI entry `spark`.
- MySQL/MySQLi as the default application database (`app/Config/Database.php`). PHPUnit uses SQLite in memory.
- Session login, email 2FA, blocked-IP check, menu authorisation, and a time-window filter on `documents*`.
- Document upload (PDF, JPG, JPEG, PNG), OCR, database search, RAG index, categories, audit log, download, and viewer sharing.
- Chat with OpenAI, embeddings, and a selectable vector store (memory, MySQL, or Pinecone).
- Email templates, sent queue, login history, blocked list, cron actions, general settings, ChatGPT settings, public holidays.
- Server usage monitor (`php spark monitor:system` and `monitoring` routes).
- SonarQube scan on `main` via Bitbucket Pipelines. The pipeline does not deploy the application.

### Present as leftovers, not as a complete feature

Routes in `app/Config/Routes.php` name controllers that are not in `app/Controllers/`:

`Products`, `LabelStatus`, `GetXMLData`, `Orders`, `LabelUserGroups`, `LabelEmailTemplates`, `Company`, `FaultFinder`, `StoreApiController`.

`app/Controllers/Reports.php` renders `reports/reportsList` and imports `OrdersModel`, `InvoicesModel`, and `ProductsModel`. Those model files are not in `app/Models/`. Views under `app/Views/reports/` still describe orders and invoices. `writable/` contains sample order and invoice XML (M2North, PnP Godrej, TAF). A `$routes->resource('organisations')` entry has no `Organisations` controller.

Provenance: **Implemented** as registered routes and views. The missing classes are **not implemented** in this tree. Whether removal was intentional is **Unknown / Requires Confirmation**.

`overview.md` infers AWS, PDF, Excel, and AI features from `composer.json`. AWS SDK, mPDF, and PhpSpreadsheet are required by Composer. No call sites for AWS, mPDF, or PhpSpreadsheet were found under `app/`. League CSV is used by `app/Controllers/Csv.php`. OpenAI is used. Provenance: dependency **Implemented** in Composer; application use of AWS, mPDF, and PhpSpreadsheet **not found**.

### Out of scope for this documentation set

- Changing the source repository.
- Deciding whether leftover order and invoice routes should be deleted or restored.
- Production hostnames, database names, and secret values.

## System architecture

```text
Browser
  → public/ (CodeIgniter 4)
      → Filters: isLoggedIn, isGranted, csrf on POST, timeAccess on documents*
      → Controllers (Welcome, Home, Users, Documents, Chat, SystemSettings, CronJobs, …)
      → Models → MySQL (MySQLi)
      → writable/uploads/documents for stored files
      → OpenAI (chat + embeddings) when OPENAI_API_KEY is set
      → Vector store: memory (default), MySQL VECTOR, or Pinecone
      → SMTP via email.* environment keys
      → Tesseract / pdftotext / pdftoppm for OCR (paths are configuration)
Cron caller (unauthenticated GET /cronJobs)
  → CronJobs reads cronjob_actions and sends queued mail
Bitbucket Pipelines on main
  → SonarQube scan only
```

Menu entries are data (`user_menu`, `user_menu_category`, `user_access`), not a hardcoded sidebar. `app/Views/layouts/sidebar.php` renders whatever the role is allowed to see.

## Major components

| Component | Location | Status |
|---|---|---|
| Login, 2FA, password reset, registration | `app/Controllers/Welcome.php` | Implemented |
| Users, roles, menu permissions, viewer profile | `app/Controllers/Users.php` | Implemented |
| Documents | `app/Controllers/Documents.php`, `app/Controllers/Admin/Documents.php` | Implemented |
| Chat and memory | `app/Controllers/Chat.php`, `app/Helpers/chat_memory_helper.php` | Implemented |
| RAG | `app/Neuron/DocumentRAG.php`, `app/Helpers/document_helper.php` | Implemented |
| OCR | `app/Libraries/OcrLibrary.php`, `app/Libraries/PdfTextExtractor.php` | Implemented |
| Email queue and cron | `app/Controllers/Email.php`, `app/Controllers/CronJobs.php`, `app/Helpers/mail_helper.php` | Implemented |
| System settings | `app/Controllers/SystemSettings.php` | Implemented |
| Server monitor | `app/Commands/MonitorSystemUsage.php`, `app/Controllers/ServerMonitoring.php` | Implemented |
| Orders, invoices, products, labels, fault finder | Routes and some views only | Incomplete in this tree |

## Milestones visible in documentation

No milestone plan is stored in the repository. The changelog is the closest record:

1. Admin starter baseline: users, menus, settings, cron, email templates (migrations from 2022-11 through 2024-10).
2. 2025-11-07 — DMS (documents, types, categories, tags, audit, time window, RAG, OCR) and CodeIgniter config fixes.
3. 2025-11-09 to 2025-11-10 — vector embeddings, chat memories, document contexts, email response fields (migration filenames).
4. Undated `2025-01-XX` changelog section — viewer profile and per-document access. The migration file is named `2025-01-15-100009_CreateUserDocumentsTable.php`. Whether that date or the November DMS date is the real sequence is **Requires Confirmation** (filenames and changelog dates disagree).
5. 2025-11-11 — chat conversation ownership checks (`docs/CHAT_SECURITY_AUDIT.md`).
6. 2025-12-15 — project-rule update at `514489a`.

## Implementation plan

There is no forward plan in the repository beyond the README line "Development TODOS" linking to Jira, and the scope document's out-of-scope list (no email on document assignment, no expiry notifications, no access analytics).

`scope/Task_viewer_user_profile.md` marks those three items **out of scope** for that task. Provenance: **Documented**. They are not implemented in the files read for this pass.

## Known dependencies

- PHP. Composer allows `^8.0`. `docs/README.md` says PHP 8.3 is required, with intl, mbstring, mysqlnd, json, xml, and libcurl if HTTP requests are used. **Discrepancy — Requires Confirmation.**
- `codeigniter4/framework` `^4.0`.
- `aws/aws-sdk-php`, `mpdf/mpdf`, `phpoffice/phpspreadsheet`, `league/csv`, `orhanerday/open-ai`, `neuron-core/neuron-ai`, `smalot/pdfparser`, `ext-simplexml`.
- External processes named in OCR and monitoring code: Tesseract, pdftotext, pdftoppm, and `top` (the monitor command). Availability on a given host is **Unknown**.
- OpenAI API. RAG indexing returns false when `OPENAI_API_KEY` is empty (`document_helper.php`).
- SMTP server from `email.SMTPHost` and related keys.
- MySQL. `MySQLVectorStore` comments say it expects MySQL 9.1.0+ native `VECTOR`. That version requirement is **Documented** in the class comment. It was not verified against a running server.
- SonarQube host and token as Bitbucket pipeline variables. The pipeline does not build or deploy the PHP app.

## Current project status

**Implemented and documented** as an Admin Overdrive / DMS codebase on `main`, last commit 2025-12-15. No release tag was inspected. No deployment pipeline beyond SonarQube was found. Production URL, database, and whether the seeded developer user is used outside local setup are **Unknown / Requires Confirmation**.

`overview.md` is a generic structure summary. It says the database is "likely MySQL". `app/Config/Database.php` sets `DBDriver` to `MySQLi`. Prefer the config file.

A filled `.env`, a file named `.env copy`, and `env` are in the tree. `.gitignore` does not ignore them. Values are not copied into Silicon Ark. **Human review required** before those files are treated as safe to keep in git.