Step 1: Platform Admin + Company Setup
Company onboarding, roles, and task basics are in place.
Flutter Client + Device Services
Step 2 adds the cross-device experience: offline-first tasks, queued sync, route tracking, and mileage capture. Flutter keeps the UI consistent across devices while device services capture tracking and attachments.
In Progress
Project State Timeline
Step 2: Flutter Client + Device Services
Mobile UI, offline sync, and tracking data capture.
Current step
Step 3: Reporting + Analytics
Mileage, route summaries, exports, and operational dashboards.
Flutter Experience
- Shared UI for tasks, check-ins, and daily workflows.
- Offline-first local store with queued sync.
- Role-aware navigation for admin, manager, and member.
- Target Android and iOS with one codebase.
Device Features
- Opt-in user location tracking with background modes.
- Vehicle mileage capture with manual entries and guidance.
- Device registration with secure per-device tokens.
- Reminders and alerts via notifications.
Backend + Sync
- REST and JSON endpoints for records, locations, and mileage.
- Idempotent sync with cursors and conflict rules.
- Retention policies and audit logs (system-level).
- Batch ingestion to protect DB load.
Current Features (Delivered)
- Platform admin login with company create and update controls.
- Company user management: invite, update roles and status, reset password.
- Company login with dashboard and task creation.
- Tasks create and edit with basic stats (my open, my done, team open, overdue).
- Password reset emails for platform admins and company users.
- Flutter local-only mode with tasks, route segments, and points stored on device.
- QR pairing for mobile devices with optional unpairing to return to local mode.
- Route list and route map view with auto-zoom to tracked paths.
Current State Snapshot (Mobile)
- App starts in local mode; pairing is optional.
- Local routes and tasks stay visible while unpaired.
- Pairing/login pushes local tasks, segments, and points to the server.
- Tracking uses distance-based sampling with configurable thresholds.
- Routes can be reviewed per task or via the full route list.
Implementation Phases
- Phase 0: finalize API contract and data model for records, devices, tracking, and mileage.
- Phase 1: Flutter shell, auth, task list and create, and basic offline cache.
- Phase 2: route tracking between tasks with background location sync.
- Phase 3: mileage workflows, approvals, and reporting.
- Phase 4: QA, battery tuning, privacy review, and rollout plan.
Agent
- Multi-Device Implementation Agent: owns Flutter architecture, device services, and sync strategy.
- Responsibilities: select plugins, define permission flow, design background tracking, align API contracts.
- Outputs: Flutter module map, sync spec, device data retention policy, testing checklist.
Web vs Flutter Boundary
- PHP web stays focused on platform admin and company setup workflows.
- Flutter targets daily field work that benefits from device features.
- Device data capture (location, mileage) lives only in Flutter.
- Flutter web is possible, but not required for admin UX right now.
- Shared backend APIs allow either client to expand later.
Design Thinking Session (Open)
- Design thinking session only; no actual decisions yet.
- Planning principle: avoid double development and dual tracks.
- Planning assumption: Flutter covers device-only tracking and local-mode workflows.
- Planning assumption: PHP web covers admin, ops, and reporting for MVP.
- Planning assumption: Flutter web is deferred unless a mobile-only gap appears.
- Planning principle: preliminary MVP only; avoid parity work.
- Notes: docs/DESIGN_SESSION.md
Use Cases (Notes)
- MVP focus: vehicle mileage tracking on mobile with simple summaries.
- Field/vehicle work: travel tracking, on-site time, and photo capture.
- Taxi mode: base fee + per-km rate with time-based pricing.
- Logistics: dispatch planning on web/tablet with mobile execution.
- Invoicing: taxi immediate, mileage periodic, logistics per customer.
Route Tracking MVP (Flutter)
- Users complete Task A and choose "Start travel to next task".
- App starts background tracking with distance-based sampling.
- User opens Task B and taps "Arrived / Start task" to stop tracking.
- Route segment links start_task_id and end_task_id for reporting.
- Offline queue uploads segments and points when online.
Task Completion Options (Initial)
- Completed.
- Completed + follow-up required.
- Blocked.
- Canceled.
- Rescheduled.
Unified Records Model (Draft)
- Record: core object with type, title, status, time fields, payload JSON.
- RecordEdge: parent and child relationships between records.
- RecordPoint: location samples tied to a record (route segment or visit).
- RecordBlob: attachments metadata (future photos or videos).
- RecordLegacyMap: map tasks and routes into records during migration.
- ServerState, SyncChanges, ConflictAudit for device restore and audit.
Scaling Notes
- Location data volume is high; batch inserts and consider daily partitions.
- Use company_id in every table to support future sharding or isolation.
- Short-term raw data, long-term aggregates to manage storage costs.
- Asynchronous jobs for sync processing and notifications.
Open Decisions (Revisit During Development)
- Distance threshold for sampling vs battery and data usage.
- Map provider: Google Maps (offline map needs TBD).
- Manual vs assisted mileage capture and vehicle identifiers.
- Conflict resolution rules for offline sync.
- User consent UX and privacy policy requirements.
- Notification cadence for check-ins and reminders.