Technical Planning and Overview
This document will tackle what we've laid out in Phase 0 of the phases as described in the original planning document (currently the readme of the repo)
This document is focused on how we will build our backend and all the management services.
- How we will be building the management services
- How the source code will be structured
- How we plan on extending functionality / deprecating older functionality.
This is an important part since the services will be the major feature of the product. We are skilled at developing client applications, and stacked is our preferred architecture. In addition to the important things defined above we'll need to setup the backend in such a way that it's easy to unit test, easy to deploy, easy to manage, easy to update and easy to debug in the live production state.
This document and phase will be concluded when we have a detailed plan of the technical setup and technical architecture overview as well as the deployment and technology stack overview.
The first major thing we have to tackle is something that's already been decided. That is, which backend infrastructure to use. Given that this is geared towards a single fullstack developer or a small team we're going to use Firebase as the backend. It has everything we need to build and run a product. The backend functionality will provide us with Authentication, a reactive database and a series of cloud functions that allows us to build carts and check them out. Let's move on to the technical details.
This section covers the highest level of the technical overview. In this section we need to decide on the following:
- What language are we going to use for the backend Cloud Functions
- How will we "contain" the functions as one management service (if we'll even do that)
We will definitely use TypeScript for this. I have never used TypeScript before so will need a lot help from the community in order to ensure I'm not writing bad code. This will most likely be the slowest parts of the building given that I have no experience with the language, but I do understand firebase so that's a win in that scenario.
I don't think this is required. Given that we're using functions we can treat them all as separate idle micro-services (which they basically are). the only kind of management we'll do is to deploy them using a certain naming convention to help identify the functions, their functionality, version and what "group" they belong too.
We have the following backend management systems that we will map as follows when it comes to the endpoint urls:
- Order Management: /order/[endpointName]
- Product Management: /products/[endpointName]
- Payment Processor: /payments/[endpointName]
- Tip Processor: /tips/[endpointName]
- User Management: /user/[endpointName]
This will give us a clear indication on what we're calling and what group it belongs to. Another thing that's apart of "managing" the services is being able to track issues. We will build logging using Cloud Logging (previously known as StackDriver) into the cloud functions from the beginning and make sure that we're keeping the logs up to date so that we can always see what's happening.
This is quite an important part and also a confusing part to a lot of the beginners. I've found that source code structuring is confusing most of the time due to a lack of abstraction on the part of the developer at the source code level as well as a lack of understanding of the bigger picture. Given that we've done the high level overview we know that we have 5 different backend groups (I'll call it groups going forward for a more accurate representation of what it is) so we can structure our code in that way. We also know that above that level of abstraction we have two more levels. Client applications and Backend applications. We can use that to our advantage as well. So the structure that I think we should follow for this project is as follows.
This will split the source code into two high level sections, clients and backend. Clients connect users to the backend, backend is what runs the entire show. The backend is split into the appropriate group which will each have its own files, all connected to the same firebase project. It should be possible for multiple projects to be connected to the same firebase projects. When deploying cloud functions it deploys only the functions in the folder and leaves the rest running. One thing I am uncertain about which I'd like some help with in researching is if deploying firebase rules always overwrites the existing ones. The reason is because I'd like to write the rules for the different groups in their own group instead of having it all in one file. If that's not possible then we'll make another folder in the backend folder to maintain the security rules and their tests. The issue will be tracked and answered here.
This is a very important part of the process. There are two options here.
- Build all new functionality to be backwards compatible.
I like this because it keeps the API simple. I don't like it because it'll complicate the actual code for the function.
- Add the version into the cloud function url.
This keeps the code simple but increases the amount of code to maintain over time. I don't know which one is better but I'm leaning towards backwards compatible functionality at the moment.
To conclude this document here's what the technical overview looks like for our product.
- Clients will be developed in Flutter and Dart
- Backend groups of serverless functions will be developed in TypeScript
- Each of the groups will be maintained in its own folder with all its source code and deployment scripts
- If possible (research here) then i'd like each group to manage or at least house its own Firestore security rules.
- We'll use a backwards compatible implementation of API version management over adding the version into the name of the url (Need some input from more advanced backend developers).
Please use this thread to contribute to the discussion.
Just as a quick note on what's next to prime the think boxes:
- Establish how data will flow through the most important processes: This will be a step through of how a user will let us know what they want and how we populate that through the system. The smaller processes will all follow the example of the large and most important processes.
- Establish which data models will be required to get the information accross
- Establish which data collections will be required to get this information through our system to our restaurant clients and consumer clients