Introduction - Definitions, technologies, components and overall architecture
The Ocean Builder's Pod Management app is a complex software project that involves several components communicating with each other and it is actually an ecosystem formed by many different technologies, programming languages, code repositories and network protocols and offering a range of user experience depending on what is the user relationship with Ocean Builders, where is the user connecting from and what device is used to do so.
This documentation is intended for readers with general tech knowledge but not necessarily deep knowledge in any of the technologies involved. It will not go down to the implementation level. For details about specific implementations please check the related repositories in our GitHub organization.
In this introduction document we will give a general overview of the different components involved, how they are being implemented, what is their role in the overall system and how do they communicate with each other. We will then expand on each of those components in other documents inside this book.
Home Assistant at the core of our app's software
Home Assistant (HA from now on) is the open source home automation software that we rely on as a base for several of the features needed in our apps. It is fundamental that before digging deep into our documentation you get a basic understanding of what HA does and how it does it. We will be referencing different functionalities, code repositories, technologies and APIs related to HA all along this documentation.
Home assistant resources:
- Website: https://www.home-assistant.io/
- Github: https://github.com/home-assistant
- Demo showing HA capabilities https://home-assistant.io/demo/
- Documentation: https://www.home-assistant.io/docs/
- Tutorials: https://www.home-assistant.io/getting-started/automation/
USER ROLES
Our apps will be used by two main user groups:
- Ocean Builders customers and, in general, pod users. Users that need to manage their experience in one or more pods.
- Ocean Builders staff: administrators, customer support members and other. These are users that work for Ocean Builders and need to have supervisor or monitoring capabilities for one or more pods.
A user can also follow in both groups: a person working for Ocean Builders who also owns one or more pods and uses the same account for both their work activities and also as customer.
Ocean Builders pod users
Pod users will interact with the Pod Management app to manage their experience in one or more pods. This is a broad group of users that can have different relationships with the pods:
- Pod owner
- Pod guest
- Pod tenant
Ocean Builders staff
- Administrators
- Customer support
Architecture overview and components
There are several ways in which we can group the components of our deployment to offer different levels of description. We will start here with the most simple and simplistic classification by grouping several components into big features and we will later on offer a more in detail breakdown of each component.
User frontends
From the user point of view we are working on two main user-facing apps and everything that the user does not interact with could be considered "the servers".
- The Pod Management app: it is a fully customized version of the HA app and is the tool for users to interact with the pods. Users are not limited to manage a single pod, they can add several pods to manage and depending on their relationship with the pod and other factors, such as permissions given to them by the pod's owner or if they are inside or outside the pod, they will be able to control different devices and functionalities on those pods.
- The Ocean Builders Admin Dashboard: it is a frontend intended to be used by Ocean Builders staff only. This app gives an overview of the status of all the pods and allows to do monitoring and different levels of management of those pods. The levels of control a user can have over a pod will depend of several factors:
