# Q Tech Logistics Portal - Architecture

**Status:** Milestone 9 courses and materials implemented locally; client inputs and hosting validation pending
**Date:** 21 November 2026
**Target host:** Afrihost shared hosting  
**Target URL:** https://portal.qtechlogistics.co.za

## 1. System Design

    www.qtechlogistics.co.za
      Public Nuxt website
            |
            | Apply and Portal links
            v
    portal.qtechlogistics.co.za
      Laravel application
        /learner  Branded learner panel
        /admin    Staff administration panel
            |
            +-- MySQL database
            +-- Private file storage
            +-- Q Tech SMTP server

The portal remains separate from the Nuxt repository. This keeps the production website statically deployable while the portal uses Laravel sessions, server-side policies and private storage.

## 2. Technology Baseline

| Area | Decision |
|---|---|
| Application | Laravel monolith |
| Interface | Filament learner and administrator panels |
| Database | MySQL or hosting-compatible MariaDB |
| Authentication | Laravel sessions, email verification and password reset |
| Authorisation | Laravel policies and panel-access checks |
| Storage | Private Laravel local disk outside public access |
| Email | Authenticated Q Tech SMTP |
| Background work | Database queue through cron; synchronous email fallback |
| Deployment | Safest available Afrihost cPanel, Git, SSH or uploaded-build workflow |

The implemented baseline is Laravel 13.38.0 and Filament 5.10.3. Development uses PHP 8.4.14; the hosting minimum remains PHP 8.3. Dependency versions are locked in `composer.lock`. The application must use a security-supported combination and must not downgrade to an unsupported release merely to accommodate an outdated runtime.

## 3. Application Boundaries

### Public website

- Owns public company, service, course, contact and privacy content.
- Continues using Web3Forms for general enquiries and, until portal approval, applications.
- Links to the learner panel after launch and may pass a course slug.
- Does not store portal sessions or learner files.

### Learner panel

- Owns registration, profile, applications, documents, enrolments, materials, submissions and published results.
- Shows only records owned by the authenticated learner.
- Uses simplified Q Tech branding and learner-friendly navigation.

### Administrator panel

- Is restricted to Administrator users.
- Owns review, statuses, private notes, learner messages, document review, enrolments, materials, assessments and results.
- Supports manual capture of selected historical applications.
- Does not include multiple staff roles in the first release.

## 4. Routes

| Route | Access | Purpose |
|---|---|---|
| / | Public | Redirect to learner login or dashboard |
| /learner/register | Public | Learner registration |
| /learner/login | Public | Learner login |
| /learner | Learner | Dashboard |
| /learner/applications | Learner | Own application and status |
| /learner/documents | Learner | Own checklist and uploads |
| /learner/courses | Learner | Assigned materials |
| /learner/my-courses | Learner | Own course offers, enrolments and access windows |
| /admin/users | Administrator | Create and manage portal accounts, account types and email verification state |
| /learner/assessments | Learner | Submissions and published results |
| /admin/login | Public | Administrator login |
| /admin | Administrator | Administration dashboard |

Unknown course slugs must not create course records. When no valid course is supplied, the learner chooses from active courses.

## 5. Access Rules

| Capability | Learner | Administrator |
|---|:---:|:---:|
| Maintain own account | Yes | No |
| View and edit own draft application | Yes | Yes |
| View another learner's records | No | Yes |
| Change application status | No | Yes |
| Read private staff notes | No | Yes |
| Upload own requested documents | Yes | Yes |
| Review documents | No | Yes |
| Manage enrolments, materials and assessments | No | Yes |
| Submit own assessment work | Yes | No |
| Record and publish results | No | Yes |

Every protected route, query, Filament action and file download must enforce a server-side policy. Hiding interface controls is not sufficient authorisation.

## 6. Application States

    Draft -> Submitted -> Under Review -> Accepted
                                      -> Unsuccessful

- Learners may edit Draft applications.
- Submission records time and privacy-consent version.
- Submitted applications become read-only to learners.
- Status changes record the previous state, new state, administrator, time and optional learner message.
- Application acceptance does not grant course access. An administrator issues an enrolment offer, the named learner accepts it, and access then follows the active enrolment date window.

## 7. Initial Data Model

