ok, bootstrap this contract before this up until creating the file (not yet tested), lock the contract, file hierarchy, status, path and future. I need to work on the full backend to iron out some alignment matters incorporating a new system (android)

Good.

We stop coding forward.

We lock the contract properly before adding more moving parts.

What you’ve built so far is correct — now we formalise it so nothing drifts when you integrate Android and align backend.

🔒 ASSIST SYSTEM CONTRACT v2.0 (LOCKED)

Environment:

Shared hosting

Raw PHP

MySQL (phpMyAdmin)

Single database: cuj011_jb26user

Single identity table: users

Domain root: https://api.jb26.co.za/

Document root physically: /home/cuj011/api.jb26.co.za/api/

API base:

https://api.jb26.co.za/


No /api/ prefix in URL.

🏗 CURRENT FILE HIERARCHY (LOCKED)

Physical structure:

/home/cuj011/api.jb26.co.za/
│
├── config/
│     └── database.php
│
└── api/   ← document root
      ├── auth/
      │     └── login.php
      │
      ├── system/
      │     ├── response.php
      │     ├── audit.php
      │     ├── platform_access.php
      │     └── bootstrap.php (mining)
      │
      └── assist/
            ├── bootstrap.php
            │
            ├── driver/
            │     └── create_breakdown.php
            │
            ├── fleet/
            │     └── submit_po.php
            │
            └── sp/
                  └── get_available_jobs.php   (created, not yet validated)


This structure is now locked.

No moving files.

No second DB.

No second auth.

🧱 DATABASE STRUCTURE (LOCKED)

Single database: cuj011_jb26user

Core (existing)

users

companies

api_tokens

user_platform_access

Assist Layer
dpa_user_roles
dpa_breakdowns
dpa_service_profiles
dpa_service_users
dpa_service_divisions
dpa_service_company_divisions
dpa_job_execution
dpa_job_photos
dpa_audit_log
dpa_archive_log


No duplicate company identity.
No duplicate user identity.

Everything references:

users.id

companies.id

🧠 ROLE MODEL (LOCKED)

Global roles (existing):

super_admin

platform_admin

support

company_owner

company_admin

manager

billing

user

viewer

rsp_admin

Assist roles (new layer):

driver
fleet_controller
sp_admin
artisan
rsp
support


Stored in:

dpa_user_roles


Assist endpoints require:

Valid token

platform_enabled(user, 'assist')

dpa_user_roles entry

This isolation is permanent.

🚦 STATUS ENGINE (LOCKED)

Breakdown lifecycle:

awaiting_po
broadcasting
allocating
allocated
enroute
arrived
in_progress
completed
cancelled
archived


Only valid transitions allowed.

Current implemented:

create_breakdown → awaiting_po

submit_po → broadcasting

No other status changes exist yet.

🌍 GEO BROADCAST CONTRACT (LOCKED DESIGN)

Broadcast rules:

Initial radius = 25km

Window = 300 seconds

Expansion = +25km per tier

Expansion triggered during SP polling

No cron required

No background daemon

Shared-host safe

Isolation rule:

fleet_company.rsp_id = sp_company.rsp_id


No cross-reseller leakage.

🔐 MULTI-TENANT MODEL (LOCKED)

companies table:

id

rsp_id

owner_user_id

company_name

status

Meaning:

Every fleet belongs to an RSP

Every SP belongs to an RSP

Dispatch confined to same RSP boundary

This is permanent design rule.

📦 WHAT IS IMPLEMENTED

✔ Breakdown creation
✔ PO submission
✔ Assist bootstrap
✔ Role enforcement
✔ Platform enforcement
✔ Audit logging
✔ SP polling endpoint file created (untested)

🧊 WHAT IS NOT YET IMPLEMENTED

✖ Atomic job acceptance
✖ SP decline
✖ Penalty tracking
✖ Artisan allocation
✖ ODO capture
✖ Photo upload
✖ Signature capture
✖ PDF generator
✖ Archive engine
✖ Admin frontend (/assist/)
✖ Division filtering in SP polling
✖ Broadcast audit tier logging

🔮 FUTURE TRACKS (LOCKED ORDER)

When backend alignment complete:

Phase 4

SP accept endpoint (atomic lock)

Phase 5

SP cancel with 5-min penalty rule

Phase 6

Artisan allocation + status flow

Phase 7

Execution capture (ODO, photos, signatures)

Phase 8

PDF job card generator

Phase 9

Archive + ZIP + RSP email

Phase 10

Admin frontend at:

https://api.jb26.co.za/assist/


Plain PHP + HTML.

📱 ANDROID CONTRACT (PREPARED BUT NOT ACTIVE)

Android will:

Login via existing auth

Receive token

Call Assist endpoints

Poll every 15 seconds (SP side)

No offline-first

No WebSocket

Firebase push later optional

But Android must NOT move ahead of backend.

Backend remains authority.

🧭 CURRENT STATE OF SYSTEM

Stable.
Consistent.
No structural drift.
No duplicate identity.
No second DB.
No cross-platform interference.

You are now safe to:

Refactor backend alignment

Integrate new Android system

Adjust service profile logic

Extend division filtering

Add fleet hierarchy

Without breaking foundation.

🔒 CONTRACT LOCK

From this point:

No change to identity model

No split user tables

No second database

No duplicate company tables

No framework migration

No websocket addition (shared host)

Everything extends from this base.

When you're ready to resume build:

We continue from:

/assist/sp/get_available_jobs.php


And move into atomic accept logic.

Take the time to align Android and backend now.

We’ve built a stable spine.

When you return, we extend cleanly.