Home · Docs · Roadmap

Mobile Field Service — Roadmap

This is a Fujio-Turner offline-first field app (Expo + cbl-reactnative fork, CBL 4.x EE target + vector index). Repo: https://github.com/Fujio-Turner/mobile_field_service. Walk a mode day before implementing screens: assets, customer, sales. Auth: AUTH.md. Settings: guides/SETTINGS.md.

How to read checkboxes:

PRs 00–05 are a linear spine. After that, photos / tasks / map / inventory / chat can overlap; the replicator PR waits until outbound + children + messages exist so push filters are real. “Independently mergeable” means each PR leaves the app building; it does not mean 06–14 can land in any order.

Phase 0 — Docs and constraints

• Apache-2.0 LICENSE
• React Native / Expo / native .gitignore (Windows entries = dev machines, not a runtime)
• Architecture: collections, copy-on-write, queries, sync matrix (DESIGN.md)
• Day-in-the-life use cases: assets, customer, sales (DAY_IN_LIFE.md)
• Schemas: docs/schema/
• This roadmap + PR plan
• Engineering guides: logging, UI, release, replication (guides/)
• AGENT.md; tests live in tests/; local slices in gitignored work/
• README: EE license, Expo development builds, iOS/Android only, CBL via Fujio-Turner/cbl-reactnative (4.x EE target on the fork)

Exit: an engineer can implement without inventing field names, prefixes, or SQL++.

Phase 1 — App shell and session UI

• Expo SDK 52, RN 0.76.9 (SDK 52 pin), Node ≥ 20, newArchEnabled: true
• iOS 15.1+, Android API 24+ (expo-build-properties)
• Expo Router: Login, Today placeholder, Profile
• Login UI (email or username + password) — AUTH.md
• EXPO_PUBLIC_AUTH_STRATEGY=basic|oidc_implicit|oidc_code|demo (default basic; .env.example uses demo)
• Keychain/Keystore session + expiry; RefreshAuth; replicator 401/404 → re-auth (session write/restore/logout in PR-01; mint + 401 path with replicator)
• Phone-first tabs; large-phone / small-tablet safe areas
• Camera / location usage strings in app.json (runtime prompts in later PRs)
• Jest (or equivalent) test runner wired
• “Development build required” if the native module is missing

Exit: installable iOS/Android binary; demo login navigates to Today (seed jobs on a development build).

Phase 2 — Encrypted database, collections, seed

• CblReactNativeEngine singleton
• Open mfs_<safe>_<hash8> with AES-256 string key from Keychain + FileSystem.getDefaultPath()
• Create scope field (fourteen collections including messages, orders, rates, taxes, tracking) + local.tmp
• Value + FTS indexes from DESIGN.md
• stampAuditCreate / stampAuditUpdate / stampHistory (unix seconds, app version, path from/to, lat/lon when GPS)
• ULID + prefixes (woin, woout, ast, prd, inv, invtx, usr, cus, tsk, nte, msg, ord, rate, tax, tmp) + tracking track:{day}:{employeeId}
• Users seed with employeeId + email (channel emp:E-4412)
• Optional JSON seed: three inbound jobs (WO-10470 / 10482 / 10490), assets, van stock, products, rates, taxes, user + dispatch user, Hartford customer, one inbound order. Skip KV loop if seed markers already exist.
• tmp in scope local; replicator allow-list cannot include it; expiration helper
• RebuildStock read-model stub (no stock save)
• Guard screen if the native module is missing (Expo Go)

Exit: cblite / VSCode CBL inspector shows field.workordersin seed docs with audit stamps.

Load: seed ≤ 20 jobs, ≤ 200 assets, ≤ 50 products — small enough for first-run demo, not a district dump.

Phase 3 — Today list + KV detail

