Back in 2020 a friend pinged me with questions about building apps:
Where do I find developers to build an app?
What's a good price for asking someone to build an app?
Do you have any recommendations for individual developers or shops?
I had heard these questions before. He'd been asking a variations of the same questions for about 2 or 3 years. Each time I tried to send him to some online portal, or link him to dev shops in the Philadelphia area I knew. I couldn't take on doing extra work.
But it was 2020 the world was in turmoil and I suddenly found myself with more time to listen to his problem in detail. So we got on a zoom call with his dad and brother (who would become my primary contacts moving forward as they were closer to the business)
The details are as follows: The family owns some gas stations, they have an existing loyalty program that they use with a few other partner gas stations, but want to take it to the next level to stay competitive and innovate. Their current off the shelf solution provider couldn't meet their needs.
They wanted to have more granular controls over how the loyalty program works. The ability to control how individual stores accumulated loyalty or issued discounts, and even offer individual customer or sectors custom loyalty rates.
They tasked me to build something new.
Deciding to build
After our first meeting I told them that I'd get back to them if I could help out. Up to that point of my life I'd built:
- A series of mostly terrible GeoCities/AngelFire websites.
- One of which was a paid $50 gig for a Chess Club at Community College.
- A stalled project for selling bleach and other chemicals online for this "business man" I somehow got connected to. I ran away as fast as I could after for our second meeting the location was a conference room where he was pitching a Pyramid Scheme.
- A stalled project for a furniture store that I think I just forgot about in true teen fashion. They may have also stopped responding to emails. Memory lost to the haze of time.
- A backyard bird store webpage that one of my professors put me onto. I got paid $625 in 2009 dollars.
- After a year I got a short and terse message from the owner asking me to take it down since they went out of business.
- A gym website that a friend from college asked for some help with. ~ $900 in 2013 dollars.
- Also got taken down after a year or so.
I'd built a handful of far more intricate and novel things for work as part of teams, but what they were asking for was more than I'd done on my own.
But it felt within reach. So I decided to jump in.
Big Picture Goals
The big picture was this: Customers were issued mag stripe cards that contained a 18 digit number, their card number. Customers could then top up value to this card, and then spend it at gas stations who participated in the loyalty program.
Customers with a card could gain one of two loyalty benefits:
- Customers who could accumulate loyalty onto their account when they spent money from their loyalty card
- Customers who would get an instant discount at the pump every time their used their loyalty card
Customers falling into category 1, accumulating points could then eventually spend those points like cash value. For example spending $100 on gas using your card, could get you $1 in credit that you could then spend at any station using the loyalty system.
They also wanted the ability to put their finger on the scales to have granular control of what percentage discount or rate of accumulation each store would have. So Store A could have a 2% instant discount, but Store B could at the same time have a 5% discount.
Additionally they wanted the ability to run promotions that could be at specific stores, and even the ability to offer individual customers, or sectors of customers a different rate, at different stores.
In addition to the core business controls they wanted, they would also require the ability to have a point of sale machine read cards that gas station attendants could use easily to open up a customer account, view their balance, do a transaction and print a receipt. The devices also needed to print a Batch Receipt which summarized an attendants activities for their shift
The head office also needed some light reporting of what devices were doing; the ability to get transaction data for specific stores and specific dates.
Also everything a POS machine could do, the head office wanted to be able to do it from a desktop computer.
Plenty to do.
Getting started — The Project Brief
I started digging in to ensure I understood all the requirements, which at a surface level seem straight forward enough, but the devil could trip you and steal your lunch money in the dark details.
It took about 3 meetings to get a full understanding of all of their business needs, understanding what they were truly asking for, and helping them understanding things they didn't even consider that would need to happen such as a migration of all their customers from an old platform to a new platform.
Eventually I sent them a project brief which detailed every minute detail of the program as I had understood it.
The project brief contained a description of terms, an overview of the problem, user stories; for customers, store attendants, head office workers; a system overview, a timeline and cost and payment terms. Some user stories included:
Randall signs up
Randall adds value to his loyalty card
Randall uses his cash balance
Randall uses his loyalty balance
Randall loses his card
Randall uses his card around the island
Tom fills up
Bob fills up
TVC controls the rewards
New promotional rate set
A Non-JMS station signs onto the Fuel Card Loyalty Program
Shana ends her shift
TVC issues a credit to Shane’s Plumbing services
TVC sets up a master card for a business
Theo reviews the sales
Existing users are imported
Each of the names in the user stories(Randall, Tom and Bob) represented different types of users
They came back with one or two revisions, but then once we agreed that the project brief covered everything, it was time to get started.
Getting started — Getting a device
The first thing we did was order a POS device. A lot of this system was going to center around the device.
Their current system Verifone devices. We quickly moved away from these as an option because:
- Support wasn't great
- Documentation wasn't clear on how we could build custom apps on it.
- Just seemed like a lot of sales and marketing talk from all their public docs
- Devices were expensieve
- Just a complete unknown of what I would be getting myself into
I needed to find a device that met the requirements:
It must be programmable (to allow the Loyalty Application to run on it)
It must be portable
Can read magnetic stripe cards
Optionally can read cards via NFC
Can print a receipt
Can connect to the internet via WiFi or a cellular connection
I narrowed it down to 3 options:
A tablet that had an external mobile printer and mag strip reader.
Pros:
- Faster development environment
- WiFi and cellular built-in
Cons:
- Cumbersome, not quite handheld
The PowMr POS Receipt Printer 58mm.
Pros:
- Built-in printer
- WiFi and cellular
Cons:
- No built-in magstripe reader
Pros:
- Built-in magstripe reader
- Built-in NFC reader
- Built-in Printer
- Built-in EMV (chip) reader
- WiFi and cellular
Cons:
- Limited customer support options
In the end we chose the Xeumior device. It had every thing we needed all in one device, and we were willing to gamble a little on importing it from China.
Another pro the Xeumior device had going for it was that it was Android based, which meant programming for it could be done in Java, which I felt more comfortable to work in compared to Swift, which I didn't have much experience in past Hello World.
I had some exposure to Objective C building a store finder for a previous job, but I didn't have fond memories of Objective C.
Getting started — Building the backend
The next step was figuring out the server side that the devices would talk to.
For me that was an easy decision: Django.
I felt very comfortable in Python, and Django just let's you get stuff done with little fuss.