Repository navigation
Architecture and Design Document
This document describes and clarifies the architecture and design of the MacroTouch application. This application is designed to allow users to set up a remote device to trigger customized macros on a host computer to help enhance ease of use and efficiency of computer usage. This document helps to clarify the design choices and decisions made for the construction of this software.
Our major components include an Electron desktop application, a mobile controller website, a master server, and an action server, as diagrammed here:
An interactive version of this, along with lower levels, can be found here
As this software is intended as a self-hosted or "homelab" application, some aspects of reliability will be outside of our control. With that said, the most basic, single-host installation that we provide will be expected to be reliable and fully functioning out of the box. Our reliability practices include:
- Separate, single concern modular components
- Communication across components through standardized websockets and HTTP APIs with shared type definitions
- Centralized component lifecycle management through the master server to ensure all parts are running properly
- Thoroughly tested macro actions across Linux, Windows, and Mac operating systems
We focus on minimalist, simple design using robust communication methods across local-only networks. We foresee no performance bottleneck issues in any aspect of our service due to these two facts our our design.
Our functionality, as detailed in our system requirements documents, will be fully implemented and tested. Any additional functionality desired by the user will be made available through a actions plugin system.
Other existing solutions are either abandoned, designed for other purposes, or expensive commercial offerings. This is a purpose built, simplicity-focused solution meant to fill the hole left by the existing products for open-source casual enthusiasts looking for a capable and robust solution.
All of our major components are based upon cross-platform technologies that enable seamless compatibility across all major desktop operating systems. The one aspect that does require intentional compatibility, individual OS action implementations, has a clear and explicit pattern for implementing each OS. The action plugin system also ensures that this product will be capable of integrating with nearly any 3rd party software.
This product is highly modular, strictly type-defined, and expandable. As a fully locally hosted, open source application, there is no absolute lifespan or expected end of service. While up to individual team members to continue, there is no planned maintenance after December 2026, the time when it will fulfill its primary purpose as a class project.
As a self-hosted application, there is no hosting service to be deployed to. Deployments are made by running the existing package building script and hosting the compiled executables on GitHub.
As an open source project, support is not guaranteed long-term, though is available through documentation and GitHub issues. This project is also easily forkable and plugin extendable for any community member that would like to customize, upgrade, expand, or repair the software.
There is zero cost to this software. All development is provided on a volunteer basis and there is no hosted services accumulating costs.
- Vue.js and Nuxt
- A Nuxt web application provides the desktop application (wrapped in Electron) and the mobile controller webpage. This allows for a shared UI codebase across both the desktop app and the mobile controller, along with natural support with any and all devices that can run a web browser. Additionally, this allows for the modularity needed for a multi-device server based setup (a "homelab" configuration).
- Node.js
- Our various servers all run within Node.js, allowing seamless cross-platform support, as well as an extensive library of packages that further enable our actions capabilities and cross-platform tooling.
- Platform-specific action implementations
- Not all OS platforms provide the same level of control and customization, meaning that we may run into issues with implementing some actions on certain platforms
- Network Communications
- This product is designed to only work over local networks which simplifies many aspects, but also leaves the product at the mercy of the network configuration. Designing a fully robust network handling system may be difficult across unknown and unusually configured networks.