DEV Community: Bagas Hizbullah

Crafting A Minimalist Portfolio Website with SvelteKit and Pico CSS

Bagas Hizbullah — Sat, 14 Oct 2023 10:50:20 +0000

Creating a portfolio website can be a practical way to showcase resumes, projects, and blogs. As someone who leans more towards backend development, I found myself in the situation of wanting to establish an online presence without drowning myself into the complexities of React or dealing with the manual development with plain HTML, CSS, and JavaScript. It was in the search for a simpler alternatives that I found Svelte, and its meta-framework, SvelteKit.

The simplicity of Svelte's syntax, its templates, and its approach to frontend development, which relies on compilation rather than a virtual DOM, has won me over. And then there is SvelteKit, an extension of Svelte that simplifies the process of building websites, which made it a great choice for my portfolio website project. It offered a perfect balance between simplicity and powerful functionality that aligns well with my preferences.

However, the question of CSS styling remained. The vast ecosystem of Tailwind CSS, with its extensive class-based utility system and configurations, felt kind of overwhelming for my needs. On the other hand, creating styles entirely from scratch using pure CSS felt time-consuming and inefficient.

My search for a middle ground led me to Pico CSS, a minimalist CSS framework with a unique approach to styling. What makes Pico CSS different is its focus on elegant styling without the use of classes. Instead, it encourages the use of semantic HTML tags to implement predefined styles rather than abusing <div> tags with CSS classes, making it an interesting choice for those who prefer to keep their HTML clean and meaningful.

In this blog post, I will try to explain the technical aspects of how I utilized SvelteKit and Pico CSS to create a portfolio website that effectively presents my resume, projects, and blogs.

Initiate SvelteKit Project

Getting started with a SvelteKit project is a straight-forward process. The easiest way is to run npm create command:



npm create svelte@latest my-app

It will scaffold a new project in the my-app directory, asking questions to set up some basic tooling such as TypeScript. However, I'm using JSDoc for this project, because it is good enough for my needs.

SvelteKit follows conventions that encourage efficient code organization. There are two basic concepts:

Each page is a Svelte component.
Create more pages by adding files to the src/routes directory of the project.

I used the index page for my resume. Then, I created 2 specific directories, blogs and projects, along with their mandatory +page.svelte and +page.server.js files. These files served as the components that rendered the content for my /blogs and /projects pages respectively.



src/routes/
├── blogs
│   ├── +page.server.js
│   └── +page.svelte
├── +error.svelte
├── +layout.svelte
├── +page.svelte
└── projects
    ├── +page.server.js
    └── +page.svelte

3 directories, 7 files

Additionally, I added a +error.svelte file for rendering custom error messages when needed.



<script>
    import { page } from '$app/stores';

    /** @type {Record<number, string>} map of status codes to emojis */
    const emojis = {
        400: '❌', // bad request
        401: '🔒', // unauthorized
        403: '🚫', // forbidden
        404: '🔍', // not found
        500: '🛠', // internal server error
        502: '🔌', // bad gateway
        503: '🔧', // service unavailable
        504: '⏳' // gateway timeout
    };
</script>

<section id="error" class="container">
    <h1><strong>{$page.status}</strong></h1>
    <h2>{$page.error?.message}</h2>
    <span id="emoji">
        {emojis[$page.status] ?? emojis[500]}
    </span>
</section>

<style>
    h1,
    h2 {
        margin-bottom: 1rem;
    }

    #error {
        display: flex;
        flex-direction: column;
        justify-content: center;
        align-items: center;
        text-align: center;
        margin: 0rem;
    }

    #emoji {
        font-size: 10rem;
    }
</style>

For static data, I put them as a JSON object inside src/lib/store.js file.



/**
 * Experience data for the resume.
 *
 * @type {Array<{
 *   job: string,
 *   url: string,
 *   company: string,
 *   start: string,
 *   end: string,
 *   description: Array<string>
 * }>}
 */
export const experiences = [
// ...
];

/**
 * Volunteering data for the resume.
 *
 * @type {Array<{
 *   job: string,
 *   url: string,
 *   company: string,
 *   start: string,
 *   end: string,
 *   description: Array<string>
 * }>}
 */
export const volunteering = [
// ...
];

/**
 * Social data for the resume.
 *
 * @type {Array<{
 *   href: string,
 *   rel: string,
 *   fa_class: string,
 * }>}
 */
export const socials = [
// ...
];

