chore: update documentation

docs/DATA_RESET.md

@@ -12,4 +12,4 @@ Use this on local, or on staging if you're unfamiliar with Ansible.
  - And `chmod 775 .env`
 
  - Reseed with `php artisan migrate:refresh --seed`
- - Run tests with `phpunit`
+ - Run tests with `./vendor/bin/phpunit`

docs/DEPLOYMENT.md

@@ -1,35 +1,113 @@
 ## Physical server set up
 
-We have two Rocky linux virtual machines in a Digital Ocean cluster. The machines have their packages updated monthly.
+We have two droplet virtual machines at [Digital Ocean](https://cloud.digitalocean.com).
+
+They exist at in LON1 for easier GDPR compliance in regard to domestic data storage.
+
+They are configured with the following Digital Ocean hardware parameters:
 
 ### Staging
 
-Basic / 4 GB / 2 vCPUs / 80Gb / $24.00 per month
+Basic / 4 GB / 2 "regular" Intel vCPUs / 50Gb SSD / 4TB transfer @ $24.00 per month
 
 ### Live
 
-8 GB / 4 vCPUs / 160Gb / $48.00 per month
+Basic / 8 GB / 4 "Premium" Intel vCPUs / 160Gb SSD / 5TB transfer @ $56.00 per month
+
+### Networking
+
+The Machines each have virtual NICs with an internal IP4 address and an internet facing static IP4 address. These addresses are supplied by Digital Ocean. 
+
+Firewalling is provided via the OS firewall.
+
+Access is via keyed SSH with restricted IP.
+
+## OS Platform
+
+Both virtual machines have [Rocky linux](https://rockylinux.org/) (v9.x) and have identical baseline configurations, regardless of underlying hardware.
+
+The machines have their packages updated monthly using the OS update facility (DNF) and so a fresh install of the current 9.x should be fine.
 
 ## Software stacks
 
 The staging server was hand rolled to provide the LAMP stack below. Live was a VM clone of staging. These have been live since March 2023 so may have some package drift.
 
+### Apache Web Server
+
 ```
 [neontribe@rocky9-arc-staging ~]$ apachectl -v
-Server version: Apache/2.4.57 (Rocky Linux)
-Server built:   Jul 20 2023 00:00:00
-[neontribe@rocky9-arc-staging ~]$  php-cgi -v
-PHP 8.1.26 (cgi-fcgi) (built: Nov 21 2023 21:53:48)
+Server version: Apache/2.4.62 (Rocky Linux)
+Server built:   Aug  3 2024 00:00:00
+```
+
+Apache binds multiple virtual hosts:
+
+Staging:
+- voucher-store.alexandrarose.org.uk
+- voucher-admin.alexandrarose.org.uk
+
+Live:
+- voucher-store.alexandrarose.org.uk
+- voucher-admin.alexandrarose.org.uk
+
+
+The application can disambiguate requests for the web route based on the request parameters.
+
+### PHP 
+
+```
+[neontribe@rocky9-arc-staging ~]$  php-fpm -v
+PHP 8.1.31 (fpm-fcgi) (built: Nov 19 2024 15:24:51)
 Copyright (c) The PHP Group
-Zend Engine v4.1.26, Copyright (c) Zend Technologies
-    with Zend OPcache v8.1.26, Copyright (c), by Zend Technologies
+Zend Engine v4.1.31, Copyright (c) Zend Technologies
+    with Zend OPcache v8.1.31, Copyright (c), by Zend Technologies
+```
+
+PHP has the following modules enabled:
+
+|              |              |              |              |
+|--------------|--------------|--------------|--------------|
+| bcmath       | bz2          | calendar     | core         |
+| ctype        | curl         | date         | dom          |
+| exif         | fileinfo     | filter       | ftp          |
+| gd           | gettext      | hash         | iconv        |
+| intl         | json         | libxml       | mbstring     |
+| mysqli       | mysqlnd      | openssl      | pcntl        |
+| pcre         | PDO          | pdo_mysql    | pdo_sqlite   |
+| Phar         | posix        | readline     | Reflection   |
+| session      | shmop        | SimpleXML    | sockets      |
+| sodium       | SPL          | sqlite3      | standard     |
+| sync         | sysvmsg      | sysvsem      | sysvshm      |
+| tokenizer    | wddx         | xml          | xmlreader    |
+| xmlrpc       | xmlwriter    | xsl          | Zend OPcache |
+| zip          | zlib         |
+
+### MySQL
+
+```
 [neontribe@rocky9-arc-staging ~]$ mysqld -V
-/usr/libexec/mysqld  Ver 8.0.32 for Linux on x86_64 (Source distribution)
+mysql  Ver 8.0.36 for Linux on x86_64 (Source distribution)
 ```
 
-The ARC service comprises two server applications and one Vue.js single page app.
+### Application
+
+The ARC service comprises 
 
-The server applications are both served from a single Laravel stack, switched on virtual host by Laravel. These persist shared data into a mysql server. The raw mysql files for this instance are:
+* A statically built and served [VueJS](https://v2.vuejs.org/) 2.x PWA Trader application:
+
+    - that installs on the user's device where it can
+    - manages the redemption and reconciliation of trader's voucher transactions 
+    - uses the Laravel instance as REST API to read/write data.
+
+
+* A Laravel application that serves:
+
+    - a portal for administration of the entities (vouchers / centres/ areas / markets and various user accounts) in the service
+    - a portal for the management of voucher distribution at children's centres
+    - a REST API to serve the user authentication needs and fulfil requests from the trader application
+    - persist shared data into a mysql server.
+
+The raw mysql files for this instance are:
 
 ```
 [root@rocky9-arc-staging mysql]# du -sh .
@@ -38,13 +116,9 @@ The server applications are both served from a single Laravel stack, switched on
 
 ```
 [root@Arc-live-04-2023 mysql]# du -sh .
-20G     .
+5.1G     .
 ```
 
-The Vue.js (2.x) single page application is served as statically built files that are served by the Apache instance via virtual host named switching. This app uses the Laravel instance as REST API to read/write data and carry out operations requested by the user.
-
-The Vue.js application may be optionally persisted on phones that support the progressive web app conventions. It uses a service worker to cache locally and fetch new variations from the server when it sees them.
-
 ## Service Interaction
 
 Defined in [server-components.puml](images/server-components.puml)
@@ -53,6 +127,8 @@ Defined in [server-components.puml](images/server-components.puml)
 
 ## SupervisorD and CronD managed processes
 
-The system uses [Supervisord](http://supervisord.org/) to run a database backed queue worker with responsibilities like processing long-running tasks like fetching voucher histories.
+The system uses [Supervisord](http://supervisord.org/) to run an instance of the Laravel application as a database backed queue worker with responsibilities like processing long-running tasks like fetching voucher histories.
+
+It is important to remember to reload this after a code change, as it will maintain the loaded classes in memory and fail to pickup changes.
 
-There is a cron job that is run very frequently to execute Laravel's internal [task scheduling system](../app/Console/Kernel.php)  
+There is a cron job (`/etc/cron.d/laravel`) that is run very frequently (every minute) to execute Laravel's internal [task scheduling system](../app/Console/Kernel.php).

docs/JS_UPGRADE.md

@@ -2,7 +2,7 @@
 
 You can use `npm` to check this:
 
-Check outpdated
+Check outdated
 
 ```bash
 npm outdated

docs/README.md

@@ -1,7 +1,7 @@
 # ARCV Service
 
 ## About ARC Voucher Service/API
-ARCV Service is the service portal and API for ARCV Market.
+ARCV Service is the service portal and API for the ARCV Market trader app.
 
 ## Docker and containers
 
@@ -11,7 +11,7 @@ The service, market and store can be deployed, run locally for training/testing
 
 1. Clone the repo
 2. Create a database and user (homestead, sqlite or mysql)
-3. If not using [Homestead](https://laravel.com/docs/6.x/homestead) or Valet - you will need to configure permissions on `storage` and `bootstrap/cache`. See [Laravel 6.x Installation](https://laravel.com/docs/6.x) for more info.
+3. If not using [Homestead](https://laravel.com/docs/9.x/homestead) or Valet - you will need to configure permissions on `storage` and `bootstrap/cache`. See [Laravel 9.x Installation](https://laravel.com/docs/9.x) for more info.
 4. Copy `.env.example` to `.env` and edit to local settings
 5. `composer install`
 6. `php artisan key:generate`
@@ -36,4 +36,4 @@ We suggest that you use the TLD `.test` as others, like `.app` may now be in the
  * [MVL exports](MVL-EXPORT.md), monthly/yearly voucher export
  * [Creating test vouchers](TEST_VOUCHERS.md) in bulk
  * [Setting up reporting](REPORTING.md)
- * [Styling](STYLING.md)
+ * [Styling](STYLING.md)