• ListTodayWork: inbound assignedTo.employeeId = $employeeId, status != 'cancelled' AND status != 'superseded', scheduled.day = $day, ORDER BY scheduled.startDt DESC with numeric LIMIT/OFFSET (CBL Mobile rejects IN [...] and $limit)
• Reassigned / Assignment changed badge when inbound assignee ≠ session but local outbound exists
• Page 0 merge of active outbound: workordersout status = 'assigned' OR status = 'in_progress' OR status = 'blocked' — no day filter; unpaged; collapse one row per source.id preferring outbound
• Infinite scroll (offset += 20) on inbound only
• Live query on inbound and active outbound page 0; coalesce (~50 ms); skip FindOutboundForSources for sources already in the active-outbound set
• Empty / error / stale-sync states (stale-sync waits on replicator)
• Batched FindOutboundForSources (OR of source.id = $sN, max 20) → openId + openCollection on each row
• Row tap → one KV get on openCollection (S04)
• Read-only inbound detail screen (S04); Start work pinned in a bottom dock
• query.explain() opt-in via EXPO_PUBLIC_QUERY_EXPLAIN=1 (not every query in __DEV__)
• Today header clock + seconds countdown (src/ops/todayClock.ts)

Exit: scrolling 40+ seed jobs stays on the indexed plan; tap does not re-query the list.

Latency: today list p95 < 50 ms local; KV p95 < 10 ms.

Phase 4 — Copy-on-write

• StartWork: copy workordersin → workordersout (new woout:<ulid>, role: primary, owner: technician)
• Reject start if inbound assignedTo.employeeId ≠ session
• Clone inbound taskIds templates into type:'task' instances
• Idempotent reopen via idx_woout_source (employeeId, source.id, role=primary)
• Race: duplicate copy discarded; oldest audit.cr.dt wins
• Provenance source.* with full body snapshot minus embedding / blobs
• No writes to workordersin (dispatch)
• Today screen routes started rows to app/wo/out/[id] using openCollection
• Metric mfs_copy_on_write_total
• StartWork rejects inbound cancelled / superseded
• CreateWorkOrderIn: new woin: origin: field, assigned to self; never patch dispatch inbound

Exit: double-tap Start opens one outbound id; dispatch inbound JSON unchanged; field-created inbound pushes; Today tap on a started job KV-gets the out doc.

Phase 5 — Outbound editor, status, Submit (no camera yet)

• Status machine: assigned → in_progress ⇄ blocked → complete / cancelled
• Operation statuses pending | in_progress | done | skipped (schema). Field UI toggles done ↔︎ pending (DoneToggle: outline vs filled) — does not cycle in_progress/skipped on tap
• Editable operations + embedded checklist (same outline/filled buttons)
• CompleteWork gates required operations status === 'done' and required checklist done === true (required tasks added in the tasks PR)
• CancelWork with reason (tech); dispatch cancel is inbound-only
• SubmitWork only after complete/cancel; sets syncState=ready_to_push
• Complete/Cancel set owner: backend and freeze the body (no notes/photos on that id)
• CreateAmendment: new woout with role: amendment, amends.id
• history[] on user saves (path + from/to + dt + lat/lon); skip SetSyncState
• Dispatch-updated banner (inbound KV vs snapshot; no auto-merge) — Reassigned / assignment-changed banner is in
• Reassigned banner on an in-progress copy whose inbound assignee changed

Exit: a tech can start, edit ops, complete, freeze, submit, and open a follow-up paper fully offline (without photos).

Phase 6 — Photos and local.tmp

• Camera runtime permission
• Camera → StagePhoto (local.tmp, 24 h expiration) → CommitPhoto
• Top-level blobs photo:<id> + photo:<id>:thumb (not array paths)
• Cap 20 photos/job; compress 200–800 KB; strip EXIF
• Delete photo; periodic compact
• No embedding enqueue

Exit: 10 photos on a job survive process death; local.tmp staging expires.

Storage: 10 photos × 400 KB ≈ 4 MB/job; 15 jobs/day ≈ 60 MB/day photos. v1 cap is the only growth control.

Phase 7 — Tasks and notes

• tasks instances + templates; CompleteWork gains required-task predicate
• notes job/general; FTS on notes; 409 on frozen parent
• New notes/tasks copy parent readyToPush if parent already submitted (editable only)
• Push-filter expressions for notes/tasks documented for the replicator PR

Exit: CompleteWork refuses a job with an open required task; notes cannot land on a frozen WO.

Phase 7b — Chat

• field.messages collection, prefix msg:
• Job thread thr:wo:{woinId} and DM thr:dm:{empA}:{empB}
• SendMessage readyToPush: true (not gated on WO Submit)
• Chat tab + job-scoped composer from outbound editor
• Push filter + emp: / wo: channels documented for the replicator PR

