Finite ride state machine
- Why
- Avoid fragile ad-hoc status flags and make invalid transitions explicit.
- Trade-off
- Adds upfront modelling, but makes testing and future policy rules easier.
← All work
Dissertation system
Volunteer Ambulance Coordination Platform
Low-acuity transport requests need clear ownership, controlled state, and an audit trail.
Request→
Assignment→
Status→
Closure→
Audit
React NativeExpress APISQLiteState MachineWCAGAPI TestsAudit Trail
RIDE REQUEST #014
statusPending → Accepted → EnRoute → PickedUp → Completed
ownernone → volunteer_07
events
- created_at
- accepted_at
- completed_at
- notification_sent
- audit_recorded
runtime rule
Second accept attempt → rejected
One ride through the system
One request enters. One volunteer owns it. Every state change is bounded. Every important event leaves evidence.
Request
POST /api/ride
Pickup, destination, reason, mobility note.
Assignment
Guarded accept.
One volunteer becomes the owner.
State
Finite transitions.
Terminal states block outgoing moves.
Communication
Notifications are sent and stored.
Payloads stay minimal.
Evidence
History, timestamps, role-aware reads, and tests make the workflow reviewable.
System layers
Supporting structure behind the lifecycle.
Request layer
patient ride requestpickup and destinationmobility notepending queue
Assignment layer
volunteer visibilityatomic acceptsingle ownerconflict prevention
State layer
RequestedAcceptedEnRoutePickedUpCompletedCancelled
Communication layer
Expo push tokenrequest/accept/complete notificationsnotification historyminimal payloads
Navigation layer
in-app route previewOpen in Maps handoffno in-app turn-by-turn navigation
Governance layer
audit recordsrole-aware readsprivacy minimisationaccessibility checkstest evidence
Technical decisions
Atomic accept endpoint
- Why
- Only one volunteer should own a ride request.
- Trade-off
- Keeps the MVP simple with a guarded update instead of complex dispatch logic.
Open in Maps handoff
- Why
- Users already trust native map apps for navigation.
- Trade-off
- Avoids maintaining fragile turn-by-turn navigation, but does not provide full in-app routing.
Expo notifications instead of chat
- Why
- Request, accept, and complete events need lightweight alerts.
- Trade-off
- Observable and simple, but delivery guarantees remain outside the MVP.
SQLite for MVP
- Why
- Fast development, easy reset, and in-memory test runs.
- Trade-off
- Suitable for dissertation testing, but a pilot would need managed relational storage, migrations, and audit-grade logging.
Constrained leaderboard
- Why
- Recognise volunteer contribution without turning healthcare-adjacent work into a growth loop.
- Trade-off
- Avoids heavier gamification until governance and safeguarding review.
Implementation
A patient creates a ride request with pickup, destination, reason, and optional mobility note. The server stores it as pending. Volunteers fetch pending rides and one volunteer can accept. Acceptance is guarded so a second accept attempt fails deterministically. The ride then moves through a finite state machine, while notifications and audit records make key changes visible.
API flow
- POST /api/ride
- GET /api/rides/pending
- POST /api/ride/:id/accept
- POST /api/ride/:id/complete
- GET /api/notifications/history/:userId
State machine
Requested → Accepted → EnRoute → PickedUp → Completed. Cancelled can be reached from active states. Completed and Cancelled are terminal.
Invariants
Evidence from the build
Measured claims from tests, checks, and governance framing.
State machine
27 Jest tests, 100% coverage.
Transitions, invalid moves, self-transitions, and unknown states are handled.
API
22 Supertest cases.
Register/login, ride lifecycle, double accept, repeat completion, role-scoped reads, notifications, and leaderboard.
Accessibility
Contrast CLI, target-size checks, focus visibility, accessibility screen.
The MVP considered WCAG 2.2 requirements from the start.
Performance
Cold-start p50/p95 measurement.
The app was measured against a defined p95 target rather than guessed.
Security / governance
Privacy minimisation, role-aware endpoints, STRIDE-style threat model, DPIA framing.
The system boundary and pilot risks were considered explicitly.
Pilot boundary
VAS is not a production transport service. It does not include identity proofing, DBS checks, insurance verification, geofencing, continuous GPS tracking, complex eligibility gating, or live operator tooling. Roles are controlled for the MVP, and usability evaluation was limited to lab-style testing and role-play because real patient evaluation would require ethics and governance approval.
Identity & safeguarding
No DBS, insurance, licence, or volunteer verification in the MVP.
Location & eligibility
No geofencing, continuous GPS, or complex eligibility gating.
Governance
No real patient evaluation without ethics, DPIA, privacy notice, and partner approval.
Infrastructure
SQLite is suitable for dissertation testing; a pilot would need managed storage, migrations, retention policy, and audit-grade logs.
Next iteration
- 01
Volunteer onboarding and verification
Identity checks, DBS where applicable, insurance/licence checks, safeguarding training.
- 02
Operator oversight view
Admin queue, manual intervention, no-show handling, anomaly review.
- 03
Managed data layer
Move from SQLite to managed relational storage with migrations, retention policy, and audit-grade logs.
- 04
Security hardening
Rate limits, structured errors, stronger auth, role administration, abuse monitoring.
- 05
Accessibility audit
External WCAG review, automated checks for labels/focus, wider device testing.
- 06
Pilot governance
DPIA completion, privacy notice, university/partner ethics, retention schedule, monitored pilot metrics.
What this project proves
I can take an operationally sensitive workflow and reduce it into actors, state, ownership, boundaries, tests, and evidence. This was not about building a mobile UI first. It was about making a coordination process legible enough to test, audit, and improve.