/**
 * Education data for the resume.
 *
 * @type {Array<{
 *  school: string,
 * url: string,
 * major: string,
 * start: string,
 * end: string,
 * description: string
 * }>}
 */
export const educations = [
// ...
];

/** Font Awesome icons name for the skills data. */
export const skills = [
// ...
];

/** Workflows data for the resume. */
export const workflows = [
// ...
];

/**
 * Awards data for the resume.
 *
 * @type {Array<{
 * place: number,
 * suffix: string,
 * host: string,
 * competition: string,
 * translation: string
 * }>}
 */
export const awards = [
// ...
];

/**
 * Certification data for the resume.
 *
 * @type {Array<{
 *  title: string,
 * credential_id: string,
 * credential_url: string
 * }>}
 */
export const certifications = [
// ...
];

I also put all the necessary component files inside the src/lib/components directory.



src/lib/components/
├── BlogCard.svelte
├── EduCard.svelte
├── Footer.svelte
├── JobCard.svelte
├── Navbar.svelte
├── ProjectCard.svelte
├── SkillsCard.svelte
└── SocialIcon.svelte

1 directory, 8 files

And for JavaScript files, I put them in the src/lib/scripts directory.



src/lib/scripts/
├── minimal-theme-switcher.js
└── redis.js

1 directory, 2 files

Styling with Pico CSS

To get started with Pico CSS, all I had to do was install it via npm by using the straight-forward command:



npm install -D @picocss/pico

After that, I included it into my project by importing it in the +layout.svelte file, specifically inside the <script> tag.



<script>
    // ...
    import '@picocss/pico';
    // ...
</script>

And that was basically it. I was able to use Pico CSS's elegant styles for all native HTML elements without the need for classes, enhancing the overall aesthetics of my website.

I also borrowed some code from Pico CSS's example code for a theme switcher by manipulating the data-theme attribute for the <html> tag using JavaScript. I placed the code inside src/lib/scripts/minimal-theme-switcher.js file.



/*!
 * Minimal theme switcher
 *
 * Pico.css - https://picocss.com
 * Copyright 2019-2023 - Licensed under MIT
 */

/**
 * Minimal theme switcher
 *
 * @namespace
 * @typedef {Object} ThemeSwitcher
 * @property {string} _scheme - The current color scheme ("auto", "light", or "dark").
 * @property {string} menuTarget - The selector for the menu element that contains theme switchers.
 * @property {string} buttonsTarget - The selector for theme switcher buttons.
 * @property {string} buttonAttribute - The attribute name used for theme switcher buttons.
 * @property {string} rootAttribute - The attribute name used for the root HTML element to store the selected theme.
 * @property {string} localStorageKey - The key used to store the preferred color scheme in local storage.
 */
export const ThemeSwitcher = {
    // Config
    _scheme: 'auto',
    menuTarget: "details[role='list']",
    buttonsTarget: 'a[data-theme-switcher]',
    buttonAttribute: 'data-theme-switcher',
    rootAttribute: 'data-theme',
    localStorageKey: 'picoPreferredColorScheme',

    /**
     * Initialize the theme switcher.
     *
     * @function
     * @memberof ThemeSwitcher
     */
    init() {
        this.scheme = this.schemeFromLocalStorage || this.preferredColorScheme;
        this.initSwitchers();
    },

    /**
     * Get the color scheme from local storage or use the preferred color scheme.
     *
     * @function
     * @memberof ThemeSwitcher
     * @returns {string|null} The color scheme ("light", "dark", or null).
     */
    get schemeFromLocalStorage() {
        if (typeof window.localStorage !== 'undefined') {
            if (window.localStorage.getItem(this.localStorageKey) !== null) {
                return window.localStorage.getItem(this.localStorageKey);
            }
        }
        return this._scheme;
    },

    /**
     * Get the preferred color scheme based on user preferences.
     *
     * @function
     * @memberof ThemeSwitcher
     * @returns {string} The preferred color scheme ("light" or "dark").
     */
    get preferredColorScheme() {
        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
    },

    /**
     * Initialize the theme switcher buttons and their click events.
     *
     * @function
     * @memberof ThemeSwitcher
     */
    initSwitchers() {
        const buttons = document.querySelectorAll(this.buttonsTarget);
        buttons.forEach((button) => {
            button.addEventListener(
                'click',
                (event) => {
                    event.preventDefault();
                    // Set scheme
                    this.scheme = button.getAttribute(this.buttonAttribute) || 'auto';
                    // Close dropdown
                    document.querySelector(this.menuTarget)?.removeAttribute('open');
                },
                false
            );
        });
    },

    /**
     * Set the selected color scheme and update the UI.
     *
     * @function
     * @memberof ThemeSwitcher
     * @param {string} scheme - The color scheme to set ("auto", "light", or "dark").
     */
    set scheme(scheme) {
        if (scheme == 'auto') {
            this.preferredColorScheme == 'dark' ? (this._scheme = 'dark') : (this._scheme = 'light');
        } else if (scheme == 'dark' || scheme == 'light') {
            this._scheme = scheme;
        }
        this.applyScheme();
        this.schemeToLocalStorage();
    },

    /**
     * Get the current color scheme.
     *
     * @function
     * @memberof ThemeSwitcher
     * @returns {string} The current color scheme ("auto", "light", or "dark").
     */
    get scheme() {
        return this._scheme;
    },

    /**
     * Apply the selected color scheme to the HTML root element.
     *
     * @function
     * @memberof ThemeSwitcher
     */
    applyScheme() {
        document.querySelector('html')?.setAttribute(this.rootAttribute, this.scheme);
    },

    /**
     * Store the selected color scheme in local storage.
     *
     * @function
     * @memberof ThemeSwitcher
     */
    schemeToLocalStorage() {
        if (typeof window.localStorage !== 'undefined') {
            window.localStorage.setItem(this.localStorageKey, this.scheme);
        }
    }
};

Then, I used it in the Navbar.svelte component within the <script> section, utilizing Svelte's onMount feature.



<script>
    import { ThemeSwitcher } from '$lib/scripts/minimal-theme-switcher';
    import { onMount } from 'svelte';

    onMount(() => {
        ThemeSwitcher.init();
    });
</script>

Font Awesome Icons

Utilizing Font Awesome icons in my project was easy. By integrating the Font Awesome Kit, I have access to a vast icon library that covers various categories, from social media icons to common UI elements. Even though using the kit may not be the fastest way to render icons on the web, the flexibility of the kit allows me to select and combine icons that blend seamlessly with my website's design, adding aesthetic value and a better user experience.

Fetch Blogs Data from Dev.to API

For populating my /blogs page with my published blog articles, I utilized Dev.to's API as provided in their documentation. I included a username query parameter with my username as the value:



https://dev.to/api/articles?username=bagashiz

This query allowed me to get my published blog articles from the API and integrate them into my /blogs page on my portfolio website.

To enhance user experience and website performance, I implemented a strategy where I returned the data as a streamed promise.



import { env } from '$env/dynamic/private';

/** @type {import('./$types').PageServerLoad} */
export async function load() {
    const url = env.BLOG_URL;
    return {
        streamed: {
            /**
             * @type {Promise<Blog[]>} blogs - Array of dev.to blogs
             */
            blogs: new Promise((resolve) => {
                fetch(url)
                    .then((res) => res.json())
                    .then((blogs) => {
                        resolve(blogs);
                    });
                }
            })
        }
    };
}

This approach allowed me to render the page with a placeholder before the actual blog data was fetched.



<script>
    import BlogCard from '$lib/components/BlogCard.svelte';

    /** @type {import('./$types').PageData} */
    export let data;
</script>

<section>
<!-- ... -->

    {#await data.streamed.blogs}
        <article aria-busy="true" id="skeleton" class="outline">
            <strong>Fetching data...</strong>
        </article>
    {:then blogs}
        {#each blogs as blog}
            <BlogCard {blog} />
        {/each}
    {:catch}
        <article id="skeleton" class="outline">
            <strong>Uh oh! Failed to fetch data.</strong>
        </article>
    {/await}
</section>

<style>
/* ... */
</style>

This approach not only ensured a smooth and responsive user experience but also provided an nice way to handle the loading of external data.

Fetch Projects Data from GitHub GraphQL API

To populate my /projects page with information about my pinned GitHub repositories, I utilized GitHub GraphQL API. This API allows for more specific and efficient data retrieval compared to traditional REST APIs.

However, fetching data from the GitHub GraphQL API involved a slightly different process. Instead of using simple GET requests, I needed to use the POST method. To specify the data I wanted to retrieve, I included a GraphQL query in the request body:



{
  user(login: "bagashiz") {
    pinnedItems(first: 6, types: REPOSITORY) {
      nodes {
        ... on Repository {
          name
          description
          url
          primaryLanguage {
            name
            color
          }
          stargazers {
            totalCount
          }
          forks {
            totalCount
          }
        }
      }
    }
  }
}

This query allowed me to request my pinned GitHub repositories, such as repository names, descriptions, stars and forks count, primary languages, and links.

Additionally, I also needed to add a bearer token to the Authorization header of the request. This token was generated using a GitHub personal access token with the necessary permissions, including access to public repositories and the ability to read all user profile data.



import { env } from '$env/dynamic/private';

/**
 * @type {string} url - Github GraphQL API endpoint
 */
const url = 'https://api.github.com/graphql';

/**
 * @type {string} query - GraphQL query to fetch pinned github repositories
 */
const query = `...`;

/** @type {import('./$types').PageServerLoad} */
export async function load() {
    const key = 'projects';
    const token = env.GITHUB_ACCESS_TOKEN;
    const reqInfo = {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            Authorization: `bearer ${token}`
        },
        body: JSON.stringify({ query })
    };

    return {
        streamed: {
            /**
             * @type {Promise<Project[]>} projects - Array of GitHub projects
             */
            projects: new Promise((resolve) => {
                    fetch(url, reqInfo)
                        .then((res) => res.json())
                        .then(({ data }) => {
                            const projects = data.user.pinnedItems.nodes;
                            resolve(projects);
                        });
                }
            })
        }
    };
}

