Status: Implementation specification
Target: Flutter / Android
Backend: Laravel API
Web: Laravel + Inertia + React
Local database: SQLite via Drift
Object storage: S3-compatible
Primary mode: Offline-first
Initial scope: Inspection only; no OBD, invoicing, repair orders, inventory, scheduling, or iOS
This document turns the agreed product architecture into an implementation-oriented specification for the Android mobile application.
The application is not a hard-coded Toyota 160-point checklist. It is a generic inspection client that receives versioned inspection templates from the backend and renders them dynamically.
The Toyota 160-point inspection is a reference/base template. The source contains vehicle identity fields, inspection date, mileage, RO number and inspection-sheet number, categorized checks, certification/signature areas, and item outcomes such as Meets Standards, Adjust/Repair and N/A. The source also contains specialized additional and hybrid checks. The mobile application should model these as configurable template behavior rather than hard-code them.
Source reference: Toyota 160-Point Quality Assurance Inspection Check Sheet, page 1.
- Multi-tenant platform.
- Multiple workshops/vendors.
- Multiple brands.
- Multiple vehicle models.
- Multiple inspection types.
- One vehicle can have many inspections.
- Multiple mechanics can inspect the same vehicle over time.
- One mechanic can inspect the same vehicle multiple times.
- Completed inspections are immutable.
- Corrections/reinspections create new linked records.
- Template versions are frozen for an inspection.
- Flutter.
- Android only for V1.
- Offline-first is mandatory.
- Camera.
- Gallery.
- Video.
- Multiple media per inspection item.
- Photo annotation.
- Arrows/circles.
- Timestamp.
- GPS where permitted/configured.
- VIN watermark.
- Manual vehicle data entry.
- No automatic VIN recognition.
- No number-plate recognition.
- No OBD integration.
The backend/template controls:
- Item type.
- Pass/fail behavior.
- N/A availability.
- Measurement requirements.
- Measurement unit.
- Validation rules.
- Required evidence.
- Number of required photos.
- Video allowance.
- Customer visibility.
- Conditional visibility.
- Severity defaults.
- Section ordering.
- Item ordering.
The mobile application must allow an inspector to:
- Authenticate.
- Enter/select their workshop context.
- Browse vehicles.
- Create a vehicle.
- View vehicle history.
- Start an inspection.
- Select an inspection type/template.
- Download/freeze the template version.
- Perform the inspection offline.
- Enter pass/fail/N/A results.
- Enter measurements.
- Create findings.
- Add notes.
- Capture photos.
- Select photos from gallery.
- Capture video.
- Annotate evidence.
- Capture evidence metadata.
- Continue after app restart.
- Continue without internet.
- Queue synchronization.
- Synchronize when connectivity returns.
- Complete the inspection.
- See synchronization/completion status.
Do not implement:
- OBD/Bluetooth diagnostic integration.
- VIN decoder.
- Automatic VIN recognition.
- Automatic number-plate recognition.
- Customer signatures.
- In-app payments.
- Repair orders.
- Invoices.
- Parts inventory.
- Workshop scheduling.
- Customer chat.
- iOS.
- Advanced analytics.
- Full workshop-management functionality.
- Backend PDF generation inside Flutter.
The backend owns PDF generation.
Recommended navigation:
Login
|
v
Home
|
+-- Vehicles
| |
| +-- Vehicle List
| +-- Create Vehicle
| +-- Vehicle Details
| |
| +-- Vehicle Information
| +-- Inspection History
| +-- Start Inspection
|
+-- Inspections
| |
| +-- Draft / In Progress
| +-- Completed
|
+-- Sync
|
+-- Profile / Settings
During an inspection:
Inspection Overview
|
v
Section List
|
v
Section
|
v
Inspection Item
|
+-- Result
+-- Measurement
+-- Finding
+-- Notes
+-- Evidence
|
v
Next Item
The home screen should prioritize inspection work.
Suggested content:
Good morning, John
Workshop: Downtown Motors
[ Continue Inspection ]
Today
Draft inspections: 2
Completed: 4
Pending sync: 7
[ Vehicles ]
[ Inspections ]
Sync status
7 items pending
The exact visual design can evolve, but the home screen must expose:
- Active/draft inspections.
- Quick vehicle access.
- Sync status.
- Current workshop.
- User identity.
Required functionality:
- Search by VIN.
- Search by registration number.
- Search by number plate.
- Search by owner name.
- Filter by recent activity.
- Open vehicle.
- Create vehicle.
No automatic detection is required.
Example:
Search vehicles...
ABC123
2024 Toyota Corolla
VIN: XXXXXXXXX
Owner: Rahim Ahmed
Last inspection: 24 Aug 2026
Required fields:
Brand
Model
Year
Variant / Trim
Fuel Type
VIN
Registration Number
Number Plate
Owner Name
Owner Phone (if required by backend)
Optional fields should be controlled by backend configuration where appropriate.
Validation:
- VIN required if the selected tenant/template requires it.
- Number plate may be required.
- Registration number may be required.
- Year must be valid.
- Do not attempt VIN decoding.
The vehicle details page should show:
2024 Toyota Corolla
VIN
XXXXXXXXXXXX
Number Plate
ABC-123
Owner
Rahim Ahmed
--------------------------------
[ Start New Inspection ]
Inspection History
24 Aug 2026
Pre-Sale Inspection
Inspector: John
Result: Attention Required
18 Jul 2026
Trade-In Inspection
Inspector: Sarah
Result: Pass
The history is read-only for completed inspections.
Start from vehicle details.
Vehicle
|
v
Start New Inspection
|
v
Select Inspection Type
|
v
Available Templates
|
v
Template Version
|
v
Inspection Setup
|
v
Start
Inspection setup should collect:
- Inspection type.
- Template.
- Template version.
- Current mileage.
- Optional internal reference / RO number if configured.
- Inspector.
- Start timestamp.
The selected template version becomes immutable for the inspection.
Recommended states:
DRAFT
|
v
IN_PROGRESS
|
v
READY_FOR_REVIEW
|
v
COMPLETED
Additional state:
CANCELLED
Historical relationship:
COMPLETED
|
+-- superseded_by --> NEW INSPECTION
Can:
- Open.
- Continue.
- Cancel.
- Delete locally if it has never synchronized, subject to backend policy.
Can:
- Continue.
- Pause.
- Save.
- Capture evidence.
- Complete.
Optional state if manager review is enabled by tenant/template.
Can:
- Review.
- Return for correction before final completion.
Cannot:
- Edit.
- Delete.
- Replace silently.
Can:
- View.
- Generate/view report through backend.
- Create reinspection/correction inspection.
Read-only historical record if synchronized.
The inspector should see:
Used Car Inspection
2024 Toyota Corolla
VIN: XXXXXXXX
Mileage: 82,341 km
Progress
142 / 160
Sections
✓ Vehicle Identity
✓ Road Test
⚠ Brakes
○ Under Hood
○ Functional
○ Appearance
[ Continue Inspection ]
Progress should be based on required items, not merely the number of UI pages visited.
Every section should display:
- Section title.
- Completion count.
- Failed count.
- Required evidence count.
- Section status.
Example:
Road Test
34 / 34
✓
Brakes
5 / 8
⚠ 2 findings
Under Hood
0 / 14
○
An inspection item is a mini workspace.
Example:
--------------------------------
Front brake pad thickness
Minimum: 4 mm
[ PASS ] [ FAIL ] [ N/A ]
Measurement
[ 6.2 ] mm
Notes
[ Light wear, even across axle... ]
Evidence
[ Camera ] [ Gallery ] [ Video ]
2 photos attached
Previous inspection
7.0 mm
18 Jul 2026
[ < Previous ] [ Next > ]
--------------------------------
The UI should render controls from the template item definition.
Never hard-code:
if item.id == "brake_pad_front"
Instead:
if item.input.type == "measurement"
Minimum V1:
pass_fail
pass_fail_na
measurement
number
text
selection
Potential future types:
multi_selection
date
time
signature
barcode
photo_only
video_only
Do not implement future types until required.
A result can contain:
PASS
FAIL
N/A
Optional internal status:
NOT_STARTED
IN_PROGRESS
COMPLETED
Do not expose NOT_STARTED as an inspection result unless the template explicitly supports it.
A measurement item should define:
{
"input": {
"type": "measurement",
"unit": "mm"
},
"validation": {
"minimum": 4
},
"result": {
"type": "pass_fail"
}
}The app records:
value = 6.2
unit = mm
The backend/template determines whether this means PASS or FAIL.
The mobile application may display the derived result immediately, but the backend remains authoritative.
A failed item may create a finding.
Fields:
id
inspection_result_id
severity
title
description
recommendation
status
created_at
Example:
Severity: High
Front left brake pad
Measured: 2.8 mm
Recommendation:
Replace front brake pads.
The mechanic should be able to create or edit the finding while the inspection is in progress.
Notes can exist:
- On inspection.
- On section, if supported later.
- On inspection item.
- On finding.
V1 should prioritize item notes and finding descriptions.
Templates can contain conditions.
Example:
IF vehicle.fuel_type == "hybrid"
THEN show "Hybrid Components"
Another example:
IF item.sunroof == "yes"
THEN show "Sunroof operation"
The mobile renderer should evaluate conditions locally from the downloaded template and current inspection answers.
The backend must validate the final inspection against the same rules.
Every evidence record belongs to:
inspection
inspection_result
Supported:
- Photo.
- Video.
Multiple evidence objects per item are allowed.
Example:
Inspection
|
+-- Result #47
|
+-- Photo 1
+-- Photo 2
+-- Video 1
When the user taps Camera:
Open camera
|
v
Capture
|
v
Preview
|
+-- Retake
|
+-- Use photo
|
v
Add metadata
|
v
Store locally
Do not upload directly from the camera screen.
The local file must first become a durable media record.
Gallery
|
v
Select one or more
|
v
Preview
|
v
Confirm
|
v
Store locally
Multiple selection must be supported.
V1 requirements:
- Capture video.
- Store locally.
- Associate with inspection item.
- Queue upload.
- Display upload state.
Avoid complex video editing in V1.
Annotations should not destroy the original.
Store:
Original image
+
Annotation data
Example:
{
"type": "circle",
"x": 0.62,
"y": 0.44,
"radius": 0.12
}Use normalized coordinates from 0.0 to 1.0.
Supported V1 tools:
- Circle.
- Arrow.
- Optional freehand marker if implementation remains simple.
Each media record should support:
local_id
server_id
inspection_id
inspection_result_id
type
local_path
remote_path
mime_type
file_size
width
height
captured_at
latitude
longitude
watermark_applied
sha256
upload_status
created_at
updated_at
GPS may be null when:
- Permission is denied.
- GPS is unavailable.
- Template does not require it.
The app should support a configurable watermark layer.
Minimum identity:
VIN
Inspection number / local inspection identity
Timestamp
Workshop branding may be added later.
Important:
- Preserve original.
- Create derived/watermarked output.
- Do not destroy original evidence.
Use Drift over SQLite.
Suggested local tables:
local_workshops
local_users
local_vehicles
local_templates
local_template_versions
local_template_sections
local_template_items
local_inspections
local_inspection_results
local_findings
local_measurements
local_media
local_annotations
local_sync_operations
Every synchronized entity should have:
local_id
server_id
sync_status
created_at
updated_at
Recommended values:
LOCAL_ONLY
PENDING
SYNCING
SYNCED
FAILED
CONFLICT
The UI should expose meaningful status.
Example:
✓ Saved locally
↻ Syncing
✓ Synced
⚠ Sync failed
Do not expose raw technical errors to mechanics.
Every server mutation should create a sync operation.
Example:
SyncOperation
id
operation_type
entity_type
entity_local_id
payload
attempt_count
status
last_error
created_at
updated_at
Example:
CREATE_INSPECTION
CREATE_RESULT
UPDATE_RESULT
CREATE_FINDING
CREATE_MEDIA
COMPLETE_INSPECTION
Use idempotency keys.
Example:
idempotency_key = UUID
The same operation can safely be retried.
User action
|
v
SQLite transaction
|
+--> UI updates immediately
|
+--> SyncOperation created
|
v
Connectivity?
/ \
No Yes
| |
Queue Upload
|
Server accepts
|
Mark SYNCED
If connectivity disappears during upload, retry safely.
Keep operation queued.
Keep local data. Request authentication again.
Do not delete local inspections.
Mark operation as FAILED.
Show a human-readable action.
Server returns existing result based on idempotency key.
Operation remains in SQLite and resumes later.
All pending work remains.
The inspector must be able to complete an inspection without internet.
Flow:
Complete
|
v
Local validation
|
+-- missing required data?
| |
| v
| Show errors
|
v
Mark COMPLETED locally
|
v
Queue completion operation
|
v
Sync later
The server repeats validation when the completion operation arrives.
Example rule:
{
"evidence": {
"photo": "required_on_fail",
"minimum": 2
}
}If FAIL is selected:
Photo count < 2
|
v
Cannot complete item
The exact rule comes from the template.
The mobile device must download a complete immutable template version.
Store:
template
template_version
sections
items
rules
conditional logic
evidence rules
Once an inspection starts:
inspection.template_version_id
must remain unchanged.
Do not silently update the template while an inspection is in progress.
When the backend publishes a new version:
Server:
Template v4 published
Mobile may download v4.
Existing inspection:
Inspection #100
Template v3
continues with v3.
New inspection:
Inspection #101
Template v4
uses v4.
Recommended:
- Laravel Sanctum or equivalent token-based API authentication.
- Secure token storage on Android.
- Refresh/session mechanism as defined by backend.
- Never store access tokens in plain SharedPreferences.
- Logout must not destroy unsynchronized inspection data without explicit user confirmation.
The authenticated user belongs to one or more workshops according to backend permissions.
If multiple workshop contexts are supported:
Select Workshop
must happen before vehicle/inspection data is loaded.
Tenant context must never be accepted blindly from arbitrary client input.
The server determines authorized tenant access.
Use OpenAPI as the source of truth.
Minimum mobile endpoints:
POST /api/mobile/login
GET /api/mobile/me
GET /api/mobile/workshops
GET /api/mobile/vehicles
POST /api/mobile/vehicles
GET /api/mobile/vehicles/{id}
GET /api/mobile/templates
GET /api/mobile/templates/{id}
POST /api/mobile/inspections
GET /api/mobile/inspections/{id}
POST /api/mobile/sync
POST /api/mobile/media/presign
POST /api/mobile/media/complete
POST /api/mobile/inspections/{id}/complete
Exact URLs can be changed during backend implementation; the important requirement is that the API contract is documented before mobile integration becomes broad.
Prefer pre-signed S3-compatible uploads.
Flow:
Flutter
|
| request upload URL
v
Laravel
|
| signed upload URL
v
Flutter
|
| upload directly
v
S3
|
| complete upload
v
Laravel
This prevents large video/photo payloads from unnecessarily passing through the Laravel application server.
Mobile must assume all local data is potentially sensitive.
Protect:
- Authentication tokens.
- Local database where practical.
- Private media.
- Report credentials.
- User/session data.
Do not rely on the mobile client to enforce authorization.
The backend is authoritative.
Potential permissions:
CAMERA
ACCESS_FINE_LOCATION
ACCESS_COARSE_LOCATION
Media access should use modern Android APIs appropriate to the minimum supported Android version.
Permissions must be requested only when needed.
If location is optional:
Permission denied
|
v
Continue inspection
If a template explicitly requires GPS:
Permission denied
|
v
Show requirement
|
v
Allow retry
Resume inspection from local state.
Resume local inspection.
Continue inspection.
Continue inspection.
Keep media locally and retry.
Preserve local work.
Warn user and prevent silent data loss.
Every major screen must define:
- Loading.
- Empty.
- Error.
- Offline.
- Retry.
Examples:
No vehicles found.
[ Create Vehicle ]
You're offline.
Your inspection is saved on this device.
Sync failed.
Your work is safe and will be retried.
[ Retry now ]
Recommended layers:
Presentation
|
Application / Use Cases
|
Domain
|
Repositories
|
+-----------+-------------+
| |
Local Data Remote API
Drift Laravel
Do not allow UI widgets to call HTTP directly.
lib/
core/
error/
network/
storage/
permissions/
connectivity/
security/
routing/
features/
authentication/
data/
domain/
presentation/
vehicles/
data/
domain/
presentation/
templates/
data/
domain/
presentation/
inspections/
data/
domain/
presentation/
media/
data/
domain/
presentation/
sync/
data/
domain/
presentation/
reports/
data/
domain/
presentation/
settings/
data/
domain/
presentation/
Use one consistent state-management approach across the app.
The specific package can be selected before implementation, but it must support:
- Reactive UI.
- Dependency injection.
- Async state.
- Offline database observation.
- Testability.
Avoid mixing multiple state-management patterns.
Example:
abstract class InspectionRepository {
Future<Inspection> createDraft(CreateInspectionInput input);
Stream<Inspection> watchInspection(String localId);
Future<void> saveResult(
String inspectionId,
SaveInspectionResultInput input,
);
Future<void> completeInspection(String inspectionId);
Future<void> syncInspection(String inspectionId);
}The presentation layer should depend on interfaces, not Drift or HTTP directly.
At minimum:
Workshop
User
Vehicle
Template
TemplateVersion
TemplateSection
TemplateItem
Inspection
InspectionResult
Finding
Measurement
Media
Annotation
SyncOperation
Every local record needs a stable UUID.
Example:
local_id = 01J...
server_id = nullable
Before synchronization:
server_id = null
After synchronization:
server_id = 987
Never use auto-increment SQLite IDs as cross-device synchronization identity.
Store timestamps as UTC internally.
Display according to workshop/user timezone.
Capture:
created_at
updated_at
started_at
completed_at
captured_at
synced_at
Do not use device-local formatted strings as the canonical value.
Store:
latitude
longitude
accuracy
captured_at
If needed later:
altitude
heading
speed
Do not make GPS a global mobile requirement. It should be controlled per template/item or media rule.
Recommended:
Camera
|
v
Original file
|
+--> SHA-256
|
+--> Thumbnail
|
+--> Watermarked derivative
|
+--> Annotation derivative
|
v
Local media record
|
v
Upload queue
Keep originals.
The mobile app should not decide customer report content.
It only records:
item result
finding
measurement
media
notes
The backend/report profile decides:
customer_visible = true/false
This allows internal and customer reports to differ.
Every vertical slice must include:
- Domain rules.
- Measurement validation.
- Conditional rules.
- State transitions.
- Sync operation generation.
- Drift persistence.
- API mapping.
- Offline behavior.
- Item rendering.
- Result selection.
- Validation states.
- Error states.
At minimum:
Login
Create vehicle
Start inspection
Save result
Kill/restart app
Resume
Complete offline
Sync
Do not start with all 160 points.
Build:
LOGIN
↓
HOME
↓
CREATE VEHICLE
↓
START INSPECTION
↓
ONE TEST TEMPLATE
↓
ONE SECTION
↓
ONE ITEM
↓
PASS / FAIL
↓
SAVE TO SQLITE
↓
KILL APP
↓
REOPEN
↓
RESUME
Acceptance criteria:
- User can authenticate.
- Vehicle can be created.
- Test template is available locally.
- Inspection can start.
- Result saves to Drift.
- App can be killed.
- App can restart.
- Inspection remains intact.
- Result remains intact.
- No network is required after template availability.
Implement:
- Multiple sections.
- Multiple items.
- Section progress.
- Item progress.
- Pass/fail/N/A.
- Text.
- Number.
- Measurement.
- Conditional items.
- Local persistence.
Acceptance criteria:
- Template contains at least 3 sections.
- At least 10 items render dynamically.
- No item IDs are hard-coded in Flutter.
- App works without network.
- Inspection resumes after restart.
Implement:
- Measurement fields.
- Minimum/maximum validation.
- Derived PASS/FAIL.
- Finding creation.
- Severity.
- Recommendation.
- Notes.
Acceptance criteria:
- A measurement can automatically determine result.
- Invalid values are clearly shown.
- FAIL can create a finding.
- Findings persist after restart.
Implement:
- Camera.
- Gallery.
- Multiple photos.
- Local file persistence.
- Item association.
- Thumbnail generation.
- Timestamp.
- SHA-256.
- Watermark.
Acceptance criteria:
- Five photos can be attached to one item.
- App restart does not lose them.
- Original files remain available.
- Thumbnail is shown immediately.
- Upload is not required to continue inspection.
Implement:
- Open image.
- Draw circle.
- Draw arrow.
- Undo.
- Clear.
- Save annotation.
- Render preview.
Acceptance criteria:
- Original image remains untouched.
- Annotation survives app restart.
- Annotation uses normalized coordinates.
- Derived image can be generated.
Implement:
- Camera video capture.
- Local persistence.
- Thumbnail.
- Duration.
- Upload queue.
Acceptance criteria:
- Video remains available offline.
- Upload can be resumed after failure.
Implement:
- Connectivity detection.
- Sync queue.
- Idempotency keys.
- Retry.
- Exponential backoff.
- Server acknowledgement.
- Media upload.
- Failure states.
Acceptance criteria:
Start offline
↓
Complete inspection
↓
Turn internet on
↓
Sync
↓
Refresh backend
↓
Inspection exists exactly once
Implement:
- Laravel template API.
- Template version download.
- Local template cache.
- Template activation.
- Version freeze.
Acceptance criteria:
Backend v1
↓
Mobile downloads v1
Backend v2
↓
Mobile downloads v2
Existing inspection
↓
Still uses v1
New inspection
↓
Uses v2
Implement:
- Vehicle history endpoint.
- Local vehicle history.
- Inspection list.
- Inspection detail.
- Reinspection relationship.
Acceptance criteria:
Vehicle A
|
+-- Inspection 1 — John
+-- Inspection 2 — Sarah
+-- Inspection 3 — John
All records remain individually identifiable.
Implement:
- Required-field validation.
- Required-evidence validation.
- Final local completion.
- Server completion.
- Immutable state.
Acceptance criteria:
- Missing required fields block completion.
- Required evidence blocks completion.
- Completed inspection cannot be edited.
- Offline completion is allowed.
- Server revalidates completion.
Implement:
- Error boundaries.
- Crash-safe persistence.
- Storage warnings.
- Authentication expiry recovery.
- Sync diagnostics.
- Permission recovery.
- Database migrations.
- App upgrade migration tests.
For Codex/Antigravity:
- Work one vertical slice at a time.
- Do not implement future slices prematurely.
- Do not invent API contracts.
- Do not hard-code template item IDs.
- Do not hard-code Toyota-specific behavior.
- Do not bypass repositories.
- Do not put HTTP calls directly in widgets.
- Do not destroy local unsynchronized data.
- Do not mutate completed inspections.
- Write tests with every slice.
- Run formatter/analyzer/tests after each slice.
- Keep the application runnable after every slice.
- Prefer small commits.
- Document assumptions.
- Stop and ask for clarification when a product decision is genuinely missing rather than inventing business behavior.
A slice is complete only when:
Code implemented
+
Database migration complete
+
API contract updated if applicable
+
Tests added
+
Offline behavior tested where applicable
+
Error states handled
+
Loading states handled
+
No hard-coded business/template IDs
+
Flutter analyzer clean
+
Tests passing
+
Existing functionality still works
The first task for the AI editor should be:
Set up the Flutter Android application.
Implement:
- Project structure
- Environment configuration
- Routing
- Dependency injection
- Local Drift database
- Secure authentication storage
- Connectivity abstraction
- Basic error handling
- Test infrastructure
Do NOT implement:
- Real inspection templates
- Camera
- Sync
- PDF
- Media
- Backend integration beyond the authentication abstraction
Then build Vertical Slice 1.
The mobile application is a client, not the authority.
Backend is authoritative for:
- Users.
- Permissions.
- Tenant access.
- Templates.
- Template versions.
- Validation.
- Inspection completion.
- Report visibility.
- Audit.
Mobile is authoritative only for its temporary local state until synchronization.
┌─────────────────────┐
│ Flutter │
│ Android │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Presentation │
│ Screens / Widgets │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Application / Use │
│ Cases │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Domain │
│ Inspection / Media │
└──────────┬──────────┘
│
┌─────────────┴─────────────┐
│ │
┌──────▼──────┐ ┌──────▼──────┐
│ Drift │ │ Laravel │
│ SQLite │ │ API │
└──────┬──────┘ └──────┬──────┘
│ │
┌──────▼──────┐ ┌──────▼──────┐
│ Sync Queue │────────────►│ MySQL │
└─────────────┘ └─────────────┘
│
┌──────▼──────┐
│ S3 Storage │
└─────────────┘
Before starting broad mobile development, confirm these artifacts exist:
- Product architecture document
- Mobile technical specification
- Final template JSON schema
- OpenAPI backend contract
- Drift local schema
- Sync protocol
- Media/annotation model
- Inspection state machine
- Screen/navigation specification
- Vertical slice backlog
- Test strategy
- Android development environment
- Laravel local development environment
- S3-compatible development bucket
- Test workshop
- Test users for each role
- Test vehicle
- Test inspection template
Once those are in place, the project is ready to move from architecture into implementation.
MOBILE_DATA_MODEL.md
Vehicle Inspection Platform — Mobile Data Model
Target: Flutter / Android
Persistence: SQLite via Drift
Mode: Offline-first
Backend authority: Laravel API
Storage: S3-compatible object storage for remote media
1. Goals
The local database must:
The mobile database is a working copy, not the system of record. Laravel remains authoritative after synchronization.
2. Identity Rules
Every locally-created entity uses a UUID:
Do not use SQLite auto-increment IDs as synchronization identity.
Recommended metadata on synchronized entities:
Suggested sync states:
3. Entity Relationship Overview
4. Local Tables
4.1 local_workshops
Purpose: cache authorized workshop/tenant information.
Fields:
Indexes:
4.2 local_users
Foreign key:
4.3 local_vehicles
Indexes:
Search should support partial matching where practical.
5. Template Storage
Templates are downloaded from the backend and cached locally.
5.1 local_templates
5.2 local_template_versions
Unique constraint:
A template version is immutable after publication.
5.3 local_template_sections
Unique:
5.4 local_template_items
config_jsoncontains backend-defined item configuration.Do not hard-code Toyota-specific item IDs in Flutter.
6. Inspections
6.1 local_inspections
Recommended indexes:
7. Inspection Results
7.1 local_inspection_results
Recommended result values:
NULLmeans the item has not yet been answered. It is not an inspection outcome.8. Measurements
8.1 local_measurements
The backend/template defines the authoritative validation rules.
Mobile may calculate a provisional result for immediate UI feedback.
9. Findings
9.1 local_findings
Suggested severity values:
The actual set should be backend-configurable.
10. Media
10.1 local_media
Media types:
Upload states:
11. Annotations
11.1 local_annotations
Example:
{ "type": "circle", "x": 0.62, "y": 0.44, "radius": 0.12 }Coordinates are normalized from 0.0 to 1.0.
Never overwrite the original media.
12. Sync Operations
12.1 local_sync_operations
Operation examples:
13. Transaction Rules
A user action that changes inspection state must be atomic.
Example: selecting FAIL:
The UI must not show a saved result unless the local transaction succeeded.
For media:
The physical file must be durably stored before the database transaction is considered successful.
14. Deletion Rules
Avoid physical deletion of inspection history.
For local drafts:
For completed/synchronized inspections:
15. Migration Strategy
Every schema change must use a Drift migration.
Example:
Never reset the database in production.
Migration tests are required for every schema version.
16. Local Database Rules
17. Recommended Drift Structure
18. Important Invariants
Inspection
An inspection must reference exactly one template version.
Template
A published template version cannot be mutated.
Result
An inspection result belongs to exactly one inspection and one template item.
Media
Every inspection media object belongs to exactly one inspection and one result/item.
Sync
Every server mutation has an idempotency key.
Completion
A completed inspection cannot be edited.
19. Mobile vs Backend Authority
Mobile is authoritative for:
Backend is authoritative for: