<p>Let's kick things off with a quick peek at the web app — it's all about displaying a sleek and clutter-free dashboard, somewhat similar in functionality to <a href="https://www.home-assistant.io/">Home Assistant</a>. I intentionally kept the functionality limited to maintain that clean, minimalist design. IoT Dashboard is deployed on a Raspberry Pi and displayed on a simple tablet mounted in my house.</p>
<p><img src="/images/iotdashboard.webp" alt="Screenshot of IoT Dashboard"></p>
<p>If you'd like to visit the repository, the link is here <a href="https://github.com/szymonpulut/IoTDashboard/">https://github.com/szymonpulut/IoTDashboard/</a>.</p>
<h2>A Bit of Background</h2>
<p>This application has been on quite a journey. I first built it a few years ago using pure JavaScript and direct DOM manipulations. Then, as I was learning React in 2019, I felt it was time for a rewrite. This transition marked a significant milestone for me, as it really showcased the power and simplicity of React.</p>
<p>This current version is the third iteration of the app. My goal this time was to elevate it to a production-grade level. I also wanted to challenge myself by making it full-stack, using Node.JS for the backend and GraphQL for seamless frontend-backend communication.</p>
<h2>Big Picture Overview</h2>
<p>Throughout the development process for both UI and backend applications, I focused on a couple of core principles:</p>
<ol>
<li>
<p><strong>Modularity</strong>: The app needed to be fully modular, making it easier to understand and extend in the future.</p>
</li>
<li>
<p><strong>Streamlined Process</strong>: I automated the CI/CD process, adopting tools like <a href="https://www.conventionalcommits.org/en/v1.0.0/">Conventional Commits</a> with <a href="https://github.com/googleapis/release-please">Release Please</a>, along with <a href="https://prettier.io/">Prettier</a> and <a href="https://eslint.org/">ESLint</a> for code styling and rule enforcement. <a href="https://typicode.github.io/husky/">Husky</a> handles linting on commit. While automated testing wasn't a priority initially, I plan to add some basic coverage down the road.</p>
</li>
<li>
<p><strong>File Naming Conventions</strong>: Both frontend and backend codebases adhere to clear naming conventions, facilitating file location and organization.</p>
</li>
</ol>
<h2>Frontend: The User Interface</h2>
<h3>Overview</h3>
<p>The UI is neatly organized into sections, aligned with CSS grid display areas. Key features include a clock, weather forecast, air quality measurements, temperature sensor data from around the house, control functionality for front gates, and integration with a shared Google Calendar.</p>
<p>For local development, I stick to simple <code>npm</code> commands, while deployment is made easy with <a href="https://www.docker.com/">Docker</a> and <a href="https://docs.docker.com/compose/">Docker Compose</a>.</p>
<h3>Technical Details</h3>
<p>The frontend focuses on simplicity, as most of the heavy lifting is done by the backend. It's built with React and TypeScript. Styled with <a href="https://styled-components.com/">styled-components</a>, and utilizes <a href="https://www.apollographql.com/docs/react/">Apollo Client</a> for GraphQL communications. The frontend build process is powered by lightning-fast <a href="https://vitejs.dev/">Vite</a>.</p>
<h2>Backend: The Real Core</h2>
<p>My expertise lies more in frontend development, so this project has been a valuable learning experience. I learned a lot about backend architecture, coding in Node.JS, and implementing a GraphQL server.</p>
<h3>Apollo Server &#x26; GraphQL</h3>
<p>To maintain modularity, I relied on <a href="https://the-guild.dev/graphql/tools">@graphql-tools</a> and custom code to ensure flexibility in schema and resolver management.</p>
<h3>Modules</h3>
<p>Modules, housed in the <a href="https://github.com/szymonpulut/IoTDashboard/tree/55f15878f21f588b3aceaa883d6a3b697a0a8cd8/server/src/api">/api/ directory</a>, come in two types:</p>
<ol>
<li>
<p><strong>Internal</strong>: These modules interact with internal smart home systems, like <a href="https://github.com/szymonpulut/IoTDashboard/tree/55f15878f21f588b3aceaa883d6a3b697a0a8cd8/server/src/api/gateControl">front gate control</a>, using <a href="https://mqtt.org/">MQTT</a> for communication (MQTT is a message broker similar to RabbitMQ or Kafka, specifically optimized for IoT devices).</p>
</li>
<li>
<p><strong>External</strong>: These modules interface with external APIs, like the <a href="https://github.com/szymonpulut/IoTDashboard/tree/55f15878f21f588b3aceaa883d6a3b697a0a8cd8/server/src/api/weather">weather forecast</a>, primarily fetching data via REST APIs. Responses are parsed with <a href="https://github.com/colinhacks/zod">zod</a> for full type safety.</p>
</li>
</ol>
<p>GraphQL schemas are defined in <code>.schema.graphql</code> files, with exposed actions listed in <code>.resolver.</code> files. Actions themselves are in <code>.dataSources.</code> and <code>.mutations.</code> files (for fetching and mutating data, respectively). Internal modules may also have <code>.handler.</code> files in a <code>/handlers/</code> subdirectory for handling incoming MQTT system broadcasts.</p>
<h3>Custom Utilities</h3>
<ul>
<li>
<p><strong>Fetching</strong>: I've developed a <a href="https://github.com/szymonpulut/IoTDashboard/blob/55f15878f21f588b3aceaa883d6a3b697a0a8cd8/server/src/utils/fetchData.utils.ts">data-fetching function</a> for consistent integration with <code>zod</code> and <a href="https://github.com/szymonpulut/IoTDashboard/blob/main/server/src/utils/cacheManager.utils.ts">simple caching</a>.</p>
</li>
<li>
<p><strong>MQTT</strong>: The MQTT setup, detailed in the <a href="https://github.com/szymonpulut/IoTDashboard/tree/55f15878f21f588b3aceaa883d6a3b697a0a8cd8/server/src/mqtt">/mqtt/ directory</a>, includes pre-defined topics and mappings for subscriptions and mutations. Secrets are managed via <a href="https://github.com/szymonpulut/IoTDashboard/blob/55f15878f21f588b3aceaa883d6a3b697a0a8cd8/server/src/mqtt/mqtt.topics.secret.example.ts">mqtt.topics.secret - example</a>, avoiding hardcoded values.</p>
</li>
</ul>
<h2>Challenges Faced</h2>
<p>The journey wasn't without its hurdles. Here are a couple of interesting challenges I encountered:</p>
<ol>
<li>
<p><strong>Setting up TypeScript in the backend</strong> proved more cumbersome than expected due to Node.JS's limitations in this area. Overcoming issues with <code>tsconfig</code> as well as imports during build &#x26; dev flows was particularly challenging.</p>
</li>
<li>
<p><strong>On the backend’s side, managing multiple GraphQL resolvers and schemas</strong> posed tooling-related hurdles, which was especially evident with separate modules. While centralizing everything by hardcoding resolver addresses was an option, I aimed for an auto-detection system.</p>
</li>
<li>
<p><strong>Integrating OAuth APIs</strong> introduced complexities, especially since I was more accustomed to simpler authentication mechanisms like JWT. Testing the integration involved using the GraphQL layer and added to the perceived difficulty.</p>
</li>
<li>
<p><strong>Battling perfectionism</strong> might sound like a cliché, but it was a real struggle. It took so long for me to publish this article because there always seemed to be another item on the TODO list (that would make the project so much better and/or professional). In the end, I decided to “force-release” this article even though there are some unfinished aspects, as a way to push past that barrier 😉</p>
</li>
</ol>
<h2>TODO</h2>
<p>There's always room for improvement! Here's what's on my radar:</p>
<ol>
<li>
<p><strong>Introduce automated testing</strong>. This wasn’t yet a priority, since this is a non-customer-facing application that does not serve a critical role. However, I appreciate the comfort of working with well-tested code (being able to freely refactor and plan to invest some time in it.</p>
</li>
<li>
<p><strong>Move certain interactions (night &#x26; silent mode, webcam view) into a menu</strong>. As I'm more accustomed to desktop-oriented applications, deciding on the best approach for triggering/displaying the menu is still up in the air.</p>
</li>
<li>
<p><strong>Find out a better way to store MQTT-related secrets</strong> rather than a <code>.gitignored</code> <code>.ts</code> file. This issue is especially frustrating when setting up the development/build environment on a new machine.</p>
</li>
<li>
<p><strong>Apply refactors across both server &#x26; client applications</strong>. On the client side, using React Portal for the webcam modal is a starting point, along with improving the setup in <code>main.tsx</code> &#x26; <code>App.tsx</code> is on my list. On the server side, renaming <code>externalSchemas</code> into <code>DTO</code> would be fitting, as well as a few changes in tooling - better code generation from GraphQL schemas.</p>
</li>
</ol>
<h2>Conclusion</h2>
<p>The IoT Dashboard isn't just a project — it's a constant companion throughout my career journey. With its modular design and efficient data handling, I'm proud of how far it's come. But perhaps most importantly, I am proud because I use it in my everyday life 😁</p>
<p>Stay tuned for more tech insights and stories from my journey in the world of software development. Until next time, keep coding and exploring! 🚀👨‍💻</p>


Keyword Full-stack development

The Architecture Behind the IoT Dashboard