Caching API Data with Redis

To make data retrieval efficient and minimize the need to request data from the API on every page load, I implemented a caching strategy using the ioredis package, which is a popular redis client for Node.js for interacting with a Redis database.



import { env } from '$env/dynamic/private';
import { Redis } from 'ioredis';

/**
 * @type {Redis} redis - Redis client instance
 */
const redis = new Redis({
    host: env.REDIS_HOST,
    port: parseInt(env.REDIS_PORT || '6379')
});

redis.on('error', (error) => {
    console.error(`Error initializing redis client: ${error}`);
});

export default redis;

For caching strategy, I implemented the Cache-Aside pattern. This process involves fetching data from an external API, storing it in the Redis cache, and using the cached data for the next request. I also configured the cache to expire after an hour, making sure to keep it efficient and up-to-date.



const key = 'blogs';
// ...
return {
    streamed: {
        /**
         * @type {Promise<Blog[]>} blogs - Array of dev.to blogs
         */
        blogs: new Promise((resolve) => {
            redis.get(key).then((data) => {
                if (data) {
                    const blogs = JSON.parse(data);
                    resolve(blogs);
                } else {
                    const timestamp = new Date().toISOString();
                    console.log(`[${timestamp}] Cache miss, getting data from dev.to API`);

                    fetch(url)
                        .then((res) => res.json())
                        .then((blogs) => {
                            redis.setex(key, 3600, JSON.stringify(blogs));
                            resolve(blogs);
                        });
                }
            });
        })
    }
};
// ...



const key = 'projects';
// ...
return {
    streamed: {
        /**
         * @type {Promise<Project[]>} projects - Array of GitHub projects
         */
        projects: new Promise((resolve) => {
            redis.get(key).then((data) => {
                if (data) {
                    const projects = JSON.parse(data);
                    resolve(projects);
                } else {
                    const timestamp = new Date().toISOString();
                    console.log(`[${timestamp}] Cache miss, getting data from GitHub API`);

                    fetch(url, reqInfo)
                        .then((res) => res.json())
                        .then(({ data }) => {
                            const projects = data.user.pinnedItems.nodes;
                            redis.setex(key, 3600, JSON.stringify(projects));
                            resolve(projects);
                        });
                }
            });
        })
    }
};
// ...

Trying Out New View Transitions API

The view transitions API streamlines the process of animating between two page states, which is especially useful for page transitions. This excellent blog post by Geoff Rich offered valuable insights and guidelines on implementing this new feature to my project.

I set up the new View Transitions API in my SvelteKit project using the onNavigate() function inside the +layout.svelte file. This function enabled the transitions between different page states seamlessly.



<script>
// ...
    // view transition between routes
    onNavigate((navigation) => {
        // @ts-ignore
        if (!document.startViewTransition) return;

        return new Promise((resolve) => {
            // @ts-ignore
            document.startViewTransition(async () => {
                resolve();
                await navigation.complete;
            });
        });
    });
// ...
</script>

I also implemented custom transitions using CSS. These custom transitions were defined inside the app.css file.



@keyframes fade-in {
    from {
        opacity: 0;
    }
}

@keyframes fade-out {
    to {
        opacity: 0;
    }
}

@keyframes slide-from-right {
    from {
        transform: translateX(30px);
    }
}

