ok, lets freeze Assist at this stage, lock the contract, give full detail of progress until now in bootstrap to avoid drifting in a new chat, I need to switch project to mining. in your bootstrap, note that full file locations are to be listed, compare my code first, and assume i know nothing

Understood. I’ll produce a clean project bootstrap freeze so when you open a new chat later we can continue without drift and verify files before touching anything (as you prefer).

This bootstrap records:

System architecture

Backend contract

Android architecture

Dispatch engine

Push system

File structure

Database schema changes

Current working state

Next development stages

Everything below becomes the Assist v1.0 Freeze Contract.

🔒 ASSIST PLATFORM — SYSTEM BOOTSTRAP FREEZE

Version: 1.0
Status: LOCKED / STABLE FOUNDATION

Purpose of this document:

Future chats must load this bootstrap first.
Do NOT modify architecture without verifying existing files.
All changes must respect this contract.
1️⃣ PLATFORM PURPOSE

Assist is a multi-tenant fleet roadside dispatch system.

The platform connects:

Fleet Companies
Drivers
Fleet Controllers
Service Providers (SP)
Artisans
RSP Administrators

Goal:

Driver logs breakdown
Fleet enters PO
System broadcasts job to SP network
Nearest SP accepts
Artisan attends job
Fleet monitors progress
Job completed with signatures
2️⃣ CORE DISPATCH FLOW
Driver creates breakdown
        ↓
Status = awaiting_po
        ↓
Fleet controller submits PO
        ↓
Status = broadcasting
        ↓
Broadcast radius = 25km
        ↓
Push notifications sent
        ↓
SP accepts job
        ↓
Status = accepted
        ↓
Artisan allocated
        ↓
Status = allocated
        ↓
Artisan enroute
        ↓
Status = enroute
        ↓
Arrived
        ↓
Status = arrived
        ↓
Work completed
        ↓
Status = completed
        ↓
Archived
3️⃣ STATUS STATE MACHINE (LOCKED)
awaiting_po
      ↓
broadcasting
      ↓
accepted
      ↓
allocated
      ↓
enroute
      ↓
arrived
      ↓
completed
      ↓
archived

Rules:

Only SP can move execution states
Fleet cannot change execution states
Archived jobs immutable
4️⃣ BROADCAST ENGINE

Broadcast system expands search radius automatically.

Tier model:

Tier 1 → 25km
Tier 2 → 50km
Tier 3 → 75km
Tier 4 → 100km

Expansion rule:

radius = tier × 25km
tier increases every 5 minutes

This ensures:

nearby providers get priority
far providers only notified if necessary
5️⃣ SERVER SIDE BROADCAST ENGINE

Location:

/api/system/broadcast_engine.php

Responsibilities:

runs every minute
calculates broadcast tier
expands radius
detects eligible SP companies
queues push notifications

Cron:

* * * * * php /var/www/api/system/broadcast_engine.php
6️⃣ PUSH FAN-OUT SYSTEM

Push notifications are not sent directly.

Instead they are queued.

Architecture:

broadcast_engine
      ↓
push_queue
      ↓
push_worker
      ↓
Firebase
      ↓
Android

Purpose:

prevent Firebase push storms
control dispatch rate
handle thousands of providers
7️⃣ PUSH WORKER

Location:

/api/system/push_worker.php

Function:

process push_queue
send pushes in batches
mark pushes sent
retry failures

Cron:

* * * * * php /var/www/api/system/push_worker.php
8️⃣ FIREBASE PUSH SYSTEM

Assist uses:

Firebase HTTP v1 API
OAuth Service Account

Service account file:

/api/firebase/firebase_service_account.json

Token generator:

/core/firebase_token.php

Push sender:

/core/push_sender.php
9️⃣ BACKEND STRUCTURE

Root structure:

/core
/api
/uploads
🔧 /core

Foundation components.

/core/bootstrap.php
/core/status_engine.php
/core/penalty.php
/core/reward.php
/core/firebase_token.php
/core/push_sender.php

Responsibilities:

database connection
authentication
json responses
status validation
reward system
penalty system
firebase auth
push delivery
🌐 /api

API endpoints.

/api/auth/login.php
/api/auth/me.php
/api/auth/register_device.php

Driver endpoints:

/api/driver/create_breakdown.php

Fleet endpoints:

/api/fleet/submit_po.php
/api/fleet/get_live_breakdowns.php

Service provider endpoints:

/api/sp/get_available_jobs.php
/api/sp/accept_job.php
/api/sp/cancel_job.php