| Entity | Purpose |
|---|---|
| users | Login identity, role and verification state |
| learner_profiles | Learner contact and profile information |
| courses | Portal course catalogue with stable slugs |
| applications | Course application and admissions state |
| application_status_history | Status transitions and learner messages |
| application_notes | Private administrator notes |
| document_requirements | Global required or optional checklist |
| documents | Private file metadata and review state |
| document_versions | Immutable private upload versions and file metadata |
| enrolments | Course access for accepted learners |
| materials | Course learning files |
| assessments | Instructions and due dates |
| submissions | Learner work and receipt information |
| results | Score, outcome, feedback and publication state |
| notifications | In-portal messages |

Use internal numeric keys and non-sequential public identifiers for learner-facing routes and downloads. Store timestamps in UTC and display them in Africa/Johannesburg.

## 8. Private Files

- Store documents, materials and submissions outside the public web root.
- Generate random stored names and retain a sanitised display name as metadata.
- Serve files only through authenticated, authorised downloads.
- Reject executable content and MIME types that do not match approved types.
- Use PDF, JPEG and PNG as provisional document types; course materials and assessment submissions also provisionally allow office documents and text. The client and host must confirm types and limits.
- Keep prior upload versions private for replacement history; learners may download only the current version while administrators may retrieve retained versions when operationally required.
- Use an application-level provisional 5 MB limit that must not exceed the effective PHP and hosting limits.
- Do not activate production uploads until the checklist, consent, retention and deletion rules are approved.

## 9. Security

- Require email verification before application submission.
- Use secure, HTTP-only, same-site cookies over HTTPS.
- Regenerate sessions after login and invalidate them after password reset.
- Rate-limit registration, login, reset and upload actions.
- Apply CSRF protection to state-changing requests.
- Prevent public administrator registration.
- Restrict user-account administration to administrators, display learner and administrator account types, prevent self-unverification and do not expose account deletion in the management screen.
- Group learner navigation into Admissions, My learning and Assessments without changing route or ownership boundaries.
- Create administrator-selected learner or administrator accounts with random private credentials and panel-specific password-setup links; create learner profiles and document checklists only for learner accounts.
- Keep application keys and database and SMTP credentials outside source control and public access.
- Disable debug output in production.
- Do not write passwords, document contents or unnecessary personal information to logs.

## 10. Email

Send from no-reply@qtechlogistics.co.za and use admissions@qtechlogistics.co.za as the operational reply address where appropriate.

| Event | Learner | Administrator |
|---|---|---|
| Verification | Verification link | None |
| Application submitted | Confirmation and reference | New-application alert |
| Status changed | Status and approved message | In-portal confirmation |
| Document requested or reviewed | Checklist notification | In-portal confirmation |
| Assessment submitted | Receipt | New-submission alert |
| Result published | Availability notice | In-portal confirmation |
| Password reset | Reset link | None |

Store the business action before sending email. A mail failure must be logged and retried or clearly reported without losing the application or status change.

## 11. Historical Applications

- The client selects active applications for capture.
- An administrator creates the learner and application through the validated admin workflow.
- The record notes that it was manually migrated and stores the original received date when known.
- The administrator decides whether to send account activation.
- Attachments are not imported from email automatically.
- CSV import and mailbox integration remain out of scope.

## 12. Afrihost Readiness Checklist

Production deployment must not begin until all mandatory account-specific items are verified. The project owner authorised local Milestones 6-8 before those hosting checks were complete.

| Check | Requirement | Evidence | Status |
|---|---|---|---|
| PHP | PHP 8.3+ and supported Laravel/Filament versions | cPanel runtime view | Not verified |
| Extensions | Ctype, cURL, DOM, Fileinfo, Filter, Hash, Mbstring, OpenSSL, PCRE, PDO MySQL, Session, Tokenizer, XML | Host confirmation or PHP information page | Not verified |
| Database | MySQL/MariaDB database and least-privilege user | cPanel database view | Not verified |
| DNS | portal.qtechlogistics.co.za resolves to the intended host | Public DNS query on 21 October 2026 | Verified - 197.242.159.145 |
| Web server | Portal hostname reaches the Afrihost web server | HTTP response on 21 October 2026 | Verified - LiteSpeed placeholder |
| Subdomain root | Dedicated document root for portal.qtechlogistics.co.za | Domains configuration | Not verified |
| HTTPS | Valid certificate and forced HTTPS | Browser and panel verification | Not verified |
| Web root | Points to Laravel's public directory | Document-root inspection | Not verified |
| Storage | Writable framework directories and private non-public files | Permission and direct-URL test | Not verified |
| Uploads | Adequate quota and configurable PHP upload limits | PHP configuration and quota | Not verified |
| Cron | Scheduler and queue-processing commands supported | cPanel Cron Jobs | Not verified |
| SMTP | Authenticated outbound Q Tech SMTP connection | Test message | Not verified |
| Deployment | Git, SSH/Composer or local-build upload available | Hosting-panel inspection | Not verified |
| Backups | Database and private-file backup and restore process known | Afrihost package details | Not verified |

