Wayline: A ride-hailing app from three sides

Wayline is a sample app with a server behind it. A rider asks for a ride, the nearest suitable driver is offered it, both follow the trip on a map, the ride is paid for when it ends, and an administrator runs the service. The app and the server are one Maven project in scripts/wayline, written in Java on both sides, and the Initializr generates the same project under your own name.

This chapter is the user’s guide: what each of the three kinds of user sees and can do. Wayline: Building on the sample is the other half. It explains how the project is built and what to change to make it yours.

One app serves all three. The server gives every account a set of roles, and the app opens on the screen that fits them: a rider on the map, a driver on the driving screen, an administrator on the operations console. Someone who holds more than one role switches between them from the menu.

Start the server on its development profile and it creates a set of accounts, all with the password wayline-demo, and two weeks of rides so that the charts have something to draw. Running it has the commands.

Sign in as the rider in one simulator and as a driver in another to follow a ride from both ends.

No money moves on a server that hasn’t been given a payment provider’s key. Cards are simulated, and three numbers behave in three ways:

Any expiry date in the future and any security code work with them.

The welcome screen offers to sign in or to create an account. Server address is there for a phone on the same network as a development server: localhost on a phone is the phone, so the app has to be told where the server is.

Creating an account takes a name, an e-mail address, a mobile number and a password. The e-mail address is what you sign in with. Under I want to, you say whether you plan to ride or to drive. Choosing Drive doesn’t make you a driver; it takes you to the driving application once the account exists.

The app then asks for the six-digit code sent to the mobile number. A code is good for five minutes and five attempts, and a new one can be requested after half a minute. A server with no text-message provider configured can’t send a text, so on a development profile it shows the code on the screen instead. You can skip this step with Not now, but the server refuses a ride request from an account whose number isn’t verified.

Signing in is the app’s own form. Behind it, the app runs an OAuth 2.0 authorization-code flow against the server without opening a browser, and keeps the tokens it gets in the device’s secure storage. Signing out revokes the refresh token at the server.

After the first sign-in the app asks once whether it may share usage statistics: which screens are opened and which features are used, and never a name, an e-mail address, a phone number, a place or a card. Share usage statistics agrees and Not now declines, and the app works the same either way. The answer can be changed at any time in the settings.

A rider can:

The home screen is a map with a search card over it and a sheet at the bottom. The round button at the top opens the menu, and the one at the side puts the map back on where you are.

The map starts on where you are. While the device is still finding that, a notice at the top of the map says Looking for your location. If it has no answer after eight seconds, the notice becomes Still looking for your location. Try again. When the device can’t work out its position, the notice is Can’t find your location. Try again, and when the app has no permission to ask, it’s Location is turned off. Try again. Tapping the notice asks again. Until a position arrives the map shows the service’s default city, and you can still search for a pickup and a destination.

Pick a destination and the app draws the route and asks the server for a quote. The sheet lists the three kinds of ride with what each costs, how many it seats and how many minutes away the nearest one is. Under them is the way to pay, which you can change by tapping it. The price shown is the fare with the service fee included.

The quote is for information. When you ask for the ride, the server works the fare out again from its own prices and fixes it for that ride. A price change an administrator makes a minute later applies to the next ride, not to this one.

The server offers the ride to the nearest free driver who fits what you asked for. That driver has fifteen seconds to accept. If they decline or let the time pass, the next nearest is offered it, and after a short while the search widens from three kilometers to eight. If nobody takes the ride within a minute and a half the app says so, and nothing is charged.

Once a driver accepts, the sheet shows their name, rating, car and license plate, and the car moves on the map as the driver reports in.

Call and Message open the phone’s dialer and its messaging app, so they’re offered only on a device that can dial. Share opens the device’s share sheet with a sentence naming the destination, the driver and the car. Cancel ends the ride at any point before the trip starts. The sample charges nothing for a cancelled ride.

When the driver completes the trip the server charges the card, and the sheet asks how the ride was.

The tip is a percentage of the fare or, from the receipt, any amount. It’s a second charge to the same card, made once, and the whole of it goes to the driver. On a ride paid in cash the tip is recorded on the receipt and in the driver’s earnings, and no card is charged for it.

Wallet in the menu lists the saved cards and cash, which is always there. Tapping a card makes it the one that pays unless you choose otherwise when you ask for a ride. An account holds up to eight cards.

How a card is added depends on the server. With simulated payments the card is typed into the app. With a real provider the app opens the provider’s own page in the browser, so the card number never reaches the app or the server, and the app picks the result up when you come back to it.

