Get the phone running. Then make it sync.

One ordered path. Demo needs no cluster. Capella free tier is enough for App Services.

1. Three common field jobs — you configure which ones ship

This is not one phone doing field service, on-site work, and route delivery together. A mobile developer turns on the jobs a company needs with users.workModes[] (and related settings). Copy-on-write and freeze-on-complete stay the same. The three walkthroughs are example configs.

Assets

Field service

Jon Hale — work orders, map pins, inventory txs.

Walk a day →

Customer

On-site service

Maya Chen — finish the job, then write an order.

Walk a day →

Sales

Route delivery

Priya Shah — catalog prices, deliver, next stop.

Walk a day →

Index of all three · FAQ

2. Run the phone in demo

No Sync Gateway. Work stays on the device. Node ≥ 20. Not Expo Go — Couchbase Lite and MapLibre need a development build.

git clone https://github.com/Fujio-Turner/mobile_field_service.git
cd mobile_field_service
cp .env.example .env
npm install
npm test
npx expo run:ios -d "iPhone 16 Pro"
# or: npx expo run:android

.env.example sets EXPO_PUBLIC_AUTH_STRATEGY=demo. Sign in:

Login	Mode
`jon.hale@example.com`	`assets`
`maya.chen@example.com`	`customer`
`priya.shah@example.com`	`sales`

Any other non-empty id is treated as Jon. You land on Today with seed jobs once the database is open.

App repo · Every env flag · Auth

3. Create a Capella free-tier account

App Services runs on a Couchbase Capella operational cluster. Free tier does not need a credit card. One cluster per organization. It turns off after 72 hours idle and is deleted after 30 days off.

Capella free-tier account How to create the cluster

In Capella, create a Management API v4 key (Organization Owner or Project Owner). You will paste that token into Terraform or Ansible.

4. Deploy bucket, collections, App Services

The deployment repo is the source of truth for Capella. Shared model: schema/mfs.yaml + sync_functions/*.json. Do not create local.tmp on the server.

git clone https://github.com/Fujio-Turner/mobile_field_service_deployment.git
cd mobile_field_service_deployment

# Terraform free tier
cd terraform/free-tier
cp terraform.tfvars.example terraform.tfvars
# set auth_token, organization_id, database_credential_password
terraform init
terraform apply

# or Ansible
# cd ansible
# cp group_vars/all.yml.example group_vars/all.yml
# ansible-playbook playbooks/deploy-free-tier.yml

Apply creates App User jon.hale@example.com (role technician) when the app-user password vars are set. Capella → App Services → mfs-sync → endpoint mfs → Connect. Copy the public URL:

wss://<id>.apps.cloud.couchbase.com:4984/mfs

Deployment README · Database tree

5. Point the phone at App Services

Restart the development build after changing env. Login is still the email. The replicator uses a session cookie, not a password on every request.

EXPO_PUBLIC_AUTH_STRATEGY=basic
EXPO_PUBLIC_SG_URL=wss://<host>:4984/mfs
EXPO_PUBLIC_SG_DB=mfs

Sign in as jon.hale@example.com with the App User password from deploy. Today’s HUD turns green when the replicator is connected.

Replication · Session + 401 · Settings catalog

6. Then read, in this order

ArchitectureCollections, copy-on-write, freeze, queries. SchemasJSON Schema 2020-12 per collection. Do not invent field names. ReplicationAllow-list, push filters, channels, simple vs oneshot. AuthEmail is the SG username. Session TTL, Keychain. AGENT.mdProduct rules an implementer must not regress. RoadmapWhat shipped. Vector / CLIP is still off.

Canonical URLs

For coding assistants. llms.txt, this page, architecture, schema JSON, AGENT.md. Prefer these over scraping GitHub HTML. Three repos; do not mix them. Never put local.tmp in the replicator. Never invent schema fields.

https://mobile.fuj.io/llms.txt
https://mobile.fuj.io/docs/getting-started
https://mobile.fuj.io/docs/architecture
https://mobile.fuj.io/docs/schema/
https://mobile.fuj.io/docs/schema/common.json
https://github.com/Fujio-Turner/mobile_field_service
https://github.com/Fujio-Turner/mobile_field_service/blob/main/AGENT.md
https://github.com/Fujio-Turner/mobile_field_service_deployment
https://github.com/Fujio-Turner/mobile_field_service_pages

App code is mobile_field_service. Capella IaC is mobile_field_service_deployment. This site is mobile_field_service_pages (public/ is the live root). Markdown for most doc pages is copied from the app’s docs/ and guides/.

All documentation