@keyframes slide-to-left {
    to {
        transform: translateX(-30px);
    }
}

/**
 * slide animation if prefers-reduced-motion is not set,
 * else default cross-fade animation
 */
@media (prefers-reduced-motion: no-preference) {
    :root::view-transition-old(root) {
        animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
            300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
    }

    :root::view-transition-new(root) {
        animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
            300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
    }
}

Deployment

With SvelteKit, deploying my portfolio website can't get any simpler. The first step is to switch from the default SvelteKit adapter to using the Node.js adapter.

Then I created a Dockerfile that specified all the necessary dependencies and configurations. I used a multi-stage build approach to reduce the size of the final image.



FROM node:18.18.0-alpine3.18 AS build

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18.18.0-alpine3.18 AS prod

USER node:node
WORKDIR /app

COPY --from=build --chown=node:node /app/build ./build
COPY --from=build --chown=node:node /app/package.json ./

RUN npm i --omit=dev

CMD ["node", "build"]

After that, I set up a GitHub workflow to build and publish the Docker image to the GitHub Container Registry automatically.



name: Create and publish a Docker image

on:
  push:
    branches: ["main"]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push-image:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4.1.0

      - name: Log in to the Container registry
        uses: docker/login-action@v3.0.0
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels) for Docker
        id: meta
        uses: docker/metadata-action@v5.0.0
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5.0.0
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Finally, I pulled that image and deployed it to my VPS. You can see it live now at https://bagashiz.me!

Source Code

If you're interested in exploring more about this project, you can check out the source code in my GitHub repository

bagashiz / portfolio

Class-less personal portfolio & resume website built using Go, Templ, HTMX, and styled with Pico CSS.

Portfolio

Description

My personal portfolio website for showcasing my resume, projects, and blog posts. The site is built using Go, Templ, HTMX, and Pico CSS. The site also uses KeyDB as a drop-in replacement for Redis.

The featured GitHub projects are dynamically retrieved through the power of the GitHub GraphQL API. The blog posts are seamlessly pulled in using the Dev.to API. Additionally, KeyDB is used to cache the GitHub and Dev.to API responses for 1 hour to reduce the number of API calls. Icons are provided by Font Awesome through their kit from the CDN. I've also implemented the new View Transition API feature to enhance the user experience.

There is an old stack version of the site in the sveltekit branch. The old stack version of the site was built using SveteKit.

Demo

Check out the live demo at bagashiz.xyz!

Dependencies

Go version 1.22 or…

View on GitHub

Building RESTful API with Hexagonal Architecture in Go

Bagas Hizbullah — Wed, 27 Sep 2023 15:45:16 +0000

I've been learning how to build web applications using different frameworks and languages for a while now, such as Laravel with its MVC architecture and Node.js following the 'Hapi.js Way'. As I'm trying to create a new portfolio project using Go, I found myself contemplating over the ideal project structure. I wanted something that not only aligns with the standard Go project layout, but also makes the code both easy to write and understand. That's when I stumbled upon the concept of Hexagonal Architecture, as showcased in Netflix's engineering blog. The idea of seamlessly swapping infrastructures with minimal code changes fascinated me, and I decided to implement it in my new project.

Now, the remaining question was, "what should I build?" Fortunately, as I was casually scrolling through YouTube videos, I stumbled upon this hidden gem video titled 'Ide Project untuk Upgrade Portfolio Backend Engineer' by Asdita Prasetya. He recommended developing a RESTful Point of Sale API service. It felt like the perfect project to put my newfound architectural knowledge into practice. So, getting my coffee and keyboard ready, I started on this exciting learning journey!

Hexagonal Architecture

Create your application to work without either a UI or a database so you can run automated regression-tests against the application, work when the database becomes unavailable, and link applications together without any user involvement.

Hexagonal Architecture, also known as Ports & Adapters Architecture, is one of several ways to build decoupled software systems. It was popularized by Alistair Cockburn, who is known as one of the initiators of the agile movement in software development. This way of organizing software is great for making applications that are easy to work on and can change without breaking.

The main idea behind Hexagonal Architecture is to separate the application's core business logic from the external stuff, such as databases, user interfaces, and other external services. It promotes a clean and modular structure that makes it easier to test, maintain, and scale the application.

Core

The core is where the heart of the application lives. It contains the essential business logic and rules of the application. This is where things like processing orders, managing user accounts, and performing all the tasks of the application is designed for. The core should be independent of any external technologies or frameworks, making it highly portable and reusable.