Past rides are listed under Your rides. Pull the list down to load it again. Each ride opens a receipt with the trip, the driver and the fare broken into its parts.

A driver can:

Anyone with an account can apply, from Drive with Wayline in the rider’s menu. The application has five steps, and each is saved as you leave it, so an application can be finished later:

Each photograph comes from the camera or the gallery. The app shrinks it before sending, and the server accepts JPEG and PNG files of up to 1.5 MB.

Once sent, an application waits for an administrator. Until one decides, the applicant sees where it stands and goes on riding.

Approval gives the account the driver role, and the app opens on the driving screen from then on. A rejection comes with the administrator’s reason. The applicant can change what was wrong and send the application again.

The driving screen is a map with the day’s earnings at the top and a badge that reads Offline or Online. A driver starts offline. The sheet says You are offline and, under it, Go online to start taking rides.

GO puts the driver online. The badge changes to Online, the sheet says Looking for rides, and the app reports the car’s position to the server every few seconds. Go offline stops the offers. A driver who is online and stops reporting for a minute is no longer offered rides either.

An offer shows the fare, how far the pickup is and how long the trip is, with a ring counting down the time left to answer.

After accepting, the driver follows the route to the pickup, taps I have arrived, then Start trip when the rider is in the car and Complete trip at the destination. For a ride paid in cash the sheet says how much to collect.

A driver can cancel after accepting and before the trip starts. A trip that has started can only be completed, or cancelled by an administrator.

Earnings in the driver’s menu shows the balance ready to cash out, the totals for today, this week and this month, a chart of the last two weeks, the number of trips, the tips, the rating and the share of offers accepted. Under them are the payouts already made.

A driver earns the fare less the service’s commission, and every tip in full. Cash out asks for a bank account the first time: the holder’s name, the bank and the last four digits of the account number.

An administrator can:

The same screens are laid out in two ways. On a phone the console is one screen at a time with a menu. In a window at least 165 mm wide, which is a tablet, a desktop or a browser, it’s a console with its sections down the side and a list beside the item picked from it.

The dashboard opens with what needs attention, as buttons that lead to it, then the four numbers and the charts.

The lists of applications and of rides are loaded again by pulling them down. A desktop window has no such gesture, and its lists load when the section opens.

An application opens with everything the applicant entered and the five documents, each of which opens full size. Approve and Send back are at the end of it.

An account opens with its standing, its numbers, its contact details, the two role switches, the moderation buttons and its history.

The desktop build takes the look of the operating system it runs on, in its colors, fonts, and controls.

Applications lists them by status, and the one picked opens beside the list.

People has a search field and filters for riders, drivers, admins, flagged and blocked accounts.

Rides lists the most recent rides with their state: every ride, or only those under way, completed, or cancelled. A ride opens with the trip, the fare and how it was paid. From there an administrator can cancel a ride that hasn’t finished and refund one that was paid by card. A refund returns the fare, the service fee and the tip. A ride paid in cash has nothing to refund.

Payments lists what was charged for each ride, by which method and with what result.

Pricing holds the numbers every fare is worked out from: a base fare, a price for each kilometer and each minute, a minimum, the service fee added on top for the rider, the commission kept from the driver, and a multiplier for each of the two larger kinds of ride and for times of high demand. The currency is a setting of the server and isn’t changed here.

Live map fills the window with a map of the cars that are online, which move as their drivers report in.

The screens the console doesn’t own, such as the settings, keep their phone layout in a column in the middle of the window. An administrator is a rider too, and Riding under Switch to opens the rider’s map.

The Settings screen is in every role’s menu and is the same in each. What’s chosen there is stored on the server with the account, so it follows the user to another device.

The app is translated into English, Spanish, French, German, and Hebrew. Hebrew is laid out right to left. The theme follows the device, or is fixed to light or dark, and the map changes with it.

Usage statistics is the answer to the question asked after the first sign-in. Unlike the rest of the screen it’s kept on the device and not with the account, so each device has its own answer. While it’s off the app reports nothing. Deleting the account also resets the anonymous id the statistics carry.

Three of these settings are stored and do nothing more in the sample:

Deleting the account removes the sign-in, the profile, the saved cards and any driving application. The server refuses while a ride is under way.

The server can host the app itself, so that opening the server’s address in a browser is using the app with nothing installed. It’s the same app compiled to JavaScript, with the same screens.

A browser gives a page less than a phone gives an app, and the app says so where it matters. Calling and messaging are offered only where the device can dial. The map opens on a default position when the browser won’t say where it is.

Running it has the commands, and Hosting the app in the browser explains how a server hosts an app.