### Public hosting evidence

Afrihost's current help documentation confirms that shared-hosting customers can select an available PHP version through MultiPHP Manager or the CWP PHP selector, Linux hosting can run PHP scripts and cron jobs, MySQL databases and users can be created in cPanel, and AutoSSL is available through the hosting control panel or Afrihost support. These are platform-level indicators only; they do not prove that this specific account exposes PHP 8.3, all required extensions, suitable upload limits, private storage or the required cron interval.

Public checks on 21 October 2026 confirmed that the portal and website hostnames both resolve to 197.242.159.145. The portal hostname responds through LiteSpeed and currently displays Afrihost's placeholder page. This confirms DNS and basic web-server routing only; it does not confirm a dedicated Laravel public directory, HTTPS readiness or account-level runtime features.

- PHP selector: https://help.afrihost.com/entry/how-to-update-your-domain-php-version/
- PHP and cron support: https://help.afrihost.com/entry/can-i-run-my-own-software-on-my-site/
- MySQL setup: https://help.afrihost.com/entry/how-to-create-a-mysql-database-in-cpanel/
- AutoSSL: https://help.afrihost.com/entry/how-to-install-an-autossl-certificate-for-your-domain-in-cwp/

### Shared-host adaptations

- Build frontend assets before upload when Node.js is unavailable.
- Install Composer dependencies before upload when Composer or SSH is unavailable.
- Process the database queue with a cron command that exits after queued work.
- If queue cron is unavailable, use synchronous email and omit automated reminders and cleanup jobs.
- Do not require Redis, WebSockets, long-running workers, containers or Laravel Octane.

## 13. Environments and Deployment

| Environment | Purpose | Data rule |
|---|---|---|
| Local | Development and automated testing | Synthetic data only |
| Staging | Client review and acceptance testing | Synthetic or approved test data |
| Production | Live portal | Real learner data |

- Use separate keys, databases and storage locations.
- Run migrations before switching production traffic.
- Cache production configuration, routes and views.
- Smoke-test authentication, authorisation, email and uploads after deployment.
- Back up production data and private files before destructive migrations.
- Keep the website application form available until portal acceptance, then deploy the link change separately.

## 14. POPIA and Operations

Q Tech Logistics must approve what personal information is collected, why it is needed, how long it is retained and who may access it. The portal will record the privacy-notice version and consent time for each submitted application. The handover will document access, correction and deletion procedures.

Q Tech Logistics remains responsible for confirming suitable database and file backups. Ongoing monitoring, backup administration and post-warranty maintenance require a separate support arrangement unless added to the agreed scope.

## 15. Milestone 5 Exit Criteria

- The three portal documents agree on scope, roles, routes and milestones.
- The client approves the two-panel workflow and outstanding-input list.
- Mandatory hosting checks are verified with evidence.
- A security-supported PHP, Laravel and Filament combination can run on the host.
- Private storage, HTTPS, MySQL and SMTP are feasible.
- Any hosting limitation that conflicts with the implemented baseline is resolved before deployment.

## 16. Milestone 6 Foundation

The local implementation provides:

- A Laravel 13 application with locked Composer dependencies.
- A learner Filament panel at `/learner` with registration, login, password reset, email verification and profile management.
- An administrator Filament panel at `/admin` with login, password reset, email verification and profile management, but no public registration.
- A role enum, learner-by-default account creation and deny-by-default panel checks.
- A password-prompting `app:create-administrator` command for controlled administrator provisioning.
- MySQL, private-storage, SMTP and Africa/Johannesburg environment defaults in `.env.example` without secrets.
- A working local MAMP MySQL connection with the foundation migrations applied to the `qtechlogistics` development database.
- Automated checks for public panel routes, the missing admin registration route and both role boundaries.

Enrolments and private course materials are implemented in Milestone 9. Assessments, private learner submissions and controlled result publication are implemented in Milestone 10.

## 17. Milestone 7 Applications and Review

The local implementation adds:

- `courses`, `learner_profiles`, `applications`, `application_status_histories`, `application_notes` and `notifications` tables.
- The three approved website courses through an idempotent seeder.
- Extended learner registration that captures first name, surname and phone number.
- Learner-owned application drafts with UUID route identifiers and human-readable references.
- Server-side ownership policies and learner-resource query scoping.
- Consent version and timestamp recording at submission.
- Transactional, row-locked status transitions that prevent skipped or conflicting workflow states.
- Administrator search, status and course filters, review actions and private notes.
- Queued email and Filament inbox notifications for learners and administrators.
- A dedicated local MySQL test database covering ownership, policy, workflow, notifications and route access.