There are two other essential concepts in Hexagonal Architecture: "ports" and "adapters". These concepts dictates how the "core" interacts with the external components.

Ports

Think of ports as contracts or interfaces. They define how the application communicates with external systems or services. For example, a port could specify the rules for connecting to a database, interacting with another web services, or handling user interfaces. Ports belongs to the core, because the core defines which actions are required to achieve the business logic goals.

Adapters

Adapters are the ones who implement the contracts or interfaces defined by ports. Adapters are responsible for making sure the application can interact to databases, web services, or other things. They handle the technical details.

Driver Actors

Driver actors are the initiators of communication with the core. They reach out to the core to request specific services. Examples of driver actors can be HTTP request or command line interfaces (CLI).

Driven Actors

Driven actors are the ones that triggered by the core. If the core needs something from external services, it sends a request to the adapter, instructing it to perform a particular action. For example, if the core needs to store data in a Postgres database, it triggers communication with the Postgres client to execute an INSERT query. In this scenario, the core initiates the communication.

Implementation

Requirements

Asdita had been kind enough to provide the database schema design and Postman API documentation. So all I had to do was just structure my application to adhere to hexagonal architecture principles and start coding.

Tech Stacks

For building the RESTful Point of Sale service API, I've considered and selected a combination of technologies that would work seamlessly together. For handling HTTP requests and responses, using the Gin HTTP web framework would make sense because I think it seems complete and popular among Go community too. To ensure data integrity and persistence, I'm using PostgreSQL database with pgx as the database driver, the reason I choose PostgreSQL because it is the most popular relational database to use in production and offers efficient Go integration. I'm also implementing caching using Redis with go-redis client library, which provides powerful in-memory data storage capabilities.

Database Schema

users: stores user information, including names, emails, passwords, roles (admin or cashier), and timestamps for creation and updates.
payments: stores various payment methods. It tracks payment types, names, logos, and timestamps for creation and updates.
categories: stores product categories, tracking category names and timestamps for creation and updates.
products: stores essential product data, including category IDs, SKUs, names, stock levels, prices, images, and timestamps for creation and updates.
orders: stores order details, such as user IDs, payment IDs, customer names, total prices, payments made, returns, receipt codes, and timestamps for creation and updates.
order_products: stores record of products included in each order. It notes order and product IDs, quantities, total prices, and timestamps for creation and updates.

Application Architecture

The application follows Hexagonal Architecture, depicted as a hexagon. The core at its center houses domain and service containing business logic.

On the left side of core is a driver port, an entry point for driver adapter, while on the right side there are 2 driven ports that act as the gate for the core to interact with driven adapter.

Around the core, adapters bridge the core and external world. On the left, the HTTP adapter handles incoming HTTP requests. On the right, 2 adapters exist: DB adapter connects to PostgreSQL and Cache adapter works with Redis.

The driver actors and driven actors resides outside of the application. Nginx, on the left, serves as an HTTP server, the driver actor. On the right, PostgreSQL and Redis represent driven actors responding to core requests.

Project Structure



.
├── bin
├── cmd
│   └── http
├── docs
└── internal
    ├── adapter
    │   ├── cache
    │   │   └── redis
    │   ├── handler
    │   │   └── http
    │   ├── repository
    │   │   └── postgres
    │   │       └── migrations
    │   └── token
    │       └── paseto
    └── core
        ├── domain
        ├── port
        ├── service
        └── util

21 directories

bin: directory to store compiled executable binary.
docs: directory to store project's documentation, such as swagger static files.
cmd: directory for main entry points or commands of the application. The http sub-directory holds the main HTTP server entry point.
internal: directory for containing application code that should not exposed to external packages.
core: directory that contains the central business logic of the application. Inside it there are 4 sub-directories.
- domain: directory that contains domain models/entities representing core business concepts.
- port: directory that contains defined interfaces or contracts that adapters must follow.
- service: directory that contains the business logic or services of the application.
- util: directory that contains utility functions that reused in the service package.
adapters: directory for containing external services that will interact with the core of application. There are 4 external services used in this application.
- handler/http: directory that contains HTTP request and response handler.
- repository/postgres: directory that contains database adapters for PostgreSQL.
- cache/redis: directory that contains cache adapters for Redis.
- token/paseto: directory that contains token generation and validation adapters using Paseto.

Dev tools

I've used several tools to ease things out during development. These tools help in different ways.

Podman

