Building LOMSY With Flow, Part 1
This is the first part of a series of posts. Instead of writing a “boring” tutorial with a fictional project, I decided to write down some steps on the journey of actually building a little side-project. I hope you can use my explanation for something and would be very happy to hear from you - both if you liked it, or if you spotted a mistake or have a comment to improve.
What the heck is LOMSY?
LOMSY is the short version of “Lunch ordering and management System”. But why is that needed? The wife of one of our employees started to cook lunch for the whole team about twice a week which is liked very much by the audience. So far, the process for ordering a meal was mainly a manual one:
- she decides about the date + menu that is offered
- she prints a sheet of paper with the offering and 10 empty lines
- this ordering-sheet is placed in the kitchen of the office + everyone can note his name to actually order lunch
- the ordering-sheet is taken home, ingredients get organized and the meals cooked
- the next day, the meals are taken to the office and everyone enjoys his lunch and pays the fee for it
There is nothing wrong in doing it that way - it basically works. But there are some shortcomings that are the primary reason to think about building a web-based app to optimize the processes a bit:
- the ordering sheet is placed in the office-kitchen for about 2-3 days - if an employee misses that because of holidays or other reasons, there won’t be any lunch order possible e.g. for the next week
- she who cooks has no direct insight into the amount of meals that were ordered and how her offering was accepted by the audience - unless her husband brings the ordering-sheet back home
- cash management is an issue: either there is not enough cash available physically that day, or only in bigger sheets and there’s not enough money in smaller units to give cash-back - this leads to a manual overhead: either accepting pre-payments or dues and to keep track of them
- the audience is the team of a web-agency - very interested in having online-possibilities, thus they’d prefer to be able to order online, pay online and not having to care about having physical money around the particular day
Planned features
So after thinking about the whole area of topics and the existing procedures, the following list gives an overview about the planned features:
Consumer-Role
As a consumer, I want to
- create a user account
- login/logout to/from my user account
- see the current and upcoming offerings
- place my orders
- pay the meal online
- cancel a pre-ordered meal if order-deadline is not over yet
- deposit some money in my customer account (via online payment)
- see my balance online
- be able to deposit money by cash (will be booked by an administrator, but get’s visible in the account of the consumer and it’s balance)
Administrator-Role
As an administrator, I want to
- login as an administrator
- create meals and offerings
- describe the meal
- set the price
- optionally upload a picture
- set the max. number of meals
- set the order-deadline
- set the date of delivery
- print an ordering-sheet with a QR-code on it
- see real-time list of orders per offering
- get an e-mail as soon as the order-deadline is over with a list of orders
- see a list of consumers and their balance
- be able to book manual cash-payments
- be able to update the status of each offering/order (e.g. change status from “ordered” to “delivered”)
Preparations - my personal approach so far
My approach to plan and prepare an application starts usually with a User Story Mapping workshop with a list of desired features as an outcome. The next step is then to think this through to condense a Domain Model out of it that is capable of storing the needed data to support the processes and features later on. The last step of preparation is then to think of the “architecture” of the application, decide on the technology to use. The last step of preparations is then to find building-blocks that exist already, before trying to develop stuff again and again, if there is just something around that can be re-used.
So let’s go through these steps shortly:
User Story Mapping
Well, to be honest I’ve skipped this step for this tiny side-project as it seemed to be kind of an overkill: There are just two “roles” or types or users and it was OK to just list the features as outlined above.
Just one thing remains where User Story Mapping would have helped probably: Slicing out the MVP (Minimum Viable Product) from the list above… Of course this is possible, but it would be easier to be done in the visual approach of User Story Mapping I guess.
For slightly bigger projects, I’ve already used the online tools Stories on Boards and craft.io - but even more the paper version, while discussing with both team members and stakeholders.
Domain-Model
Coming from those features in a rough state, we condensed the following Domain-Model out of it:
Having a User-Model seems to be obvious, but there were some thoughts that might not be obvious directly: Of course, we could let the Balance-Object away and just have transactions per User directly - but having the Ubiquitous Language in mind, having a Balance-Object around when talking about a User’s Balance seems to fit for me. Having the OnlinePayment-Model around is just a precaution as I guess the online payment part will have/bring this kind of Object with itself anyway.
Architecture
As said, for this project, the architecture is rather simple and easy to overview: There will be one server covering the full functionality, contain both the end-user and the administration part of the application. So the interactions look probably like this:
Technology decision
Since the whole application of LOMSY will be web-based and running on a webserver with not much of related/external systems to communicate with, the technology decision was pretty simple:
- it will run on a single Linux based Webserver
- we use PHP as a base
- we’ll use Flow as PHP framework and base
- we’ll use a smallish CSS framework as a base for the grid-system
- if there is a need to automate/animate stuff via JavaScript, we’ll probably use jQuery
- we’ll use Gulp.js to automate the build-steps for the frontend stuff (CSS/JS)
- we’ll use Git and Gitlab to version the code
- we’ll use Gitlab CI to trigger deployments of the whole application via Surf
Regarding the CSS Framework: We’ve used Bootstrap for a long time - but recently started thinking and discussing about replacing Bootstrap with something more light-weight. Since we’re basically only using the grid system anyway, any smallish grid system will do the job for us. So LOMSY also serves as a demo project that other/smaller CSS frameworks can do the job (hopefully).
I’m pretty sure, the whole application could also be built with Ruby (on Rails), C#, Node.js or with any other PHP framework. But: We’ll use the stuff we know and where we can go on fast, which leads to reaching the MVP faster, thus delivering revenue of the project faster - so since we’re using PHP and Flow regularly, the base setup is already decided without much discussion.
Building-Blocks
Thinking through the functionality of LOMSY, I’ve listed a bunch of areas where probably a building block is already available for re-use (e.g. as a PHP package we can include), instead of building that part ourselves:
- user registration
- user login/logout
- online payment
User Management
The guys from Sandstorm Media have published sandstorm/usermanagement which seems to be pretty fresh, and compatible with Flow v4.x (at least in the dev-branch). This one should cover all our needs regarding registration, password reset and login/logout.
Online Payment
After discussing several ways, we’ve decided to try to implement Stripe for now - they seem to deliver all the fancy stuff needed to implement it into any application - but we’ll have to try and test that first. This means: There’s no finished Flow/PHP package around, so we’ll have to drill together some wires probably.
QR-code generation
Well, the first entry that packagist.org shows is bacon/bacon-qr-code which seems to be used pretty often given the number of downloads - so I’ll give that one a test-drive…
PDF generation
I’d like to keep this part pretty simple - focus is on getting to a result fast, not visual perfection. So I’d like to give famelo/pdf a test run and see how easy it will be to generate PDFs with that.
Next step
Next step will be to kickstart the base application, read on in the 2nd part of this blog post series.