The provisional application fields and consent wording match the production website as of 22 October 2026. Client review is still required before production launch.

## 18. Milestone 8 Learner Records and Documents

The local implementation adds:

- Administrator-managed global document requirements with active, required and display-order controls.
- Automatic checklist synchronisation for existing learners and new registrations.
- One learner document record per global requirement and immutable upload versions for replacements.
- Random private storage paths, sanitised display names, detected MIME checks and configurable upload limits.
- A rate-limited download controller protected by policies instead of direct public storage URLs.
- Learner access to only the current version of their own documents and administrator access for review.
- Pending, approved and changes-required states with mandatory feedback for rejected files.
- The learner application view displays the owner's active checklist, while the administrator application view retains the applicant's complete active and inactive document history. Both expose secure current-file downloads, and administrators can open the related review record.
- Queued email and Filament inbox notifications for uploads and review outcomes.
- Administrator capture of selected historical applications, including original received dates and optional password-setup messages.
- Explicit historical-source metadata without manufacturing a portal privacy-consent timestamp.
- Automated tests covering private storage, replacement history, content validation, ownership, role boundaries, downloads, review and historical capture.

The repository intentionally contains no assumed supporting-document list. PDF, JPEG, PNG and 5 MB are provisional development settings only. Production collection remains disabled until Q Tech Logistics approves the checklist, privacy wording and retention/deletion rules and Afrihost upload and storage capabilities are verified.

## 19. Milestone 9 Courses and Materials

The local implementation adds:

- `enrolments` records with non-sequential public identifiers, learner, course, status, optional access dates and private administration notes.
- Administrator-only enrolment creation and management for learner accounts.
- Administrator bulk enrolment for up to 100 accepted applicants into their selected course, with shared access dates and private notes. The selector excludes non-accepted applicants and learners already enrolled in that course; server validation enforces the accepted-application rule.
- A learner-only My courses listing with offer response, enrolment status, current access state and access dates.
- Email and learner-portal course-offer notifications when an administrator creates an enrolment.
- A learner-owned offer-acceptance action; published materials and assessments remain unavailable until acceptance.
- Active, suspended, completed and cancelled states, with current access requiring an active status inside the optional start/end window.
- `materials` records linked to courses with private file metadata, draft/published state and display order.
- Administrator upload and management screens for private course materials.
- A learner course-material listing scoped to published records for current active enrolments.
- A rate-limited material download controller that performs a server-side policy check before streaming from private storage.
- Denial of guest, unrelated-learner, unpublished, suspended, expired and future-enrolment access.
- Automated tests for enrolment timing, role boundaries, query isolation and private downloads.

Office documents, PDF, text, JPEG and PNG files up to 20 MB are provisional development settings. The client must supply the initial approved materials, and Afrihost upload and storage limits must be verified before production use.

## 20. Milestone 10 Assessments and Results

The local implementation adds:

- `assessments` records linked to courses with instructions, optional deadlines and maximum scores, draft/published state and display order.
- A learner assessment listing limited to published records for current active enrolments.
- One current private `submission` per learner and assessment, with a stable human-readable receipt reference, detected file metadata, notes and submission time.
- File replacement before the deadline and before a result is recorded, with removal of the superseded private file.
- A rate-limited submission download controller protected by ownership and administrator policies.
- Administrator assessment management and submission review screens.
- Private draft `results` with optional score, Competent or Not yet competent outcome, feedback, recorder and publication timestamp.
- A separate administrator publication action; learners cannot retrieve or view draft results.
- Queued email and Filament inbox notifications for submission receipts, administrator submission alerts and published-result availability.
- Automated tests covering enrolment scoping, deadlines, private storage, replacement, downloads, draft privacy, publication and panel boundaries.

Assessment submissions provisionally allow office documents, PDF, text, JPEG and PNG up to 20 MB. Score plus Competent/Not yet competent is the provisional result model. Q Tech Logistics must approve the scoring rules, outcome terminology, publication policy, initial instructions and production upload limits before launch.

## 21. Shared Portal Branding

The administrator and learner panels share a compiled Filament theme registered through Vite. The sidebar follows the top-header theme with a white light-mode background, a dark-gray dark-mode background and a matching Q-Tech logo variant, without affecting the public website or portal form content.