Exit: airplane-mode send appears after radio returns; completing a WO does not freeze the thread.

Phase 8 — Assets map

• MapLibre RN + OpenFreeMap Liberty when online
• Document: basemap needs network / last style cache; pins from CBL work offline
• BBox query idx_ast_geo; cluster; tap → KV asset
• Filters: type, near job, near GPS
• “Use asset on this job” writes assetIds on woout (needs PR-05+)
• Location permission
• Follow-up (not this phase): region MBTiles pack

Exit: map shows seed pumps/sites; pin opens KV detail; airplane mode still shows pins.

Phase 8b — Location crumbs (tracking)

• Collection field.tracking, id track:{YYYY-MM-DD}:{employeeId} (device-local day; not email)
• RecordTrackPoint when haversine ≥ EXPO_PUBLIC_TRACK_MIN_MOVE_M (default 100 m; 152 ≈ 500 ft)
• Map tracking keyed by unix seconds → [lat, lon]; cap 4000/day; last [lat, lon, ts] for O(1) compare
• GetTrackingDay / GetTrackingLastNDays(n=7) — seven KV gets, no query
• Push filter always true; never log the map
• Foreground / while-using only in v1 (background trail later)
• TTL 30 days after day (expiresAt + setDocumentExpiration)

Exit: moving ~100 m+ writes a point; last 7 constructed ids KV-get; still docs do not dump crumbs.

Phase 9 — Products and inventory

• Catalog browse + FTS (idx_prd_fts)
• Van stock list (locationId of current user)
• ConsumeInventoryOnWork: write only inventory_tx + woout.materials (never save stock rows)
• Display qty = pulled qtyOnHand + SUM(qtyDelta WHERE inventory_tx.audit.cr.dt > snapshot.audit.up.dt)
• RebuildStock read model (no writer)
• Insufficient stock error; allowNegative only supervisor / technician_lead
• v1: one van per technician; stock not pushed and not saved; inventory_tx push when readyToPush

Exit: consuming a valve on the job writes invtx: and a materials line; van list shows snapshot + txs newer than snapshot.audit.up.dt; crash between tx and materials is repaired via appliedToWo only.

Phase 9b — Orders, rates, taxes, field customers

• Pull rates + taxes; never save those catalogs
• ListTodayOrders / StartOrder (copy inbound → working; never mutate inbound)
• CreateOrder origin: field; PriceLines integer cents
• CompleteOrder freeze + CreateOrderAmendment
• CreateCustomer origin: field (do not patch pulled customers)
• Optional orderId on delivery WOs; workOrderOutId on orders taken on site
• Seed: one inbound order, two rates, one tax, Hartford customer

Exit: sales-mode Today lists an inbound order; copy + complete does not change inbound JSON; walk-up creates cus: + ord:.

Phase 10 — Sync

• Lab SG/App Services fixture documented in DESIGN (collections field.* except tmp, session auth, channels emp:{employeeId})
• SessionAuthenticator after POST /_session (default); optional BasicAuthenticator or Authorization: Bearer header (AUTH.md)
• Replicator change listener: 401 / 404 / 10401 → OnReplicatorAuthFailure
• await Replicator.create; collection allow-list; local.tmp not included
• RN "show source" push filters (never-push for pull-only; woout/notes/tasks/tx as specified)
• No JS pull-filter functions in v1 (optional channels: string[] per collection; default empty)
• addDocumentChangeListener → syncState pushed / push_error
• Feature-detect pending-ids; else COUNT ready_to_push
• Sync status on Profile; foreground restart
• Operator sync bar: connected / not connected + last synced / pending push / downloading
• Profile Large screen optimize (optional right-thumb zone + Left hand checkbox)
• ReconcileDuplicateOutbound on pull
• Channels sketch; SG sync function is external
• Per-collection pull channels: string[] on CollectionConfig (default empty = no client filter)
• Profile Settings / debug: versions, DB path, replicator URL/status/last times, collection counts, start/stop/restart, channel editor
• Build-time replication schema simple (continuous all field.*) vs oneshot (bootstrap workordersin+orders, then periodic + foreground one-shots). Not a Profile toggle.

