DEV Community: Dean Andreakis

Principles of Software Architecture

Dean Andreakis — Tue, 28 Jan 2025 03:35:00 +0000

Principles of Software Architecture

In the fast-paced world of technology, crafting a solid software architecture is crucial for creating applications that stand the test of time. If you're in the software development arena, you've likely come across three key principles: scalability, maintainability, and modularity. These principles are the backbone of any successful software system, helping ensure it remains robust and adaptable. Let's break these concepts down in a way that's both practical and relatable.

Scalability

Scalability is all about ensuring your software can handle growth, whether it's a surge in users or an increase in data volume. Imagine your favorite app suddenly slows down or crashes when it becomes popular—that's a scalability issue.

Horizontal Scaling : The ability to add more machines or instances to distribute the load, often employing techniques such as load balancing and clustering to spread traffic effectively.
Vertical Scaling : Enhancing the capabilities of an existing machine, such as increasing CPU or RAM, which is generally simpler but eventually hits physical limitations.
Design Considerations : Architect systems using stateless components where possible, allowing for easier distribution across multiple machines. Opt for technologies and frameworks that natively support scaling.

Below is a simplified diagram of an example of Scalability. By prioritizing scalability, architects can ensure long-term performance and user satisfaction as demands increase.

Maintainability

Maintainability deals with how easy it is to update and fix your software over time. Think of it like organizing a closet—easy-to-reach shelves and clearly labeled boxes make finding things a breeze.

Separation of Concerns : Break down functionality into distinct sections, each responsible for a specific aspect of the application. This approach reduces complexity and makes code easier to understand and maintain.
Clean Code Practices : Write code that is not only functional but also readable and well-organized. Use meaningful variable names, consistent formatting, and comprehensive comments where necessary.
Automated Testing : Incorporate unit and integration tests to catch bugs early and make refactoring less risky. Tests should be automated to ensure they are run consistently.

A maintainable architecture facilitates quicker updates and reduces the risk of introducing errors during enhancements.

Modularity

Modularity is about dividing your software into separate, interchangeable parts, much like building something with LEGO bricks. Each piece is self-contained, but together, they create your masterpiece.

Decoupling : Design modules with minimal dependencies on each other. When modules are loosely coupled, changes to one module have minimal impact on others.
Reusability : A well-modularized system enables reusing components in different parts of the application or even in different projects.
Plug-and-Play : Design systems where new modules can be easily integrated, and existing modules can be replaced with minimal impact on the overall system.

By embracing modularity, architects enable flexibility in development and deployment, allowing systems to adapt more quickly to change.

Conclusion

Whether you're sketching out a new project or refining an existing one, keeping these principles in mind will guide you toward building stronger software. Scalability, maintainability, and modularity aren’t just buzzwords—they’re the stepping stones to creating systems that are ready for whatever the future holds. By weaving these principles into your work, you're setting your software up for success, both today and in the long haul.

Secrets Management w/ Firebase App Hosting and NextJS

Dean Andreakis — Mon, 20 Jan 2025 21:00:00 +0000

Definition

I am using Firebase App Hosting as a backend for a NextJS app that I am developing. I am also using the Firebase CLI to configure and manage my Firebase project. One of the many challenges along the way was how to manage secrets within the app. Secrets can be anything you determine to be sensitive information such as:

API Keys: Tokens used to authenticate requests to an Application Programming Interface (API). They grant access to services and should be kept confidential.
Passwords: Credentials used for user authentication to access systems or services. These should be stored securely, usually hashed.
Private Keys: Cryptographic keys used for encryption, signing, or authentication processes. These should be kept confidential at all times.
Encryption Keys: Keys used to encrypt and decrypt data. These must be securely stored to prevent unauthorized access to sensitive data.
Access Tokens: Tokens that grant access to specific resources or systems, often used in OAuth and other authentication protocols.
Database Credentials: Usernames and passwords used to connect to databases. These should be kept secure to prevent unauthorized database access.
Certificates: Digital certificates that authenticate the identity of systems and encrypt data. Private certificates should be kept secret.
SSH Keys: Used for secure shell (SSH) access to servers. The private SSH key should remain confidential to ensure secure server access.
Webhooks Secrets: Tokens or keys used to validate and secure webhooks communication.
Personal Identifiable Information (PII): When it's part of the application code or logs, it's considered sensitive.

Problem

Common best-practice is to not commit secrets to a repository and instead use a method to allow for referencing of the secret in production that does not reveal the actual secret value.

It is common during development to put secrets in a local environment file that is not committed to a repository. One way to do this is to include a reference to the environment file in the .gitignore file of the project. This method is less than ideal during production as the environment file containing the secrets would have to be managed outside of git (or whatever configuration management tool used).