Podman is a containerization tool similar to Docker, it manages containers for the application. It simplifies tasks such as building, running, and maintaining containers. It is ideal for creating isolated development environments such as PostgreSQL and Redis instance.

DBDocs

DBDocs serves as a database documentation generator. It automates the process of generating documentation for the database schema, aiding in comprehending and managing the database structure, especially when working with relational databases like PostgreSQL.

Taskfile

Taskfile is a tool for streamlining repetitive development tasks. It helps automate activities like building, testing, and deploying applications. Unlike Makefile, Taskfile uses YAML for configuration, making it more readable and user-friendly.

Golang-migrate

Golang-migrate is a database migration tool designed for Go applications. It helps manage and apply changes to the database schema as the application grows, ensuring that the code and database structure stay in sync.

Air

Air is an automatic reloading tool for Go applications. It keeps an eye on code changes and automatically restarts the application, making development more efficient.

Swaggo

Swaggo is a tool that creates Swagger documentation for Go APIs. It makes documenting API endpoints easier, helping developers understand and use the API.

Golangci-lint

Golangci-lint is a tool for checking Go code quality, finding issues, bugs, and style problems. It helps keep the code clean and maintainable.

Github Actions

GitHub Actions is a platform linked with GitHub repositories for automating tasks like building, testing, and deploying applications. It simplifies development and ensures code quality.

Deployment

I have created a GitHub Action workflow to automate the containerization process of the application and put it on GitHub Container Registry. Then I manually deployed it on my personal VPS with Nginx as reverse proxy. I might consider writing another blog post to explain my VPS setup.

You can explore the application's Swagger documentation at this URL: https://gopos.bagashiz.me/docs/index.html

Source Code

I don't want to make this post too long. So if you are interested, please check out the complete source code for this project on my GitHub repository. You can access and explore the code base, review the application's structure, and even contribute to its development.

bagashiz / go-pos

Simple RESTful Point of Sale (POS) Service API written in Go using Gin web framework, PostgreSQL database, and Redis cache. Proof of concept of implementing Hexagonal Architecture in Go.

Go POS

Description

A simple RESTful Point of Sale (POS) web service written in Go programming language. This project is a part of my learning process in understanding Hexagonal Architecture in Go.

It uses Gin as the HTTP framework and PostgreSQL as the database with pgx as the driver and Squirrel as the query builder. It also utilizes Redis as the caching layer with go-redis as the client.

This project idea was inspired by the Ide Project untuk Upgrade Portfolio Backend Engineer video on YouTube by Asdita Prasetya, which provided valuable guidance and inspiration for its development.

Getting Started

If you do not use devcontainer, ensure you have Go 1.23 or higher and Task installed on your machine:
```
go version && task --version
```
Create a copy of the .env.example file and rename it to .env:
```
cp .env.example .env
```
Update configuration values as needed.
Install all dependencies, run docker…

View on GitHub

Improvements

I admit that there are a few areas of this project that still have room for improvement:

As of now, unit tests haven't been implemented yet.
The project currently uses slog package from standard library for logging. But switching to a more advanced logger like zap could offer more flexibility and features.
Instead of directly accessing environment variables with os.Getenv(), integrating a configuration handler like viper might make it maintainable.

References

Hexagonal Architecture by Alistair Cockburn
Ready for changes with Hexagonal Architecture by Netflix Technology Blog
Hexagonal Architecture in Go by Matias Varela

Berkenalan dengan Fedora Silverblue

Bagas Hizbullah — Sun, 15 Jan 2023 19:47:21 +0000

Sebagai mahasiswa IT, saya tahu betul betapa pentingnya tools dan libraries dalam menyelesaikan tugas dan proyek kuliah saya. Demi tugas kuliah, saya harus menginstall berbagai macam software seperti Python dengan pip sebagai package manager-nya, Java, PHP, NodeJS, berbagai macam database seperti MySQL, Postgresql, Mariadb, dan bahkan virtual machine! Namun, beberapa tools itu hanya saya gunakan selama menempuh mata kuliah yang membutuhkan saja. Setelah saya menyelesaikan mata kuliah tersebut, saya tidak menggunakan tools dan libraries itu lagi. Hal ini dapat menyebabkan komputer saya menjadi berat dan lambat, atau istilahnya bloated. Oleh karena itu, saya sangat tertarik dengan salah satu sistem operasi berbasis Linux yang tidak biasa, yaitu Fedora Silverblue!

Apa Itu Fedora Silverblue?