Exit: lab SG round-trip: pull inbound, push submitted outbound + blobs + txs.

Phase 11 — Search, polish, observability

• FTS notes / products / assets
• Structured logs (no PII/doc dumps)
• Metrics: query latency, copy-on-write, blob bytes, replicator
• Database compact on idle after photo deletes
• Customer history (local complete workordersout)

Phase EE — Vector similarity (gated)

Binding: Fujio-Turner/cbl-reactnative feat/vector-search-support (VectorIndexConfiguration). Official @couchbase/couchbase-lite-react-native 1.1 does not expose vector search — do not use it.

Still needed: native CBL 4.x bump on that fork if not already, and on-device MobileCLIP runtime (model size, NNAPI/CoreML). Lab/testing does not require an EE license.

• Lock MobileCLIP-S2 512-d (embedding.clip512)
• On-device embed at CommitPhoto only in this phase
• Never write clip512: []
• Create vector index when API exists (cosine, dim=512, centroids ≈ √N)
• APPROX_VECTOR_DISTANCE(embedding.clip512, $vec)
• Similarity screen behind VECTOR_SEARCH_ENABLED && nativeVectorApi
• No production JS brute-force cosine over the full catalog

Phase future — POD signature

• Signature capture (name + blob) on complete/deliver, in addition to photo proof
• Store as top-level blob on working workordersout / orders, not nested arrays

Non-goals on this roadmap

• Web / Windows / macOS app
• SAP adapter, Zeus Hub, sibling ops dashboard
• koten-ai branding or remotes
• P2P CBL sync
• Passwords in CBL
• Mutating dispatch inbound workordersin (field origin: field create is allowed) or reopening a completed workordersout id
• POD signature pad (photo proof now; see Phase future)
• Credit card payment at order create (later; catalog snapshot only in v1)
• Inventory reservation / “out of stock” on create (assume plenty)
• Customer-facing chat
• Official @couchbase/couchbase-lite-react-native 1.1 as the binding SoT
• Offline MBTiles as a v1 requirement
• Offline login after Logout

PR Plan

Ordered, independently reviewable PRs. Each PR should build, typecheck, and leave the app runnable (stub screens allowed until their PR). 00→05 must land in order. After 05, 07/08/09/10 can overlap; 11 (replicator) waits for 07 and 10 so notes/tasks/tx filters exist. Completeness of push filters is extended in 07/10 if 11 were started early — do not start 11 early.

PR-00 — Docs

PR-01 — Expo app shell + login UI

PR-02 — CBL open, collections, audit, seed

PR-03 — Today list query + pagination

PR-04 — KV inbound detail

PR-05 — Copy-on-write StartWork + Today routing

PR-06 — Outbound editor + status + Submit

PR-07 — Photos + local.tmp

PR-08 — Tasks and notes

PR-09 — Assets map

PR-16 — Tracking crumbs

PR-10 — Inventory and products

PR-11 — Replicator and sync UI

PR-12 — Observability and FTS search chrome

PR-14 — Chat / messages

PR-15 — Orders, rates, taxes, field customers

PR-13 — EE vector similarity (later)

Merge notes

• Spine: 00 → 01 → 02 → 03 → 04 → 05.
• After 05: 06 (editor + freeze + amendment) then 07 (photos). 08 (tasks/notes) can parallel 07. 09 (map) depends on 05, not 04. 16 (tracking) after 09 location permission (collection exists from 02). 10 (inventory) depends on 06. 14 (chat) can parallel 06+ after 02/05.
• 11 (sync) after 07 + 08 + 10 + 14 + 15. If filters must land incrementally, extend src/sync/filters.ts — but prefer 11 last among them.
• 15 (orders) after 02; reuse freeze UX from 06.
• PR-06 CompleteWork ships without the required-task predicate; PR-08 adds it in the same operation.
• No PR may add Web or Windows runtime targets.
• No PR may write passwords into CBL, mutate dispatch inbound WOs/orders, reopen a completed outbound/order id, nest blobs in arrays, or replicate tmp.
• Prefer Fujio-Turner/cbl-reactnative over official 1.1. Native 4.x + vector live on that fork.
• No PR may brand this as koten-ai.