Execution endpoints:

/api/execution/update_status.php
/api/execution/upload_photo.php
/api/execution/generate_job_card.php

System endpoints:

/api/system/broadcast_engine.php
/api/system/push_worker.php
🔟 DATABASE TABLES

Core tables:

breakdowns
companies
users
service_profiles
service_company_divisions
device_tokens

Dispatch tables:

push_queue

Breakdown columns include:

status
tier_level
current_radius_km
broadcast_started_at
broadcast_expires_at
accepted_company_id
allocated_at
started_at
arrived_at
completed_at
travel_distance_km
billable_distance_km
signature_path
11️⃣ ANDROID APP

Package:

com.jb26.assist

Project root:

AndroidStudioProjects/Assist
Android Architecture

Pattern:

XML
Fragments
ViewModel
LiveData
Retrofit

No offline support.

All logic API-driven.

12️⃣ ANDROID PACKAGE STRUCTURE
com.jb26.assist

Core:

assist.core
assist.network
assist.security
assist.firebase
assist.util

Auth:

assist.auth

Fleet:

assist.fleet.breakdown
assist.fleet.adapter
assist.fleet.model

SP:

assist.sp.ui
assist.sp.adapter
assist.sp.jobs

Execution:

assist.execution
assist.execution.signature
assist.execution.gps
13️⃣ ANDROID KEY FILES

Launcher:

app/src/main/java/com/jb26/assist/LauncherActivity.kt

Login:

app/src/main/java/com/jb26/assist/auth/LoginActivity.kt

Main navigation:

app/src/main/java/com/jb26/assist/MainActivity.kt

SP queue:

app/src/main/java/com/jb26/assist/sp/ui/JobQueueFragment.kt

Fleet monitor:

app/src/main/java/com/jb26/assist/fleet/breakdown/FleetBreakdownFragment.kt

Execution screen:

app/src/main/java/com/jb26/assist/execution/ExecutionFragment.kt

Signature capture:

app/src/main/java/com/jb26/assist/execution/signature/SignaturePadView.kt

GPS milestone logging:

app/src/main/java/com/jb26/assist/execution/gps/GpsMilestoneTracker.kt

Push service:

app/src/main/java/com/jb26/assist/firebase/AssistFirebaseService.kt
14️⃣ MOBILE NAVIGATION

Launcher activity decides route.

token exists?
      ↓
YES → MainActivity
NO  → LoginActivity

MainActivity loads navigation based on role.

Example:

driver
fleet_controller
sp_admin
artisan
15️⃣ JOB QUEUE REFRESH

SP job queue refresh sources:

manual refresh
auto timer (30 sec)
push notification trigger

Push message type:

BREAKDOWN_BROADCAST

Triggers:

refresh job queue
16️⃣ EXECUTION MODULE

Execution screen handles:

enroute
arrived
completed

Milestones captured:

start odometer
arrival odometer
completion notes
signature
GPS checkpoints

Signature stored:

uploads/signatures/
17️⃣ FLEET LIVE MONITOR

Fleet controller screen shows:

live breakdown list
status color mapping
SP assigned
timestamps
distance

Color mapping improves usability.

18️⃣ SECURITY MODEL

Authentication:

Bearer token

Device registration:

register_device.php

Push tokens stored:

device_tokens table
19️⃣ MULTI TENANT ISOLATION

Isolation key:

rsp_id

Rules:

SP cannot see other RSP jobs
Fleet cannot see other companies
Dispatch limited by RSP
20️⃣ CURRENT SYSTEM STATUS

Backend:

dispatch engine complete
push system complete
API endpoints implemented
database aligned

Android:

login working
session routing working
job queue implemented
execution module implemented
signature capture working
fleet monitor implemented
push service implemented
21️⃣ NEXT DEVELOPMENT STAGES

Next components when Assist resumes:

dispatch SLA engine
SP ranking system
repair photo upload
job card PDF
driver app UI
admin analytics dashboard
🔒 LOCK DIRECTIVE

Future chats must follow this rule:

ALWAYS request existing file code before modifying
verify file paths
do not rename packages
do not introduce new architecture

This prevents architecture drift.

End of Assist Bootstrap Freeze

You can now safely switch projects.

When you return to Assist, start the new chat with:

Load Assist Bootstrap v1.0

and we will continue without breaking the architecture.

If you'd like, I can also produce a one-page system architecture diagram of Assist (dispatch engine, mobile apps, push system, API, cron workers).

It makes the whole platform very easy to visualize and maintain.