Solution

The solution for production is to use the Secret Manager service that is part of Google Cloud Platform. If you login to the GCP console and search for "Secret Manager" you should see something similar to the below screenshot:

Click on "Create Secret" and it should take you to a page where you can add the necessary information as seen below:

Once you add a new secret in the GCP secret manager then you can go back to your project directory and enter the following command in a terminal using the firebase cli tool:

firebase apphosting:secrets:grantaccess -b <firebase-project-backend-name> <name-of secret>

Lastly, you can then add a reference to the secret in your projects apphosting.yaml file:

env:
  - variable: <name referenced by your code>
    secret: <name of secret from GCP secret manager>

Your code can now reference the secret as follows:

const secret = process.env.<name-of-secret>

Deploying a Shopify Node App Docker Image to GCP

Dean Andreakis — Fri, 10 Sep 2021 15:36:58 +0000

In my last post I showed how to take a Shopify node app and dockerize it. In this post I will show you how to take that docker image and deploy it to GCP using Google Artifact Registry and Google Cloud Run services. I will also show the Shopify app configuration, installation and execution in a Shopify development store used for testing.

Prerequisites

We will assume that:

A GCP account has been created at console.cloud.google.com
A project has been created in GCP for your Shopify app
The gcloud CLI has been installed
The docker CLI has been installed

Setup Google Cloud Platform (GCP)

We will first setup GCP to accept and store the docker container image and then to deploy and run that image on Google Cloud Run.

An overview of these steps can be found here but I will show the specific commands for my dockerized Shopify node app named "shnode":

In IAM add the Artifact Registry Administrator role to your GCP user.
Go to the Artifact Registry service and make sure the API is enabled.
In the Artifact Registry select the "create a repository" button. Make sure you select type "Docker" for the repository type.
Authenticate to the repository as follows:

gcloud auth configure-docker us-west4-docker.pkg.dev

where us-west4-docker.pkg.dev is the location of the repository we created. We can see this information in the list of repositories:

Tag your docker image as follows:

docker tag shnode us-west4-docker.pkg.dev/shopify-319117/shnode/shnode:1.0

where the format is us-west4-docker.pkg.dev/my-gcp-project/my-repo/my-image:tag1

Push the container to GCP Artifact Registry:

docker push us-west4-docker.pkg.dev/shopify-319117/shnode/shnode:1.0

Create a GCP Cloud Run service: Go to GCP Cloud Run and select the "create a service" button. Once you create a service you will be able to see the URL of the service. We will refer to this URL as HOST in the next section where we setup the Shopify app itself:
Deploy the image to GCP Cloud Run and start it up:

gcloud run deploy --image us-west4-docker.pkg.dev/shopify-319117/shnode/shnode:1.0

Setup Shopify App

The Shopify node app must be setup properly in order for it to be installed and executed in a Shopify store. We will assume that the Shopify app has already been created in your Shopify partner account.

Go to the App setup page for your app in your Shopify partner account and make sure the URL's in the URLs section match the HOST URL from above when we created the GCP Cloud Run service:
In your Shopify partner account install the app to your development store using the "test your app" section of the app details page:
The Shopify app source tree itself includes a .env file that has a HOST environment variable. Make sure this matches the HOST URL from above when we created the GCP Cloud Run service. If you update this .env file then you will have to rebuild your docker image and re-deploy. To rebuild go to the root of your Shopify app source tree and issue the following command:

docker build -t shnode .

where "shnode" is the image name. At this point you can continue the deployment from the above section "Setup Google Cloud Platform (GCP)" where we tag the docker image.

Dockerizing a Shopify Node App

Dean Andreakis — Thu, 08 Jul 2021 21:17:08 +0000

I am in the process of learning to develop apps for the Shopify platform. In doing so, I wanted to establish early on how I would be deploying and managing my apps. I recently earned my GCP Professional Cloud Architect certification so I was pretty sure I would be using GCP in production. I decided that the easiest way to deploy and manage my apps in production would be to containerize them using Docker. If your not familiar with what a container is I highly recommend reading this overview on the docker site. TLDR; a container packages a software application and its dependencies so that it can execute across different environments without the need to pre-configure those environments.

Let's get started!

Pre-requisites:

Initial Steps

I started by following along the Shopify quick start guide that shows you how to use the Shopify CLI tool to quickly create an app and install and run it on a Shopify development store. I won't go thru the steps here but I do recommend going thru them yourself.

Once you have followed the Shopify quick start guide as described above, you will have used the Shopify CLI tool to create an example app and then to also serve it up on your local development system. The commands that the quick start guide uses are as follows:

shopify node create
shopify node serve

The first command scaffolds a new Node.js app in a subdirectory and creates your app in the Shopify Partner Dashboard.

The second command starts an ngrok tunnel, updates the .env file in your app project, updates information about the app in the Shopify Partner dashboard and then actually starts the app locally.

Go ahead and issue these two commands per the guide and see that your app is running in your development store. Next, stop the app from executing locally once you have verified it working in your development store.

In our case we want to package our app into a docker container and then execute that container.

Docker

We first need to create a file called 'Dockerfile' in the root of our apps project directory. Here is a Dockerfile that I created that will work with the Shopify quickstart app:

FROM node:16.4
WORKDIR /app
COPY package.json /app
RUN npm install --production --legacy-peer-deps
COPY . /app
RUN npm run build
CMD npm run start
EXPOSE 8081

It is also good practice to create a .dockerignore file also in the app project root so unnecessary items don't end up in the docker image:

Dockerfile
.dockerignore
node_modules
npm-debug.log

Once we have these files in place, go ahead and issue the following command in the root of your project app directory. This will create the Docker image for the app:

docker build -t <project_name> .

Here is a screenshot of the command output:

At this point the Docker image for the app has been created. We can now run the app in the container with the following command:

docker run -p 8081:8081 <project_name>

You should be able to go back to your Shopify development store and see the app running. Note that the '8081:8081' part of the command specifies the PORT that the Docker image will listen on. In the case of the Shopify quick-start example the PORT is defaulted to 8081.

We now have a Docker image of our Shopify app that we can either run locally using the Docker desktop tool or deploy to the cloud and execute there. This makes the job of deploying the app much easier as we won't have to worry about configuring a server. In my next post I will talk about using GCP Container Registry and GCP Cloud Run to manage and execute my app containers.

Last Notes and Gotchas

It is important to note that because we worked-thru the Shopify quick-start example first, the details of creating an app locally, configuring the app in the Shopify Partner dashboard, starting ngrok, updating the .env file in the project etc. are taken care of behind the scenes by the two (2) shopify CLI commands I mentioned earlier:

shopify node create
shopify node serve

If we were starting a new app and wanted to create a Docker image for that app we could just issue the commands above first as in the guide and then go back and create the Dockerfile and build the image as defined above.

Alternatively, we may just want to issue the first command (shopify node create) and then take care of everything else ourselves instead of issuing the second command (shopify node serve). In that case we have a few things to take care of before building the Docker image:

Execute ngrok http <PORT> where PORT is the port your apps server is listening on.
Update the .env file in the app project: The 'HOST' variable needs to be updated with the URL that ngrok displayed above.
Update the .env file in the app project: The 'SHOPIFY_API_KEY' and 'SHOPIFY_API_SECRET' must match the values from the app information in the Shopify Partner dashboard.
Update the app information in the Shopify Partner dashboard. The app url and app redirect url(s) must be updated to match the ngrok url:
Install the app into your Shopify development store by visiting the following url in your browser: https://<ngrok_url>/auth?shop=<store_name>.myshopify.com

Great SVG Resource for your next Web App

Dean Andreakis — Tue, 16 Feb 2021 21:33:41 +0000

I found myself working on a React app the other day and needing to add some style and interest with images. I am not a designer so any help I can get in making a web app look professional is greatly appreciated. I decided since the web app should be responsive I would use SVG images. SVG (or Scaleable Vector Graphics) is an XML-based vector image format for 2D images.

Using them in a React app is fairly easy:

import React, { Component } from "react";
import example from '../assets/img/example.svg';
import './example.css';

class Example extends Component {
    render() {
      return (
        <div>
          <div className="img-part" >
            <img src={example} alt="example" />
          </div>
        </div>
      );
    }
  }

  export default Example;

Advantages to using SVG images are:

They rescale perfectly as a user resizes the application.
Since SVG is XML-based it is a good candidate for lossless data compression algorithms which can mean much smaller file sizes for your images.
Since SVG is XML-based the image file is directly editable and is also easily edited by vector image programs such as Inkscape.

In my search for a good set of SVG images I came across unDraw. Undraw is a set of SVG images from designers that wish to contribute to the open source community. I was very impressed with the beauty, style, and huge selection of SVG images. An example of one of the images is the cover photo of this blog post.

One of the unique things about this set of SVG images is that you can adjust the color of the images as seen here:

unDraw also includes a very good keyword search tool which makes it easy to find images that fit with the subject matter of your app:

The license for unDraw is very permissive as the TLDR; is

you can use the illustrations in any project, commercial or personal without attribution or any costs. Just don’t try to replicate unDraw, redistribute in packs the illustrations or create integrations for it.