Fedora Silverblue adalah varian dari Fedora Workstation yang menerapkan prinsip "Immutable OS" yang berfokus pada kecepatan, keamanan, atomic updates, dan immutability. Fedora Silverblue adalah salah satu sistem operasi desktop generasi baru yang bertujuan untuk memberikan pengalaman yang lebih stabil dan efisien untuk pengguna.

Fedora Silverblue is an immutable desktop operating system. It aims to be extremely stable and reliable. It also aims to be an excellent platform for developers and for those using container-focused workflows.

Apa yang dimaksud dari immutable desktop operating system? Artinya root filesystem yang berisi file dan direktori penting untuk sistem operasi berjalan dengan lancar hanya bisa dibaca saja (read-only). Ini berarti pengguna tidak bisa mengubah root filesystem secara langsung.

Teknologi OSTree

Mungkin Anda bertanya-tanya bagaimana cara meng-install tools dan libraries jika root filesystem hanya bisa dibaca saja. Pertama-tama, kita perlu memahami bagaimana cara kerja sistem Fedora Silverblue dibandingkan sistem operasi berbasis Linux tradisional lainnya, seperti Fedora Workstation, Ubuntu, Arch, dan sejenisnya.

Teknologi inti (core technology) yang digunakan oleh Fedora Silverblue adalah OSTree. OSTree digunakan untuk menyusun, men-deploy, dan meng-update Fedora Silverblue. Cara kerja OSTree mirip dengan version control system seperti Git, tetapi diterapkan pada seluruh filesystem dibandingkan hanya pada beberapa file saja. Teknologi OSTree ini diterapkan pada tool bernama rpm-ostree yang digunakan pada Fedora Silverblue untuk mengelola package yang terinstall di filesystem. rpm-ostree meng-install package sebagai "layer" pada image yang sudah dibuat oleh ostree. Kedua teknologi ini menggantikan dnf yang digunakan pada Fedora Workstation sebagai package manager.

Setiap kali sebuah package di-install menggunakan perintah rpm-ostree install [nama package] di terminal, sebuah image baru dibuat dengan package tersebut ter-install di dalamnya. Alhasil, system perlu di-reboot untuk berpindah menggunakan image baru dengan package yang sudah ter-install tadi. Mekanisme ini memungkinkan package untuk di-install pada sistem operasi yang immutable seperti Fedora Silverblue tanpa mengubah root filesystem secara langsung, jadi sistem tersebut sangat stabil dan reliable.

Mengelola Aplikasi atau Software Berbasis GUI

Untuk aplikasi atau software berbasis GUI (Graphical User Interface), sangat disarankan untuk meng-install menggunakan package manager Flatpak. Untuk meng-install sebuah aplikasi pengguna dapat menjalankan perintah flatpak install [nama aplikasi] dan flatpak update untuk melakukan pembaruan.

Selain melalui perintah di terminal, Pengguna dapat meng-install aplikasi yang diinginkan dengan mudah melalui GNOME Software, yang sudah terintegrasi dengan Flatpak di Fedora Silverblue. Mekanisme ini mirip seperti App Store pada macOS dan Windows Store pada Windows.

Menjalankan Container dengan Toolbox

Bagi software developer, sangat disarankan untuk meng-install tools dan libraries yang dibutuhkan di dalam sebuah container agar tidak mengotori root filesystem sehingga menjadi bloated. Dengan begitu, sistem akan tetap stabil dan memudahkan dalam melakukan maintenance desktop. Oleh karena itu, Fedora Silverblue menyediakan fitur bernama toolbox.

toolbox adalah sebuah tool untuk memudahkan pembuatan container untuk pengguna awam. Hal ini dilakukan dengan memanfaatkan rootless container dari Podman (Saya juga berencana membahas Podman pada blog selanjutnya.). toolbox memungkinkan pengguna untuk membuat container dengan mudah dan cepat yang dapat digunakan sebagai development environment, terpisah dari sistem operasi utama.

Manfaat dari Fedora Silverblue dan "Immutable OS" Secara Umum

Root filesystem yang hanya dapat dibaca (read-only) dapat meningkatkan ketahanan terhadap kerusakan yang tidak sengaja oleh pengguna serta beberapa jenis malware. Satu-satunya cara untuk meng-update atau mengubah root filesystem adalah dengan menggunakan rpm-ostree. Manfaat lainnya adalah hampir mustahil bagi pengguna awam untuk membuat komputer mereka ke dalam kondisi tidak bisa booting atau tidak berfungsi dengan baik setelah secara sengaja atau tidak sengaja menghapus beberapa komponen sistem.