DEV Community: Akkarapon Phikulsri

Agent Skill for Debugging Things

Akkarapon Phikulsri — Fri, 06 Nov 2026 01:42:15 +0000

Today, I want to create an agent skill for debugging. Sometimes, I receive bug reports or tickets from QA, but I don't always know where to start the investigation or what prompts to use.

I decided to use the Engineering: Debug skill to help with this process. However, its responses can sometimes be too long, with large paragraphs that are difficult to follow.

I want to improve the skill so that it breaks the investigation into clear, structured sections, such as Root Cause, How the Issue Occurs, and other relevant topics. This will make the investigation easier to understand, review, and share with the development team.

That's why I decided to create Panda Debugger, an agent skill designed to make debugging investigations more structured, clear, and easier to follow.

It make debugging easier by guiding me through the investigation step by step. It also helps me understand the problem better, explore possible causes, and generate new ideas about where to look next

At the end, I just want a clear structure with specific sections sometimes I also want to skip the investigation details and go straight to ideas or possible directions for fixing the issue. That what why i decided to create this skill. It's not about saying one approach is better or worse than another. I just wanted somthing that better fits the way I work. :)

Signing PDFs in Go? Meet pdfsign v1.0.0

Akkarapon Phikulsri — Wed, 28 Oct 2026 16:18:03 +0000

Hi :) Have you ever needed to sign a PDF document from a Go application ?

Well, I had to do that for one of my projects. I needed to digitally sign PDF documents using a certificate, so I started looking for a suitable Go package.

After exploring serveral options, I found

digitorus / pdfsign

Add/verify Advanced Electronic Signature (AES) and Qualified Electronic Signature (QES) in PDF (using pure Go)

Signing PDF files with Go

A PDF signing and verification library written in Go. This library provides both command-line tools and Go APIs for digitally signing and verifying PDF documents.

See also our PDFSigner, a more advanced digital signature server that is using this project.

Quick Start

# Sign a PDF
./pdfsign sign -name "John Doe" input.pdf output.pdf certificate.crt private_key.key

# Verify a PDF signature
./pdfsign verify document.pdf

Package Architecture

The library is organized into specialized subpackages, though most users will primarily interact with the root pdfsign package.

Package	Purpose
`pdfsign`	Primary entry point. Provides the fluent API for signing, verification, and document management.
`extract`	Low-level signature inspection. Allows extracting raw PKCS#7 envelopes and signed data.
`forms`	PDF form handling. Logic for field discovery and generating PDF object updates.
`initials`	Configuration and placement logic for signing initials across multiple pages.
`signers/...`	External Signers. Optional

…

View on GitHub

and decided to give it a try. it seemed like a good fit for my case...

Well let take a look deep drive into that package

Maybe you're building a document management system, generating contracts or automating an approval process. At first, signing a PDF might seem simple

load document
add a signature
and save it !

However, things can get more complicated when you work with real-world documents. You might need timestamps, certificate validation, certification permissions, signature verification, encrypted PDFs, or metadata in languages other than English.

That's where digitorus/pdfsign comes in.

On October 26, 2026, pdfsign reached v1.0.0. This release introduces a redesigned Go API, PAdES Baseline support, stronger signature verification, post-quantum signing support, better handling of encrypted PDFs, and improved support for Unicode metadata.

In this blog we will explore the package through practical Go examples. We will also learn how to test certification signature.

What is pdfsign?

pdfsign is a PDF signing and verification library written in Go. It also provides command line tools, so you can integrate PDF signing into an application or work with PDF files directly from your terminal.

The root pdfsign package is now the main entry point for most signing and verification tasks. Other packages provide more focused functionality, such as signature extraction, forms, fonts, images and integrations with external signing systems.

Well I recently discovered that digitorus/pdfsign has released its stable v1.0.0 version. This release introduces several improvements

Redesigned Go API Makes signing and verification easier to configure.
PAdES Baseline B-B and B-T Supports basic signatures and timestamped signatures.
Stronger verification Improves checks for signatures, certificates, timestamps, and document permissions.
ML-DSA support Adds a post-quantum digital signature algorithm.
Better PDF handling Improves support for encrypted PDFs and Unicode metadata.

Let's start with the Go API and then see how these signing features behave in practice.

Example 1: Sign a PDF using Go

First, add the package to your Go module:

go get github.com/digitorus/pdfsign

The following example demonstrates the signing flow using PAdES B-T

package main

import (
    "crypto"
    "crypto/x509"
    "os"

    "github.com/digitorus/pdfsign"
)

func signPDF(
    privateKey crypto.Signer,
    certificate *x509.Certificate,
    tsaURL string,
) error {
    doc, err := pdfsign.OpenFile("contract.pdf")
    if err != nil {
        return err
    }

    output, err := os.Create("contract-signed.pdf")
    if err != nil {
        return err
    }
    defer output.Close()

    doc.Sign(privateKey, certificate).
        Format(pdfsign.PAdES_B_T).
        Timestamp(tsaURL).
        Reason("Contract approval")

    _, err = doc.Write(output)
    return err
}

This example assumes that you have already loaded the private key and certificate, and that the configured TSA endpoint is reachable.

Here's what the main steps do

pdfsign.OpenFile(...) opens the source PDF.
doc.Sign(...) configures the document for signing.
Format(pdfsign.PAdES_B_T) selects the PAdES B-T profile.
Timestamp(tsaURL) requests a timestamp from the configured TSA.
Reason(...) records the reason for signing.
doc.Write(output) writes the signed PDF.

The fluent API makes the signing configuration easy to scan, especially when you need to add more options later.

A production note: This is a focused example of the API, not a complete signing service. Your application still needs to handle credentials securely, validate inputs, define certificate and timestamp trust policies, and handle failures appropriately.

Example 2 Verify a signed PDF

Signing a PDF is only one part of the workflow. You may also need to verify a document before accepting it into your system.

Here's a basic example using the verification builder

package main

import (
    "fmt"

    "github.com/digitorus/pdfsign"
)

func verifyPDF() error {
    doc, err := pdfsign.OpenFile("contract-signed.pdf")
    if err != nil {
        return err
    }

    result := doc.Verify().Strict()

    if !result.Valid() {
        return fmt.Errorf(
            "PDF signature verification failed: %v",
            result.Err(),
        )
    }

    fmt.Println("PDF passed strict signature verification")
    return nil
}

You can check it out in my playground!

akkaraponph / pdf-playground

PDF signing playground — pdfsign v1.0.0

Ten Go examples for learning and blog demonstrations, using github.com/digitorus/pdfsign v1.0.0. Requires Go 1.27 or newer. Run commands from the indicated example folder.

The root go.mod pins v1.0.0 for all ten examples. To add that exact release to another module, use go get github.com/digitorus/pdfsign@v1.0.0.

Each folder contains sample PDFs and explains expected behavior. A command that demonstrates rejection is not a broken example. Signature integrity, certificate trust, and timestamp trust are separate checks.

Examples 4–8 use a generated local test CA where appropriate…

View on GitHub

However at the 0.9.0 previous version, I ran into a problem. My certificate contained Thai language information, and after signing the PDF, I could not open the document in Adobe Acrobat Reader.

Instead I got this error

There was an error opening this document. There was a problem reading this document (135).

But my deadline was getting closer. T_T

As a last resort, I decide to clone the repository and modify the package to support certificates containing Thai language information

I applied the fix locally and tested it. Luckily, it worked!

After confirming that the fix solved my problem, I decided to contribute it back to the original project digitorus/pdfsign so that other developers could benefit from it too.

I'm happy to see pdfsign reach its stable v1.0.0 release. Even better, my first contribution to the project was included in this release!

I also helped test and verify the fix to make sure it worked as expected.

contribution

Fun Fact

That’s the story of how I rushed to meet a deadline, trying to get PDF signing working before it was too late. But in the end, fixing just one small issue made a difference to the community, and that’s something I’m proud of.

Sometimes, even a one line change can make an impact :)

Your AI-Generated UI Doesn't Need Another Gradient

Akkarapon Phikulsri — Sun, 25 Oct 2026 14:03:38 +0000

Impeccable: The missing design vocabulary for agents

Turn AI slop into interfaces you’re proud to ship. Impeccable gives your agent the design expertise to build from scratch, improve what you have, and stay true to your design system.

impeccable.style

The feature works. The buttons respond. The data loads.

But the screen still feels off.

There are cards inside cards. Every heading has an icon. Every status is a colorful badge. A giant title takes up half the space above a table that actually needs the room.

Imagine trying to fix that with one more prompt:

Make this look more professional.

What should “professional” mean here? Less decoration? Better spacing? A completely different layout?

That ambiguity is a good reason to give the next request a smaller job.

Prompt Impeccable is a collection of 35 focused UI/UX prompts stored as standalone Markdown files. Instead of treating polish as one big redesign, it breaks the review into specific concerns: hierarchy, typography, tables, forms, loading states, accessibility, and more.

Here's a practical way to use it without getting stuck in an endless redesign loop.

Start with the task

Consider a hypothetical document-processing app.

A user opens the document list to answer three questions:

Did the upload finish?
Is the document ready?
If processing failed, how can it be retried?

Keep those questions beside the component while reviewing it. They give you something more useful than “make it modern.”

For this example, a proposed cleanup could look like this:

Element	Proposed change
Document name	Give it the strongest emphasis in each row
Processing status	Keep a readable label visible
Retry action	Make it discoverable on failed items
Updated timestamp	Keep it available, but visually quieter
Decorative icon beside every label	Remove where it adds no information
Nested card wrappers	Replace with rows or simpler grouping where appropriate

This is an illustrative design proposal, not a tested before-and-after result. A different product might need a different treatment.

The important part is the reasoning: each change should support what someone came to do.

Pick the relevant prompt

You don't need to run all 35 prompts against every screen.

The repository includes a table and data-grid prompt for data-heavy views.

Table / Data Grid UX

/impeccable

Refine this table or data-heavy interface for fast scanning.

Prioritize:

* important columns
* alignment
* readable row density
* clear headers
* predictable actions
* useful filtering
* sorting
* pagination
* selection states

Reduce:

* icons in every cell
* excessive badges
* unnecessary borders
* oversized rows
* repeated information

Keep row actions visually secondary until needed.

Make large amounts of information easier to compare.

There are also separate prompts for card reduction,

Card Reduction

/impeccable

Audit all cards and containers on this interface.

For every card, determine whether a visual container is actually necessary.

Flatten unnecessary cards.

Avoid:

* card inside card
* every section becoming a card
* excessive borders
* excessive shadows
* oversized radius
* decorative surfaces

Prefer:

* sections
* lists
* rows
* whitespace
* subtle separators
* typography

Keep cards only where they provide meaningful grouping.

icon discipline

/impeccable

Review icon usage across this interface.

Preserve icons that improve:

* navigation
* recognition
* actions
* status
* scanning

Remove icons that are:

* decorative
* repeated unnecessarily
* placed beside every heading
* placed beside normal metadata
* duplicating obvious text
* used only to fill space

Do not make the interface icon-free.

Reduce icon density rather than removing iconography entirely.

Functional icons should remain.

Decorative icons should disappear.

design-system consistency.

/impeccable

Audit this interface against the existing product design system.

Find inconsistencies in:

* spacing
* typography
* colors
* radius
* shadows
* buttons
* inputs
* cards
* badges
* icons
* states

Reuse existing components and tokens wherever possible.

Do not introduce a new visual pattern when an existing pattern already solves the problem.

Reduce one-off styling.

For the document list, start with the table review. Open the Markdown file, read it, and give its instructions to your coding assistant along with the relevant component and the task you're trying to improve.

Then add project-specific boundaries. For example:

Review the document-list component using the supplied table prompt.

Users need to check processing progress and retry failed documents.

Keep search, sorting, pagination, permissions, and API behavior unchanged.
Use the existing components and design tokens.
Do not change other screens.

Before editing, explain the proposed changes and any trade-offs.

This additional brief is an original example, not a copied repository prompt.

Read the proposal before approving it. If the assistant suggests removing the owner column, check who uses that information. An administrator reviewing shared uploads may need it even when a single-user account doesn't.

Simpler doesn't mean emptier

A cleanup can go too far.

Suppose the new layout hides document status in a menu. The screen might look calmer, but the user now has to open each item to find the failed upload.

That's not an improvement for the task above.

The repository's information-density prompt explicitly warns against hiding useful information merely to simplify the interface.

Information Density Optimization

/impeccable

Optimize the information density of this interface.

Reduce unnecessary visual noise without making the interface empty.

Keep important information visible and easy to scan.

Group related information together.

Reduce duplication.

Move secondary details into quieter presentation when appropriate.

Avoid solving complexity by simply hiding useful information.

The goal is:

high information value with low visual noise.

Try reducing emphasis before removing content. A timestamp can use quieter text. Row actions can remain accessible without looking like primary calls to action. Related metadata can share a line instead of occupying separate boxes.

Likewise, don't remove every icon. Keep a recognizable action or status symbol when it helps. Question the icon whose only job is filling an empty corner.

Check the awkward states

Once the populated screen looks reasonable, test the versions that aren't in the happy-path demo.

What happens before the first upload? During processing? After a failed request? When a search returns nothing?

Prompt Impeccable has dedicated prompts for empty, loading, and error states.

For the hypothetical app, distinguish an empty library from an empty search result. One could offer an upload action; the other could offer a way to clear filters.

For errors, only promise recovery actions the application supports. Don't add a “Retry” button with no retry behavior behind it, and don't invent a failure reason the backend never supplied.

Then try the main path with the keyboard and on a narrow screen. Use the accessibility audit as a checklist—not as proof that the result meets an accessibility standard.

Keep the change reviewable

After each pass, inspect the diff and repeat the original task.

Can you identify the document? Read its state? Find the retry action? Do sorting and pagination still work?

If a visual cleanup also changes fetching logic or introduces a new dependency, ask why that belongs in this change. Keep unrelated work separate unless there's a clear reason to include it.

There isn't a prompt that can make that judgment for your product. These files provide a useful review brief; you still need to check the implementation.

Pick one screen that feels unfinished. Choose the prompt closest to its actual problem. Make one small change, then use the screen again.

akkaraponph / prompt-impeccable

Impeccable UX/UI Prompt Collection

A modular collection of 35 targeted UX/UI prompts designed to eliminate AI-generated sloppiness, enforce design system consistency, and elevate web applications to production-grade craftsmanship.

Each prompt is stored in its own standalone markdown file under this directory, ready to be used individually or combined for specific design, refactoring, and code review purposes.

🎯 Categorized by Purpose

1. General Polish & AI-Slop Elimination

Targeted prompts to eliminate common AI design tropes (excessive containers, decorative gradients, random badges) and restore visual discipline.

01-base-production-polish.md — Base production polish for hierarchy, spacing, alignment, and responsiveness.
02-reduce-ai-sloppy-ui.md — Audit and remove cards-inside-cards, excessive pills, badges, and decorative noise.
03-icon-discipline.md — Retain functional navigation/action icons while purging decorative clutter.
04-visual-hierarchy-audit.md — Establish clear primary vs secondary visual emphasis and contrast.
05-information-density-optimization.md — Maximize information value while lowering visual noise.
30-ai-slop-detection-pass.md — Dedicated sweep for sparkle icons, decorative gradients, floating cards, etc.
31-reduce-ui-noise.md…

View on GitHub

Theory of Humanistic Architecture

Akkarapon Phikulsri — Sun, 06 Sep 2026 15:41:18 +0000

Humanistic Architecture Learning to See Problems Differently

I had the opportunity to attend a class called “Humanistic Architecture” by Mr. Chakrit Riddhagni.

The class was about applying humanistic principles to software development.

Before talking about what I learned, I would like to share a little about my own perspective on software development.

Personally, I have a quote and a belief about software development: it is both a science and an art.

I see software development as something that has an artistic side, while being grounded in logic, with almost endless possibilities.

“Crafting software requires artistry, guided by imagination, grounded in logic, endlessly enduring.”

This quote has been one of my inspirations since I started working as a developer.

What I mean by this is that I have always liked thinking about software development as a kind of literature. We are not simply writing code. We are solving problems. We are developing and creating something to solve a problem that either we or our customers are facing.

Because of this, as a developer, I naturally work with problems every day.

But… I never really thought much deeper about what a “problem” actually is.

Usually, when we solve a problem for a customer or develop software for them, we receive an issue or a scope of work and then start working on it.

We know that something is a problem, so we focus on solving it.

But we do not always stop and ask

What is the actual structure of this problem ?
Is this really the problem?
And does the solution we are building actually address the problem we are trying to solve?

That changed when I attended the “Humanistic Architecture” class.

One of the biggest things I gained from this class was a new perspective and a set of tools for defining what a “problem” really is.

Anatomy of a Problem

We can look at a problem through the Anatomy of a Problem, which consists of three parts:

Current State — where we are now
Gap — the difference between where we are and where we want to be
Desired State — where we want to go

The Current State is our situation at this moment.

The Desired State is the situation or outcome we want to reach.

And the Gap is the space between them — the part that needs to be changed in order to move from the Current State to the Desired State.

Beyond understanding this structure, I also learned more about how to find solutions that address the root cause of a problem as much as possible through psychological models.

One of them is Satir's Iceberg Model, where one of the most important concepts is Yearning — our deep desire, motivation, or inner need.

Another model is the 3 Centers Model

Heart, Head, and Body

Heart — using our feelings and values to determine direction
Head — using our thinking to make plans
Body — taking action and putting those plans into practice

The Anatomy of a Problem, together with these two models, became the main tools I learned for analyzing problems and finding solutions.

And I don't think these tools are useful only for software development.

I can also see how they can be applied to everyday life and many other situations.

For example, whenever we are not satisfied with our Current State and have a Desired State that we want to reach, a Gap exists between them.

And that Gap is where the problem lies.

This simple way of looking at problems has changed the way I think.

Overall, this class really resonated with me.

It is something that I can actually apply in my work, and I believe it will also be useful in my everyday life.

After coming back to work, I don't think I can look at problems in exactly the same way anymore.

Instead of simply seeing an issue and thinking about how to fix it, I will probably have this structure in my head first:

Current → Gap → Desired

And somehow, I think that's the biggest thing I took away from this class. 😆

Akkarapon Phikulsri

Sep 6

The Anatomy of a Problem

#humanistic #problemsolving #softwareengineering #humanisticarchitecture

4 min read

The Anatomy of a Problem

Akkarapon Phikulsri — Sun, 06 Sep 2026 13:42:12 +0000

I recently had the opportunity to attend a class called “Humanistic Architecture” by Mr.Chakrit Riddhagni. The class was about applying humanistic principles to software development.

Before I talk about what I learned, I want to share a little about my own perspective on software development.

Personally, I have a quote and a belief that I have carried with me throughout my career: software development is both a science and an art.

I see software development as something that has an artistic side, while being grounded in logic, with almost endless possibilities.

“Crafting software requires artistry, guided by imagination, grounded in logic, endlessly enduring.”

This quote has been one of my inspirations since I started working as a developer.

Because of this, being a developer means that we naturally work with problems every day.

But… I never really thought much deeper about what a “problem” actually is.

Usually, when we work on a problem for a customer or develop software for them, we receive an issue or a scope of work and then start working on it. We know that something is a problem, so we focus on solving it.

However, we do not always stop and think about the structure of the problem.

Is this really the problem?

What is actually causing it?

And does the solution we are building really address the problem we are trying to solve?

That changed when I attended the “Humanistic Architecture” class.

One of the biggest things I took away from the class was a new perspective and a set of tools for defining what a “problem” really is.

We can look at a problem through the Anatomy of a Problem, which can be divided into three parts:

Current State — where we are now
Desired State — where we want to be
Gap — the difference between the current state and the desired state

The Gap is where we need to focus in order to move from the Current State toward the Desired State.

Beyond understanding the structure and components of a problem, another important thing I learned was how to find solutions that address the root cause of a problem as effectively as possible.

The class introduced ways of looking at problems through psychological models, which helped me understand that solving a problem is not always about simply fixing what we can see on the surface.

Sometimes, we need to understand the people, their behaviors, their expectations, and the reasons behind the problem before we can design a solution that truly solves it.

And I think this is a perspective that can be very valuable for software developers.

Because sometimes, the hardest part of solving a problem is not writing the code. It is understanding what the real problem is.

The Anatomy of a Problem

The first topic we learned was “The Anatomy of a Problem,” which is about understanding the structure of a problem.

A problem can be divided into three parts:

Current State > where we are right now
Gap -> the difference between where we are and where we want to be
Desired State -> where we want to go

Current State is the situation we are in at the moment.

Desired State is the situation or goal that we want to reach.

Gap is the space or difference between the Current State and the Desired State. It represents what needs to change in order to move from where we are now to where we want to be.

For example:

Current State: I cannot sleep.
Gap: I either do not sleep, or I try to sleep but cannot fall asleep.
Desired State: I can sleep well.

This way of thinking may look simple, but it gives us a useful framework for looking at problems.

Instead of simply saying “I cannot sleep, so I need a solution,” we can step back and ask:

Where am I now? Where do I want to be? And what is preventing me from getting there?

I think this is an interesting way to start understanding a problem before jumping directly into finding a solution.

Whenever we are not satisfied with our current state and have a place we want to reach, a gap will exist between the two.

That gap is exactly where we need to focus our effort to solve the problem, because the problem already exists.

Before learning about “The Anatomy of a Problem,” I started with an exercise based on a simple but interesting question

“What makes us, as human beings, get up and take action to solve a problem?”

From my perspective, human beings always have needs or wants that they want to fulfill in order to feel complete. When things do not go as we expect, we experience disappointment. As a result, we usually look for a method or a tool to fill that gap or solve the problem in a way that we believe is appropriate.

After learning about “The Anatomy of a Problem,” I started to understand and reflect on this idea more deeply.

“A problem is a thing or situation that we cannot handle or solve at that moment.”

Very often, when we solve one problem, new problems appear. In fact, there are often other problems hidden inside a problem.

“Every problem or solution can always create new problems.”

In other words, every problem has a solution, and every solution can bring new problems.

However, a problem may not exist if we are satisfied with our Current State. When we are satisfied with where we are, there is no Desired State that we need to reach. Therefore, there is no Gap between the two.

So, this leads me to the following understanding:

“The problem is the gap between the Current State and the Desired State.”

Git - Commit Message Format

Akkarapon Phikulsri — Sun, 06 Sep 2026 07:29:58 +0000

Introduction

The commit message is something we write very frequently during the development process. It summarizes the changes made after completing a section or feature. It's important to keep commit messages clean and easy to read. Following best practices and using a pattern consistent with your team's or company's style is crucial. Here,

I will show you a pattern that helps structure and organize commit messages effectively, making them easy to read and understandable :)

Pattern

Each commit message consists of a header, a body, and a footer. The header has a special format that includes a type, a scope, and a subject:

<type>(<scope>): <subject>
<BLANK LINE>

<body>
<BLANK LINE>
<footer>

The header is mandatory and the scope of the header is optional.

Example

fix: remove unused dependency lodash.camelcase

Any line of the commit message cannot be longer than 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

the component of message format are type, scope, subject, body and footer

Type
Must be one of the following example below

feat: A new feature.
fix: A bug fix.
docs: Documentation only changes.
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
refactor: A code change that neither fixes a bug nor adds a feature.
perf: A code change that improves performance.
test: Adding missing tests.
chore: Changes to the build process or auxiliary tools and libraries such as documentation generation.
ci: Changes to our CI configuration files and scripts.
build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
revert: Reverts a previous commit.
wip: Work in progress. Commit that may be removed later.

but some time i just have no idea for prefix message usally i use are feat and fix haha

Scope
The scope is optional and could be anything specifying the place of the commit change. For example nsis, mac, linux, etc.

Subject
The subject contains a succinct description of the change:

Use the imperative, present tense: change not changed nor changes.
Don't capitalize the first letter.
No dot (.) at the end.

Body
Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes".
The body should include the motivation for the change and contrast this with the previous behavior.

Footer
The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit Closes. Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

Best Practices

Write Meaningful Commit Messages: Ensure that each commit message clearly conveys what the change is and why it was made. This is crucial for maintaining a clear project history.
Keep Commits Small: Each commit should represent a single logical change. This makes it easier to review changes and revert them if necessary.
Use Branches: For each new feature or bug fix, create a new branch. This helps in keeping the main branch stable and allows for easier collaboration.
Squash Commits: Before merging a feature branch into the main branch, consider squashing commits to ensure a clean and concise project history.
Review Before Commit: Review your changes before committing. Ensure that your code adheres to the project's coding standards and passes all tests.
Automate Testing: Set up automated tests to run on each commit to ensure that changes do not introduce new bugs.
Follow a Consistent Style: Adhere to the established style guide for the project to maintain consistency across the codebase.

How ever
In the AI era, we normally ask AI to generate the commit message. It would be better if we provide a commit message pattern for the AI agent. I think it would be better to make commit history easier to read, not just dump messages that have no prefix or too much noise

Reference

FreeCodeCamp. (2022, March 2). How to write better Git commit messages. FreeCodeCamp. https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/
Beams, C. (n.d.). How to write a Git commit message. Retrieved July 16, 2024, from https://cbea.ms/git-commit/
2my. (2021, October 30). Git conventional commits. 2my Blog. https://blog.2my.xyz/2021/10/30/git-conventional-commits/
Akkaraponph. (n.d.). Commit messages. GitHub. Retrieved August 5, 2024, from https://github.com/akkaraponph/commit-messages

PostgreSQL Cheat Sheet: Investigating and Terminating Database Blocking Sessions

Akkarapon Phikulsri — Fri, 28 Aug 2026 04:07:47 +0000

If you run PostgreSQL in production for a long time, you will probably see this problem at some point:

Queries start waiting.
Connections increase.
The database becomes slower.
Connection usage gets close to max_connections.

One common cause is a session that is blocking other sessions.

A common example is a connection in the idle in transaction state. The application started a transaction but did not COMMIT or ROLLBACK it.

In this article, we will use pg_stat_activity and several PostgreSQL functions to investigate these problems.

We will also look at when to use:

pg_cancel_backend()
pg_terminate_backend()
pg_blocking_pids()

The goal is not only to kill a bad session. The goal is to understand why it happened and prevent it from happening again.

Why Can PostgreSQL Sessions Block Each Other?

PostgreSQL uses MVCC (Multi-Version Concurrency Control) and locking to support many users at the same time.

For example:

BEGIN;

UPDATE orders
SET status = 'PROCESSING'
WHERE id = 100;

The transaction may hold locks until it finishes with:

COMMIT;

or:

ROLLBACK;

The problem happens when the application starts a transaction but never finishes it.

The connection may then appear as:

idle in transaction

The session is not running a query anymore, but the transaction is still open.

This can cause several problems:

Locks may still be held.
Other queries may have to wait.
Old transaction snapshots may stay open.
VACUUM may not be able to clean some dead rows.
Tables may become larger over time.

This is why it is important to understand the difference between:

active

and:

idle in transaction

An active session is currently running a query.

An idle in transaction session is waiting for the client, but its transaction is still open.

Step 1: Inspect All Non-Idle Sessions

I normally start an investigation with this query:

SELECT
    pid,
    usename,
    application_name,
    state,
    query_start,
    now() - query_start AS duration,
    query
FROM pg_stat_activity
WHERE state <> 'idle'
ORDER BY query_start;

This removes normal idle connections from the result.

You can now see sessions that are:

running queries,
waiting,
or idle inside a transaction.

The application_name field is very useful when you have many services.

For example, your PostgreSQL connection may include:

application_name=order-service

Then you may see something like:

pid     application_name   state
12345   order-service      active
12346   payment-service    idle in transaction

This is much easier than trying to guess which application owns a PID.

For Go, Node.js, or other microservice systems, I strongly recommend setting application_name for every service.

Step 2: Use a Quick Triage Query

During an incident, sometimes you do not need every column.

You just want to quickly see what is happening.

Use:

SELECT
    pid,
    age(clock_timestamp(), query_start),
    state,
    query
FROM pg_stat_activity
WHERE state <> 'idle';

This shows:

PID
query age
session state
query text

I use this kind of query as a quick first check.

For example:

PID 1596183
State: active
Duration: 00:08:32
Query: SELECT ...

Now you know that one query has been running for more than eight minutes.

The next question is:

Is this query really slow, or is it waiting for another session?

That is an important difference.

Step 3: Find Idle-in-Transaction Sessions

To check only sessions that are idle inside a transaction:

SELECT
    pid,
    usename,
    application_name,
    state,
    xact_start,
    state_change,
    now() - xact_start AS transaction_age,
    query
FROM pg_stat_activity
WHERE state = 'idle in transaction'
ORDER BY xact_start;

Pay special attention to:

xact_start

This tells you when the transaction started.

A transaction that has been open for a few seconds may be normal.

A transaction that has been open for 30 minutes or several hours is much more suspicious.

Do not immediately kill every idle in transaction connection.

First check:

Which application created it?
How long has the transaction been open?
Is this normal for the application?
Is it blocking another session?

Step 4: Terminate an Idle Transaction

If you confirm that a session is stuck and should not still be open, you can terminate it.

For one PID:

SELECT pg_terminate_backend(1596183);

This closes the PostgreSQL session.

PostgreSQL will roll back its open transaction and release its locks.

For old idle transactions, you can also use a controlled query like:

SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND state_change < now() - interval '5 minutes'
  AND pid <> pg_backend_pid();

This example only terminates sessions that have been idle inside a transaction for more than five minutes.

The condition:

pid <> pg_backend_pid()

prevents the query from terminating your own PostgreSQL session.

Be careful with this command in production.

It is usually better to filter by things such as:

datname

usename

or:

application_name

For example:

SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND application_name = 'order-service'
  AND state_change < now() - interval '5 minutes'
  AND pid <> pg_backend_pid();

This is much safer than terminating every idle transaction in the cluster.

Step 5: Cancel a Running Query

Sometimes the connection itself is fine, but one query is taking too long.

In that case, try:

SELECT pg_cancel_backend(1596183);

pg_cancel_backend() stops the current query but keeps the database connection alive.

This makes it a good first choice for things like:

a very expensive SELECT,
a report query,
an accidental full-table operation,
or a query that a user wants to cancel.

Think about it like this:

pg_cancel_backend()
        |
        v
Stop the current query
        |
        v
Keep the connection

`pg_cancel_backend()` vs `pg_terminate_backend()`

These two functions are similar, but they solve different problems.

Function	What happens	Good for
`pg_cancel_backend(pid)`	Stops the current query but keeps the connection	Long-running or unwanted active queries
`pg_terminate_backend(pid)`	Closes the whole database session	Stuck sessions, idle transactions, serious blocking problems

My normal approach is:

Active bad query
     |
     v
pg_cancel_backend()
     |
     | still causing problems
     v
pg_terminate_backend()

For an idle in transaction session, pg_cancel_backend() normally does not solve the problem because there is no active query to cancel.

In that situation, you may need:

pg_terminate_backend()

Step 6: Find Who Is Blocking a Query

A long-running query is not always slow.

Sometimes it is simply waiting for another transaction.

PostgreSQL provides a very useful function:

pg_blocking_pids()

For example:

SELECT
    pid,
    usename,
    application_name,
    state,
    pg_blocking_pids(pid) AS blocking_pids,
    query
FROM pg_stat_activity
WHERE cardinality(pg_blocking_pids(pid)) > 0;

You may get something like:

pid       blocking_pids
-----------------------
20002     {20001}

This means:

PID 20001
    |
    | blocks
    v
PID 20002

Do not immediately kill PID 20002.

It is the blocked session, not necessarily the real problem.

You should investigate PID 20001.

Finding the Root Blocker

A production problem can be more complicated:

Session A
   |
   | blocks
   v
Session B
   |
   | blocks
   v
Session C

If you kill Session B, Session C may improve, but you have not fixed the real source of the problem.

The real blocker is:

Session A

That is why pg_blocking_pids() is useful.

You want to follow the blocking chain until you find the session that is not waiting for another backend.

That session is usually the root blocker.

Investigate that session first.

Step 7: Check Which Database Uses the Most Connections

If your PostgreSQL server contains several databases, check how connections are distributed:

SELECT
    datname,
    count(*)
FROM pg_stat_activity
GROUP BY datname
ORDER BY count(*) DESC;

Example:

datname        count
-------------  -----
order_prod       82
notification     15
postgres          3

Now you know where most connections are being used.

If one database has a very high number, investigate:

application connection pool size,
PgBouncer settings,
connection leaks,
long-running queries,
idle transactions.

A high connection count does not always mean PostgreSQL itself is the problem.

The application may simply be opening too many connections.

Step 8: Check Connection Headroom

You should also check how close PostgreSQL is to its configured connection limit.

SELECT
    (SELECT count(*) FROM pg_stat_activity) AS used_connections,
    (
        SELECT setting::int
        FROM pg_settings
        WHERE name = 'max_connections'
    ) AS max_connections;

For example:

used_connections | max_connections
-----------------+----------------
87               | 100

You are now using:

87 / 100

connections.

That means there is very little room left.

This becomes dangerous because when an incident happens, you may not even be able to open another connection to investigate the problem.

For production systems, I normally monitor connection usage before it gets close to the maximum.

Preventing Idle Transactions

Manually killing sessions is useful during an incident.

But it is not the real fix.

PostgreSQL can automatically terminate connections that stay idle inside a transaction for too long.

For example:

ALTER DATABASE mydb
SET idle_in_transaction_session_timeout = '2min';

Now PostgreSQL will close sessions that remain idle inside a transaction longer than the configured timeout.

You should choose the timeout based on your workload.

For example:

30 seconds

may work for a fast OLTP API.

While:

5 minutes

may be safer for applications with longer business operations.

Do not copy a timeout value without understanding your system first.

Protect Against Long-Running Queries

You can also use:

statement_timeout

For example:

ALTER DATABASE mydb
SET statement_timeout = '30s';

This prevents individual SQL statements from running forever.

However, be careful.

A timeout that is good for API requests may be too short for:

reports,
migrations,
ETL jobs,
batch processing.

Different applications may need different timeout values.

Log Lock Problems

Another useful PostgreSQL setting is:

log_lock_waits

You can enable it with:

ALTER SYSTEM SET log_lock_waits = on;

PostgreSQL can then log queries that wait too long for a lock.

This works together with:

deadlock_timeout

For example:

ALTER SYSTEM SET deadlock_timeout = '1s';

This makes lock problems much easier to investigate because PostgreSQL logs useful information when sessions wait for locks.

Remember to reload the configuration when required.

Fix the Problem in the Application

Database commands help during an incident.

But if idle in transaction keeps happening, the real bug is usually inside the application.

For example, in Go:

tx, err := db.Begin(ctx)
if err != nil {
    return err
}

defer tx.Rollback(ctx)

Then later:

if err := tx.Commit(ctx); err != nil {
    return err
}

The important idea is simple:

BEGIN
  |
  +---- success ----> COMMIT
  |
  +---- error ------> ROLLBACK

Every transaction must have a clear ending.

This is especially important when using libraries such as:

pgx
GORM
database/sql
Node.js pg

Every error path should either commit or roll back the transaction correctly.

Connection Pools Matter Too

Also check your connection pool configuration.

For example, imagine you have:

10 services

and every service allows:

20 connections

Your applications may try to create:

10 × 20 = 200 connections

But PostgreSQL may only allow:

max_connections = 100

That architecture will eventually create problems.

Tools such as PgBouncer can help reduce the number of PostgreSQL backend connections, but they do not replace correct transaction handling.

You still need to:

commit transactions,
roll back transactions,
set reasonable pool limits,
monitor connection usage.

My Production Troubleshooting Flow

When PostgreSQL starts becoming slow, I normally think about the problem in this order:

PostgreSQL is slow
        |
        v
Check pg_stat_activity
        |
        v
Are queries active or idle in transaction?
        |
        +------ idle in transaction
        |             |
        |             v
        |      Check transaction age
        |             |
        |             v
        |      Check if it is blocking
        |             |
        |             v
        |      pg_terminate_backend()
        |
        +------ active
                      |
                      v
              Check blocking_pids
                      |
              +-------+-------+
              |               |
           blocked         not blocked
              |               |
              v               v
         Find blocker    Investigate query
                              |
                              v
                      pg_cancel_backend()

The important point is:

Do not kill a PostgreSQL PID only because a query has been running for a long time.

First understand what that PID is doing.

Ask:

Is it running?

Is it waiting?

Is it blocking?

Is it being blocked?

Is it idle inside a transaction?

Then choose the correct action.

Useful Commands Summary

Check non-idle sessions:

SELECT
    pid,
    usename,
    application_name,
    state,
    query_start,
    now() - query_start AS duration,
    query
FROM pg_stat_activity
WHERE state <> 'idle'
ORDER BY query_start;

Find idle transactions:

SELECT
    pid,
    application_name,
    xact_start,
    now() - xact_start AS transaction_age,
    query
FROM pg_stat_activity
WHERE state = 'idle in transaction';

Find blocked sessions:

SELECT
    pid,
    pg_blocking_pids(pid) AS blocking_pids,
    query
FROM pg_stat_activity
WHERE cardinality(pg_blocking_pids(pid)) > 0;

Cancel a query:

SELECT pg_cancel_backend(1596183);

Terminate a connection:

SELECT pg_terminate_backend(1596183);

Check connections per database:

SELECT
    datname,
    count(*)
FROM pg_stat_activity
GROUP BY datname
ORDER BY count(*) DESC;

Check connection limit:

SELECT
    (SELECT count(*) FROM pg_stat_activity) AS used_connections,
    (
        SELECT setting::int
        FROM pg_settings
        WHERE name = 'max_connections'
    ) AS max_connections;

Final Thoughts

When PostgreSQL has a connection or blocking problem, pg_stat_activity is one of the first places I check.

But the most important skill is not knowing how to kill a PID.

It is knowing which PID should be killed and why.

A blocked query may only be a victim.

An idle in transaction session may be the real blocker.

And a high connection count may be caused by an application pool instead of PostgreSQL itself.

A good production investigation should therefore follow this process:

Observe
   ↓
Find the blocker
   ↓
Understand the transaction
   ↓
Mitigate the incident
   ↓
Fix the application
   ↓
Add protection and monitoring

Commands like pg_cancel_backend() and pg_terminate_backend() are useful emergency tools.

But the long-term solution is better transaction handling, good connection pool limits, proper timeouts, and enough monitoring to find the problem before production users notice it.

Fixing "GOPROXY list is not the empty string, but contains no entries" in Go

Akkarapon Phikulsri — Wed, 22 Jul 2026 10:05:57 +0000

If you've ever run go mod tidy and been greeted by a wall of red text ending in:

go: todo-services imports
        github.com/99designs/gqlgen: GOPROXY list is not the empty string, but contains no entries

...you're not alone. This error looks scary because it repeats for every single import in your project, but the actual fix takes about 30 seconds. Here's what's going on and how to solve it.

What This Error Actually Means

Go resolves modules through GOPROXY, an environment variable that tells the toolchain where to fetch dependencies from. The error message is oddly specific:

"GOPROXY list is not the empty string, but contains no entries"

This means GOPROXY is set to something, but once Go parses it, there are zero usable proxy URLs in it. Common causes:

A stray comma or pipe with no actual URL (GOPROXY=, or GOPROXY=|)
GOPROXY=off, which explicitly disables all proxying
A shell-level override with a blank or whitespace value that shadows your real Go config
A corporate/custom proxy URL that no longer resolves

This is especially common on Windows with Git Bash (MINGW64), where environment variables inherited from Windows user/system settings can silently override what Go has configured in its own env file.

Step-by-Step Fix

1. Check for a shell-level override

Environment variables set in your current shell session take priority over Go's own config file. Check what's actually there:

echo "GOPROXY=[$GOPROXY]"

If this prints GOPROXY=[], GOPROXY=[ ], or something malformed, that's your problem — the shell is passing Go a broken value.

2. Clear the session override

unset GOPROXY

This drops the bad value for the current session and lets Go fall back to its own configuration.

3. Persist a valid proxy in Go's config

This writes directly to Go's env file (%USERPROFILE%\AppData\Roaming\go\env on Windows, ~/.config/go/env on Linux/macOS):

go env -w GOPROXY=https://proxy.golang.org,direct

The ,direct fallback tells Go to bypass the proxy and fetch directly from source control if a module isn't available there — a good safety net.

If you're behind a corporate network or VPN, swap in your internal proxy instead:

go env -w GOPROXY=https://your-company-proxy.example.com,direct

4. Sanity-check related settings

go env GOPROXY GOFLAGS GOSUMDB

Expected healthy values:

Variable	Expected value
`GOPROXY`	`https://proxy.golang.org,direct` (or your internal proxy + `,direct`)
`GOFLAGS`	Empty, unless you intentionally use flags like `-mod=mod`
`GOSUMDB`	`sum.golang.org` (default), unless disabled for a reason

5. Clear Go's caches if the problem persists

Sometimes a bad proxy state gets baked into cached build artifacts or module downloads. If steps 1–4 didn't fully resolve things, nuke the caches:

go clean -cache -testcache -modcache

Flag	Clears
`-cache`	Compiled build cache
`-testcache`	Cached test results
`-modcache`	Downloaded modules (`$GOPATH/pkg/mod`)

This forces a full re-download of every dependency on your next build, using your now-corrected proxy settings.

6. Retry

go mod tidy

At this point, all those GOPROXY list is not the empty string... lines should be gone, replaced by normal module resolution output for todo-services.

Windows/MINGW64 Gotcha

If GOPROXY keeps reverting to a bad value in new terminal sessions, the override probably lives in Windows System Properties → Environment Variables, not just in go env. Go's own persisted config won't help if Windows keeps re-injecting a bad value into every new shell. Check it directly:

cat "$USERPROFILE/AppData/Roaming/go/env"

Quick Reference Checklist

echo "GOPROXY=[$GOPROXY]" — no stray/invalid shell override
unset GOPROXY — if a bad session override exists
go env -w GOPROXY=https://proxy.golang.org,direct — sets a valid persistent proxy
go env GOPROXY GOFLAGS GOSUMDB — confirms sane values
go clean -cache -testcache -modcache — if issues persist
go mod tidy — succeeds after the above

Command Cheat Sheet

go version                            # Confirm installed Go version
go env                                # Print all Go environment settings
go env GOPROXY                        # Print a specific setting
go env -w KEY=VALUE                   # Persist a setting to Go's env file
go env -u KEY                         # Unset a persisted setting (revert to default)
go mod tidy                           # Sync go.mod/go.sum with imports
go clean -cache -testcache -modcache  # Clear build, test, and module caches

If this saved you a headache, drop a — and if you've hit a different flavor of this error, I'd love to hear about it in the comments.

GitHub Spark - A First Look at GitHub’s New Developer Tool

Akkarapon Phikulsri — Sun, 15 Mar 2026 07:30:05 +0000

GitHub Spark is an intuitive way to bring your ideas to life.

Note: GitHub Spark is available to users on GitHub Copilot Pro+ and Enterprise plans.

What is GitHub Spark?

GitHub Spark is an AI-powered tool that helps you "spark" ideas into functional "sparks" (micro-apps) quickly. You don't need to write every line of code; instead, you describe your idea in plain English. Just "vibe it to life," and the AI builds the app for you.

You can get started with GitHub Spark here.

Quick prompt

We will quickly try out the cash flow app for managing personal finances in React Native. I started the process with a simple prompt, and i got some code and a quick preview

Referencing Repositories

As you can see in the image below, I can refer to my old repositories, and GitHub Spark will attempt to read the context of that code.

This makes it incredibly powerful for building on top of your existing work.

According to the picture, this is about the suggestions section from Spark, which is where you can add feature suggestions.

Comparison with Lovable

In my opinion, it feels similar to Lovable

lovable.dev

However, because Spark is native to GitHub, we can easily reference other repositories as context.

Playground

We can also easily quick-edit the code or try to change the line of code by hand using a quick editor

I liked the modal that told me what went wrong and showed the button to tell the agent to "Fix all" right away.

We can see the pair window of code and the preview section on the right side while AI is fixing.

Theme

It's easy for us to change the theme of our app; all we have to do is click and choose a color preset.

After that...

I just clicked a preset to quickly render and change the entire theme to a new color. We can also see how the theme changes based on adjustments to typography, color, and appearance.

Data Mockup

Table
JSON

We can quickly mock the data based on the table UI and also give JSON information.

Assets

The Assets tab is essentially your project's. We can drop files there that Spark needs to reference during the build or at runtime, like the logo image for our website, and can iterate to using them later.

Visuals: Logos, custom icons, or high-res background banners.
Data JSON or CSV files (like your personal spreadsheets).
Knowledge PDFs or text files that give the AI specific instructions or context.

Turning Assets into Action

The real power of Spark happens when you move from uploading to iterating. You can take old data and give it a modern "face" in seconds.

For my review, I tested this by bringing in

Brand Assets: A custom logo.png and hero banner. jpg.

for the logo, we can iterate ai to redesign landing page with logo like

Legacy Data A 5-year-old income-expense dataset from my GitHub.

akkaraponph / income-expense

for fundamental data science

Datasets-Income-Expense

For fundamental data science

Simple Datasets

Repo. Directory Structure

├── Datasets-Income-Expense
│   ├── English
│       ├── Income_Expense_lacakp_Q1_2564_Eng.csv 
│       └── Income_Expense_lacakp_Q2_2564_Eng.csv
│   ├── Thai
│       ├── Income_Expense_lacakp_Q1_2564_Thai.csv 
│       └── Income_Expense_lacakp_Q2_2564_Thai.csv

Exsamples

Date	Income	Expense	Category	Where	Payment Method
1-Jan-21	3000	owe	online	netbank	primary
1-Jan-21	3500	income	home	cash	primary
1-Jan-21	2800	rent fee, expense	apartment	cash	primary
1-Jan-21	40	water bill, expense	apartment	cash	primary
1-Jan-21	65	electricity bill, expense	apartment	cash	primary
1-Jan-21	853	music, expense	online	netbank	tertiary
1-Jan-21	1600	income, entertainment	online	cash	tertiary
3-Jan-21	90	car fare, expense	none	cash	primary
3-Jan-21	35	breakfast, expense	market	cash	primary
3-Jan-21	30	dinner, expense	market	cash	primary
3-Jan-21	10	expense	shop	cash	primary
3-Jan-21	40	expense	apartment	cash	secondary
4-Jan-21	65	breakfast, expense	Seven-Eleven	cash	primary
4-Jan-21	45	expense, eggs	Seven-Eleven	cash	primary
4-Jan-21	15	drinking water, expense	apartment	cash	primary
4-Jan-21	30	food, dinner, expense

…

View on GitHub

After dropping the files, I just iterate the prompt like
base on csv files give me mockup base on those data

The agent looked at the headers and quickly built a working dashboard without having to do any manual mapping or coding. It's very satisfying to see a static file turn into an interactive app component right in front of your eyes.

Publish

We can make our spark public (need to sign in with GitHub to view) and also change the visibility setting.

Is GitHub Spark the Future of Rapid Prototyping?

In summary, GitHub Spark is a game changer for bridging the gap between a raw idea and a functional reality; it empowers creators to take the concepts in their heads and manifest them into tangible "Sparks" using nothing more than natural language and some simple prompts.

Why it stands out

Speed to market Whether you're a developer or a visionary, you can build a working product or mockup prototype at an incredible pace.
Intuitive Customization The ability to tweak themes, typography, and data mockups with a few clicks makes it accessible without sacrificing control.
The GitHub Advantage The killer feature is the native ecosystem. Being able to reference your existing private repositories for context is a superpower that other tools simply can't match

If you are already a fan of tools like Lovable but prefer staying within the GitHub ecosystem, Spark is a fantastic alternative. At the current price point of $39 USD (GitHub Copilot Pro+), the value you get—combining AI-assisted coding with this rapid prototyping environment—is exceptionally comprehensive.

GitHub Spark isn't just a toy; It's a high-velocity engine for the next generation of builders :)

DeltaView - AI-Driven JSON Diff Viewer Built with GitHub Copilot

Akkarapon Phikulsri — Sat, 14 Feb 2026 11:40:32 +0000

This is a submission for the GitHub Copilot CLI Challenge

DeltaView - AI-Driven Diff Viewer Built with GitHub Copilot

What I Built

DeltaView is a powerful web-based JSON diff viewer that showcases AI-driven development using GitHub Copilot. The application parses JSON inputs, generates structural diffs, and displays them with beautiful syntax highlighting and side-by-side comparison views.

Key Features:

Intelligent JSON Diff Engine - Recursively compares JSON structures and categorizes changes (added, removed, modified)
Real-time Diff Visualization - Side-by-side comparison with color-coded changes
Syntax Highlighting - Professional code display with proper formatting
Error Handling - Graceful handling of invalid JSON and edge cases
Type-Safe Implementation - Built with TypeScript for reliability
Responsive UI - Modern, clean interface built with React, TailwindCSS, and shadcn/ui

Technology Stack:

Frontend: React + TypeScript
Styling: TailwindCSS + shadcn/ui components
Build Tool: Bun (ultra-fast JavaScript runtime)
Development Methodology: AI-driven architecture with markdown specifications

🎬 Features & Demo

Live demo available at: deltaview.refactorroom.com

DeltaView - All-in-One Developer Toolkit | JSON Converters, Generators, Editor & Schema Converters

All-in-one developer toolkit: JSON converters, generators, online editor, and schema converters. Compare JSON with visual diffs, format & validate, visualize as graphs or tables. Privacy-first, free forever.

deltaview.refactorroom.com

1. 📝 JSON Compare Input Panel

Easily input two JSON objects to compare. The interface features:

Side-by-side JSON input panels
Format buttons to validate and beautify JSON
Load example data for quick testing
Real-time error validation
Support for large JSON structures

2. 🔍 JSON Comparison Results

Get detailed, line-by-line diff visualization:

Orange highlights - Removed or old values
Purple highlights - Added or new values
Character-level precision - See exactly what changed within each line
Copy buttons - Easily copy individual sides
Expandable view - Toggle between split and fullscreen modes
Line numbers for easy reference

Key Comparison Features:

Recursive diff of nested objects
Array element tracking
Property addition/removal detection
Value modification detection
Type change detection

3. 📊 JSON Graph Visualization

Visualize JSON structure as an interactive graph:

Node-based representation of objects and arrays
Visual relationship mapping
Interactive node exploration
Zoom and pan controls
Perfect for understanding complex JSON hierarchies

Graph Features:

Auto-layout for clarity
Color-coded node types
Expandable/collapsible nodes
Connection visualization
Ideal for API responses and config files

4. 📋 Table View

Convert JSON data into structured table format:

Automatic table generation from JSON objects
Column headers from object keys
Clean, organized data presentation
Sortable columns
Perfect for data-driven JSON

Table Features:

Auto-detect and format columns
Handle nested objects gracefully
Array data visualization
Easy copy and export functionality
Responsive column sizing

5. ✨ JSON Formatter

Format, validate, and beautify JSON with professional formatting:

One-click JSON formatting
Automatic indentation (2 spaces)
Syntax highlighting
Error detection with line numbers
Copy formatted output

Formatter Capabilities:

Validate JSON syntax
Detect and report errors
Pretty-print with proper indentation
Remove unnecessary whitespace
Support for large files

🌐 Technology & Performance

Instant Validation - Real-time error checking
Responsive Design - Works perfectly on desktop, tablet, and mobile
Dark/Light Mode - Comfortable viewing in any lighting
Fast Processing - Handles large JSON files efficiently
Type-Safe - Built with TypeScript for reliability

My Experience with GitHub Copilot CLI

How I Used GitHub Copilot CLI

Architecture Definition - Used natural language in docs/architecture.md to define the diff engine specifications, component structure, and data contracts. GitHub Copilot CLI helped generate detailed TypeScript interfaces.
Component Generation - Leveraged gh copilot in the terminal to:
- Generate React component scaffolds with proper TypeScript types
- Create utility functions following project conventions
- Generate UI component wrappers for shadcn/ui integration
Complex Logic Implementation - Used Copilot Chat for:
- Implementing the recursive JSON diff algorithm
- Handling edge cases and data type comparisons
- Creating proper error handling patterns
Code Quality & Consistency - Copilot CLI suggested:
- Linting fixes and TypeScript improvements
- Best practice patterns for React hooks and state management
- Proper accessibility attributes for UI components

Impact on Development

Productivity Gains:

⚡ 60-80% faster development - Boilerplate and repetitive code generation done by AI
🎯 Consistency - All components follow the same patterns defined in agent markdown files
📚 Better Documentation - Architecture markdown files serve as both specs and living documentation
🐛 Fewer Bugs - Type-safe implementations and consistent error handling patterns

Developer Experience:

Natural language to code conversion eliminated context switching
AI understood project conventions and applied them automatically
Focus shifted from syntax to architecture and user experience
Iterative refinement became faster with AI assistance

Key Learnings

Markdown-First Development - Well-structured architecture docs enable AI to maintain consistency across large codebases
Context is King - Providing clear specifications in agent files dramatically improves code quality
Collaboration Model - Human architects design system, AI implements details, humans review and refine
Scalability - This methodology scales better than traditional development for complex projects

This project demonstrates that modern web applications can be built faster, with higher quality, and better maintainability when humans and AI work together with clear architectural specifications.

🚀 Get Started with GitHub Copilot - Easy, Fun & Productive!

Why GitHub Copilot?

GitHub Copilot transforms your coding experience into a productive conversation with AI! Whether you're building new features, debugging code, or learning new frameworks, Copilot is your 24/7 coding companion that makes development easier, faster, and more enjoyable.

✨ Key Benefits

🎯 Easy to Use - Just install and start coding! Copilot understands natural language and suggests code as you type
⚡ Boost Productivity - Cut development time in half by letting AI handle boilerplate, repetitive tasks, and scaffolding
💡 Learn While You Code - Discover best practices, new APIs, and coding patterns through intelligent suggestions
🎨 Focus on Creativity - Spend less time on syntax, more time on solving problems and building amazing features
🤖 CLI Power - Use gh copilot in your terminal for instant help, command suggestions, and code generation

📦 Super Simple Installation

Getting started with GitHub Copilot is as easy as 1-2-3:

Install the Extension - One click in VS Code or your favorite IDE
Sign In - Connect with your GitHub account
Start Coding - That's it! Copilot is ready to assist you

🎉 Why Developers Love It

"Instead of manually writing everything from scratch, I just describe what I want and Copilot generates it. This cuts out boilerplate and lets me focus on the actual logic and user experience."

Key Features That Make Coding Fun:

Natural Language → Code: Describe what you want in comments, get working code instantly
Context-Aware: Understands your project structure and adapts to your coding style
Multi-Language: Works seamlessly with dozens of programming languages
Terminal Integration: GitHub Copilot CLI for command suggestions and explanations right in your terminal
Real-Time Assistance: Get suggestions as you type, no interruptions to your flow

💪 Productivity Boosters

Generate entire functions from a single comment
Convert ideas into working code in seconds
Automate repetitive coding tasks
Get instant code explanations and documentation
Fix bugs faster with AI-powered suggestions

Ready to supercharge your coding? Get GitHub Copilot today!

🤖 AI-Driven Development with Agent Markdown Files

This project demonstrates a powerful AI-first development methodology using structured markdown documentation to guide AI coding agents. Instead of traditional specification documents, we use agent-optimized markdown files that serve as both documentation and instruction sets for AI assistants like GitHub Copilot.

📋 The Agent MD File Pattern

Our docs/ folder contains markdown files specifically designed for AI agents:

docs/
  ├── agent.md              # Core agent instructions & principles
  ├── architecture.md       # System architecture & structure
  ├── coding-standards.md   # Code quality rules
  ├── prompt.md             # Initial project prompt
  ├── ui-guidelines.md      # UI/UX specifications
  ├── vision.md             # Project scope & constraints
  └── tasks/                # Task breakdown

🎯 Why This Approach Works

Traditional Development:

Write specs → Translate to code → Review → Refactor
High cognitive load on developers
Specs often become outdated
Inconsistent implementation

AI-Driven Development:

Write clear markdown requirements → AI generates code → Human reviews
AI maintains consistency across codebase
Documentation stays synchronized with code
Faster iteration cycles

🔧 How We Use Agent Files

1. Architecture as Code (architecture.md)

Defines the entire system structure, component responsibilities, and technical constraints:

Tech stack decisions (React, TypeScript, shadcn/ui)
File organization and structure
Data contracts and interfaces
Performance constraints
Non-goals and boundaries

AI Agent Benefit: Understands the full context and makes consistent architectural decisions.

2. Agent Instructions (agent.md)

Core principles and rules for the AI coding agent:

Code style preferences
Component patterns to follow
JSON handling rules
UI tone and approach
Error handling standards

AI Agent Benefit: Maintains code quality and follows project conventions automatically.

3. Project Prompt (prompt.md)

The initial project specification in natural language:

Feature requirements
Component structure
UX guidelines
API contracts

AI Agent Benefit: Can regenerate or extend features while staying aligned with original vision.

4. Vision Document (vision.md)

Clear boundaries and constraints:

What the project IS
What the project IS NOT
Scope limitations

AI Agent Benefit: Prevents scope creep and keeps AI focused on core functionality.

✨ Benefits of AI-Driven Development

🚀 Speed

Generate entire components from markdown specifications
Boilerplate elimination – AI handles repetitive code
Parallel development – AI works on multiple files simultaneously

🎯 Consistency

Architectural alignment – AI follows defined patterns
Code style uniformity – Automatic adherence to standards
No drift – Documentation and code stay in sync

📚 Living Documentation

Markdown files are human-readable project docs
AI references them for every code generation
Easy to update and maintain

🧠 Knowledge Transfer

New team members read markdown files
AI onboards instantly with same context
Reduces tribal knowledge problems

🛠️ Practical Workflow Example

Step 1: Manual Project Initialization

Before leveraging GitHub Copilot, we start with a basic project setup. This project was initialized using Bun:

bun init

After running bun init, your project structure is ready:

This creates the initial project structure with:

Basic package.json
TypeScript configuration
Entry point files

Why manual first? This establishes the foundation and project structure that Copilot will then enhance and build upon. You control the tech stack decisions, and AI handles the implementation details.

Step 2: Trust Your Workspace

When you open your project folder in VS Code, you'll need to trust the workspace to enable all features:

Click "Yes, I trust the authors" to allow VS Code and GitHub Copilot to:

Access your project files
Provide context-aware suggestions
Run scripts and tools
Enable full extension functionality

This is a one-time security step that ensures you're comfortable with the code in your workspace.

Step 3: Start Prompting with Copilot

Now you're ready to start working with GitHub Copilot! Open the Copilot chat and start describing what you want to build:

Simply describe your requirements in natural language:

"Create a JSON formatter component following docs/architecture.md"
"Build a diff viewer with syntax highlighting"
"Add error handling for invalid JSON input"

Copilot understands your project context and generates code that fits your architecture!

Step 4: AI Takes Over Development

Once the foundation is set, GitHub Copilot accelerates development:

Scenario: Add a new "Export to CSV" feature

Traditional Approach:

Write feature spec
Manually code the export logic
Create UI components
Write tests
Update documentation
Code review
Refactor

AI-Driven Approach:

Update docs/architecture.md with CSV export requirements
Ask Copilot: "Implement CSV export feature following docs/architecture.md"
AI generates:
- Export logic in lib/export/csv.ts
- UI button component
- Integration with existing panels
- Error handling
- TypeScript types
Human reviews and refines
Documentation already updated (step 1)

Time saved: 60-80% reduction in implementation time

📖 Example: JSON Diff Implementation

Our architecture.md specifies:

## Diff Engine
Must be:
- Structural (parse JSON first)
- Recursive
- Deterministic
- Library-free

type DiffEntry = {
  path: string
  type: "added" | "removed" | "modified"
  oldValue?: unknown
  newValue?: unknown
}

AI Agent reads this and generates:

Complete recursive diff algorithm
Type-safe implementation
Proper error handling
Exact data contract adherence

Developer role: Review logic, test edge cases, refine algorithm

💡 Best Practices for Agent Markdown Files

Be Specific, Not Vague
- ❌ "Make it look nice"
- ✅ "Use monospace font, 2-space indentation, subtle colors (green for added, red for removed)"
Define Data Contracts
- Include TypeScript types in markdown
- Specify exact field names and types
- Show example inputs/outputs
Set Boundaries
- Explicitly state what NOT to do
- Define scope limitations
- Prevent feature creep
Keep It Organized
- One concern per file
- Cross-reference related files
- Use clear headings
Write for Both AI and Humans
- Natural language that humans can read
- Structured format AI can parse
- Examples and counterexamples

🎓 Getting Started with Agent-Driven Development

Create a docs/ folder in your project
Write an architecture.md – Define your system structure
Add agent.md – Specify coding principles and patterns
Create vision.md – Set clear boundaries
Reference these files when working with GitHub Copilot
Iterate – Update markdown files as requirements evolve

🔮 The Future of Development

AI-driven development with agent markdown files represents a paradigm shift:

Documentation-first development
AI as implementation partner
Human as architect and reviewer
Faster, more consistent codebases

This project (deltaview.refactorroom.com) was built almost entirely using this methodology, demonstrating that complex applications can be developed with AI assistance while maintaining high code quality and clear architecture.

🚀 Deploying to Cloudflare Pages

DeltaView is deployed to Cloudflare Pages for fast, global distribution. Here's how to deploy:

Prerequisites

Cloudflare Account - Sign up at cloudflare.com
Wrangler CLI - Install with:

   npm install -g wrangler

Authentication - Run wrangler login to connect your account

Your Current Setup

Your project is configured for Cloudflare Pages with:

Project name: deltaview
Build output: dist/
Build command: bun run build.ts

Deployment Steps

1. Authenticate with Cloudflare

wrangler login

2. Build Your Project

bun run build.ts

This generates the dist/ folder with your static assets.

3. Deploy to Pages

wrangler pages deploy dist

Or deploy to a specific environment:

wrangler pages deploy dist --branch=production
wrangler pages deploy dist --branch=preview

4. Add Custom Domain (via Dashboard)

Go to Cloudflare Dashboard
Select deltaview project
Navigate to Settings → Custom domains
Add your domain (e.g., deltaview.refactorroom.com)

Using Package Scripts

We've provided convenient npm scripts in package.json:

bun run pages:build      # Build the project
bun run pages:deploy     # Deploy to Pages
bun run pages:dev        # Local Pages preview

CI/CD Automatic Deployment

For automatic deployments on every push:

Go to Cloudflare Dashboard
Select deltaview project → Settings → Build and deployment
Connect your GitHub repository
Configure:
- Build command: bun run build.ts
- Build output directory: dist
Push to main branch - deployment happens automatically!

Live Site

Your site is live at:

Pages domain: https://deltaview-ap7.pages.dev
Custom domain: https://deltaview.refactorroom.com (once configured)

Project Setup

To install dependencies:

bun install

To start a development server:

bun dev

To run for production:

bun start

This project was created using bun init in bun v1.2.19. Bun is a fast all-in-one JavaScript runtime.

Comprehensive Research: Audit Log Paradigms & Go/PostgreSQL/GORM Design Patterns

Akkarapon Phikulsri — Sat, 07 Feb 2026 16:16:36 +0000

Audit Log Paradigms
Event Sourcing vs Audit Logging
Real-World Use Cases
Database Design Patterns for Audit Trails
State Transition Tracking
API Audit Logging Best Practices
Go/PostgreSQL/GORM Implementation Patterns
Complete Code Examples

1. Audit Log Paradigms

Core Concepts

Audit logging is the practice of recording changes to data in a system to provide:

Traceability: Who did what, when, and why
Compliance: Meeting regulatory requirements (GDPR, HIPAA, SOC 2, PCI DSS)
Security: Detecting suspicious activities and unauthorized access
Debugging: Understanding system behavior and data evolution
Recovery: Ability to rollback or replay changes

Key Principles

1. Append-Only Structure

Audit logs should NEVER be modified or deleted
All entries are immutable after creation
Use separate tables/storage from operational data

2. Essential Audit Fields

Every audit log entry should capture:

Timestamp: When the action occurred (with timezone)
Actor: Who performed the action (user ID, service account)
Action: What was done (CREATE, UPDATE, DELETE, READ)
Resource: What entity was affected (table name, record ID)
Before/After State: Previous and new values
Context: Additional metadata (IP address, session ID, request ID)

3. Performance Considerations

Audit logging should not significantly impact main operations
Use async/background processing for logging when possible
Implement log rotation and archival strategies
Index strategically for query performance

2. Event Sourcing vs Audit Logging

Comparison Matrix

Feature	Event Sourcing	Audit Log
Purpose	Maintain complete history of state changes as source of truth	Track user actions for security/compliance
Granularity	Very granular, every state change	High-level, significant actions
Structure	Append-only log of immutable events	Append-only log of action records
Events Recorded	Facts that occurred (irrefutable)	Account of actions performed
Reconstruction	Can reconstruct system state by replaying events	Not designed for reconstructing state
Querying	Often requires event replay	Direct querying for audit purposes
System Recovery	Facilitates rollback/recovery by replaying	Primarily for investigation/compliance
Complexity	Higher complexity, careful design needed	Generally simpler, auxiliary feature
Use Case	Core business logic and state management	Compliance, security, debugging

When to Use What?

Use Event Sourcing when:

Business logic depends on complete history
Need to replay events to rebuild state
Domain complexity requires detailed tracking
Audit trail is a critical business requirement

Use Audit Logging when:

Need compliance/security tracking only
Don't need state reconstruction
Want simpler implementation
Audit is secondary concern

Hybrid Approach:
Many systems use event sourcing for critical domains and traditional audit logging for other areas.

3. Real-World Use Cases

1. Financial Services

Scenario: Banking transaction processing

Use Case: Track every transaction, balance change, and access attempt
Requirements:
- Immutable records of all transactions
- 7-10 year retention for compliance
- Millisecond-precision timestamps
- Ability to prove no tampering

Implementation:
- Separate audit database with write-only access
- Cryptographic signatures on audit entries
- Regular backup to immutable storage (S3 Glacier)

2. Healthcare (HIPAA Compliance)

Scenario: Patient record access tracking

Use Case: Track who viewed/modified patient records
Requirements:
- Log every access to protected health information (PHI)
- Capture: user, timestamp, patient ID, action, reason
- Alert on suspicious access patterns
- Retain for 6+ years

Implementation:
- Real-time audit logging on every PHI access
- Automated alerting for unusual patterns
- Encrypted audit logs
- Regular compliance reports

3. E-Commerce Order Management

Scenario: Order lifecycle tracking

Use Case: Track order state transitions from creation to delivery
Requirements:
- Capture state changes: created → paid → shipped → delivered
- Record who authorized changes
- Support dispute resolution
- Enable order reconstruction

Implementation:
- State machine with audit trail
- Transition validation rules
- Rollback capability for specific states

4. API Access Control

Scenario: RESTful API request tracking

Use Case: Monitor API usage, detect abuse, support debugging
Requirements:
- Log API requests: endpoint, method, user, parameters
- Track rate limiting violations
- Capture response status and errors
- Enable analytics and billing

Implementation:
- Middleware-based request/response logging
- Async logging to not block requests
- Log aggregation (ELK stack, Splunk)
- Real-time alerting on anomalies

5. Multi-Tenant SaaS

Scenario: User action tracking across tenants

Use Case: Provide audit trails to enterprise customers
Requirements:
- Per-tenant audit logs
- Customer-accessible audit UI
- GDPR right-to-erasure support
- Role-based audit log access

Implementation:
- Tenant-isolated audit tables or schemas
- Audit API endpoints for customers
- Export functionality (CSV, JSON)
- Data retention policies per tenant

6. Incident Management System

Scenario: Tracking incident status and updates

Use Case: Track incident lifecycle and all updates
Requirements:
- Every status change logged
- Update history with timestamps
- Severity changes tracked
- Automated timeline generation

Implementation:
- Event-sourced incident aggregate
- Rich timeline reconstruction
- Audit log as secondary index
- Real-time status board

4. Database Design Patterns for Audit Trails

Pattern 1: Row Versioning (In-Place Audit)

Concept: Add versioning fields directly to the main table

CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    order_number VARCHAR(50) NOT NULL,
    customer_id BIGINT NOT NULL,
    total_amount DECIMAL(10,2),
    status VARCHAR(20),

    -- Audit fields
    version INT NOT NULL DEFAULT 1,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    created_by VARCHAR(100) NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_by VARCHAR(100) NOT NULL,
    deleted_at TIMESTAMPTZ,
    deleted_by VARCHAR(100)
);

Pros:

Simple to implement
No extra tables
Easy to query current state

Cons:

Loses history of changes
No details on what changed
Can't rollback to previous versions

Pattern 2: Shadow/History Tables

Concept: Separate table mirrors main table with full history

-- Main table (current state)
CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    order_number VARCHAR(50) NOT NULL,
    customer_id BIGINT NOT NULL,
    total_amount DECIMAL(10,2),
    status VARCHAR(20),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- History table (all versions)
CREATE TABLE orders_history (
    history_id BIGSERIAL PRIMARY KEY,
    id BIGINT NOT NULL,
    order_number VARCHAR(50),
    customer_id BIGINT,
    total_amount DECIMAL(10,2),
    status VARCHAR(20),

    -- Audit metadata
    operation VARCHAR(10) NOT NULL, -- INSERT, UPDATE, DELETE
    changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    changed_by VARCHAR(100) NOT NULL,

    -- Track what changed
    change_reason TEXT
);

-- Trigger to populate history
CREATE OR REPLACE FUNCTION orders_audit_trigger()
RETURNS TRIGGER AS $$
BEGIN
    IF (TG_OP = 'DELETE') THEN
        INSERT INTO orders_history (id, order_number, customer_id, total_amount, 
                                    status, operation, changed_by)
        VALUES (OLD.id, OLD.order_number, OLD.customer_id, OLD.total_amount,
                OLD.status, 'DELETE', current_user);
        RETURN OLD;
    ELSIF (TG_OP = 'UPDATE') THEN
        INSERT INTO orders_history (id, order_number, customer_id, total_amount,
                                    status, operation, changed_by)
        VALUES (NEW.id, NEW.order_number, NEW.customer_id, NEW.total_amount,
                NEW.status, 'UPDATE', current_user);
        RETURN NEW;
    ELSIF (TG_OP = 'INSERT') THEN
        INSERT INTO orders_history (id, order_number, customer_id, total_amount,
                                    status, operation, changed_by)
        VALUES (NEW.id, NEW.order_number, NEW.customer_id, NEW.total_amount,
                NEW.status, 'INSERT', current_user);
        RETURN NEW;
    END IF;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER orders_audit
AFTER INSERT OR UPDATE OR DELETE ON orders
FOR EACH ROW EXECUTE FUNCTION orders_audit_trigger();

Pros:

Complete history preserved
Main table stays clean
Easy to query historical data

Cons:

Doubles storage requirements
Schema changes need updating both tables
Trigger overhead on every operation

Pattern 3: Generic Audit Log Table

Concept: Single table logs changes to any entity

CREATE TABLE audit_logs (
    id BIGSERIAL PRIMARY KEY,

    -- What was changed
    table_name VARCHAR(100) NOT NULL,
    record_id VARCHAR(100) NOT NULL,

    -- What changed
    field_name VARCHAR(100),
    old_value TEXT,
    new_value TEXT,

    -- Who and when
    operation VARCHAR(10) NOT NULL, -- CREATE, UPDATE, DELETE, READ
    changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    changed_by VARCHAR(100) NOT NULL,

    -- Context
    ip_address INET,
    user_agent TEXT,
    session_id VARCHAR(100),
    request_id VARCHAR(100),

    -- Additional metadata
    metadata JSONB
);

-- Indexes for common queries
CREATE INDEX idx_audit_logs_table_record ON audit_logs(table_name, record_id);
CREATE INDEX idx_audit_logs_changed_at ON audit_logs(changed_at DESC);
CREATE INDEX idx_audit_logs_changed_by ON audit_logs(changed_by);
CREATE INDEX idx_audit_logs_operation ON audit_logs(operation);

Pros:

Works for any table
Flexible schema
Single place for all audits

Cons:

Less type safety
Complex queries for reconstruction
Can grow very large

Pattern 4: Event Store (Event Sourcing)

Concept: Store all changes as discrete events

CREATE TABLE events (
    id BIGSERIAL PRIMARY KEY,

    -- Event identification
    aggregate_type VARCHAR(100) NOT NULL, -- e.g., "Order"
    aggregate_id VARCHAR(100) NOT NULL,
    event_type VARCHAR(100) NOT NULL, -- e.g., "OrderCreated", "OrderPaid"
    event_version INT NOT NULL,

    -- Event data
    event_data JSONB NOT NULL,

    -- Metadata
    occurred_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    caused_by VARCHAR(100) NOT NULL,
    correlation_id VARCHAR(100),

    -- Ensure ordered sequence per aggregate
    CONSTRAINT unique_aggregate_version UNIQUE (aggregate_type, aggregate_id, event_version)
);

CREATE INDEX idx_events_aggregate ON events(aggregate_type, aggregate_id, event_version);
CREATE INDEX idx_events_occurred_at ON events(occurred_at);

Example events:

{
  "event_type": "OrderCreated",
  "aggregate_type": "Order",
  "aggregate_id": "ORD-12345",
  "event_version": 1,
  "event_data": {
    "order_number": "ORD-12345",
    "customer_id": 567,
    "items": [...],
    "total": 99.99
  }
}

{
  "event_type": "OrderPaid",
  "aggregate_type": "Order",
  "aggregate_id": "ORD-12345",
  "event_version": 2,
  "event_data": {
    "payment_method": "credit_card",
    "transaction_id": "TXN-98765"
  }
}

Pros:

Complete history with business context
Can rebuild state by replaying events
Natural fit for CQRS
Excellent for complex domains

Cons:

High complexity
Schema evolution challenges
Event versioning required
Querying current state requires rebuilding

5. State Transition Tracking

Finite State Machine Pattern

Concept: Track valid state transitions and maintain history

-- Define valid state transitions
CREATE TABLE state_transitions (
    from_state VARCHAR(50) NOT NULL,
    to_state VARCHAR(50) NOT NULL,
    PRIMARY KEY (from_state, to_state)
);

-- Seed valid transitions for orders
INSERT INTO state_transitions (from_state, to_state) VALUES
    ('INITIAL', 'created'),
    ('created', 'payment_pending'),
    ('payment_pending', 'paid'),
    ('payment_pending', 'cancelled'),
    ('paid', 'processing'),
    ('processing', 'shipped'),
    ('shipped', 'delivered'),
    ('delivered', 'completed'),
    ('paid', 'refunded'),
    ('processing', 'cancelled');

-- Main entity table
CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    order_number VARCHAR(50) UNIQUE NOT NULL,
    customer_id BIGINT NOT NULL,
    current_state VARCHAR(50) NOT NULL DEFAULT 'created',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- State history table
CREATE TABLE order_state_history (
    id BIGSERIAL PRIMARY KEY,
    order_id BIGINT NOT NULL REFERENCES orders(id),
    from_state VARCHAR(50) NOT NULL,
    to_state VARCHAR(50) NOT NULL,

    -- Enforce valid transitions
    FOREIGN KEY (from_state, to_state) 
        REFERENCES state_transitions(from_state, to_state),

    transitioned_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    transitioned_by VARCHAR(100) NOT NULL,
    reason TEXT,
    metadata JSONB,

    -- Ensure transitions are sequential
    sort_key INT NOT NULL,
    is_current BOOLEAN NOT NULL DEFAULT true,

    CONSTRAINT unique_current_per_order 
        UNIQUE (order_id, is_current) WHERE is_current = true
);

-- Index for querying current state
CREATE INDEX idx_order_state_history_current 
    ON order_state_history(order_id, is_current) 
    WHERE is_current = true;

-- Index for timeline queries
CREATE INDEX idx_order_state_history_timeline 
    ON order_state_history(order_id, sort_key);

State Transition Function

CREATE OR REPLACE FUNCTION transition_order_state(
    p_order_id BIGINT,
    p_to_state VARCHAR(50),
    p_user VARCHAR(100),
    p_reason TEXT DEFAULT NULL
) RETURNS BOOLEAN AS $$
DECLARE
    v_current_state VARCHAR(50);
    v_next_sort_key INT;
    v_is_valid BOOLEAN;
BEGIN
    -- Get current state
    SELECT current_state INTO v_current_state
    FROM orders
    WHERE id = p_order_id
    FOR UPDATE; -- Lock row

    IF NOT FOUND THEN
        RAISE EXCEPTION 'Order not found: %', p_order_id;
    END IF;

    -- Check if transition is valid
    SELECT EXISTS(
        SELECT 1 FROM state_transitions
        WHERE from_state = v_current_state
        AND to_state = p_to_state
    ) INTO v_is_valid;

    IF NOT v_is_valid THEN
        RAISE EXCEPTION 'Invalid state transition: % -> %', 
            v_current_state, p_to_state;
    END IF;

    -- Get next sort key
    SELECT COALESCE(MAX(sort_key), 0) + 1
    INTO v_next_sort_key
    FROM order_state_history
    WHERE order_id = p_order_id;

    -- Mark current state as no longer current
    UPDATE order_state_history
    SET is_current = false
    WHERE order_id = p_order_id
    AND is_current = true;

    -- Insert new state
    INSERT INTO order_state_history (
        order_id, from_state, to_state, transitioned_by, 
        reason, sort_key, is_current
    ) VALUES (
        p_order_id, v_current_state, p_to_state, p_user,
        p_reason, v_next_sort_key, true
    );

    -- Update current state on main table
    UPDATE orders
    SET current_state = p_to_state
    WHERE id = p_order_id;

    RETURN true;
END;
$$ LANGUAGE plpgsql;

Querying State History

-- Get complete timeline for an order
SELECT 
    from_state,
    to_state,
    transitioned_at,
    transitioned_by,
    reason,
    sort_key
FROM order_state_history
WHERE order_id = 123
ORDER BY sort_key;

-- Find all orders in a specific state
SELECT o.id, o.order_number, o.current_state
FROM orders o
WHERE o.current_state = 'shipped';

-- Find orders that transitioned through a specific state
SELECT DISTINCT o.id, o.order_number
FROM orders o
JOIN order_state_history h ON o.id = h.order_id
WHERE h.to_state = 'processing';

-- Get duration in each state
SELECT 
    order_id,
    to_state,
    transitioned_at,
    LEAD(transitioned_at) OVER (PARTITION BY order_id ORDER BY sort_key) 
        - transitioned_at AS duration_in_state
FROM order_state_history
WHERE order_id = 123
ORDER BY sort_key;

6. API Audit Logging Best Practices

Essential Elements for API Audit Logs

Request Identification
- Request ID (unique identifier)
- Correlation ID (for distributed tracing)
- Session ID
Authentication/Authorization
- User ID or service account
- Authentication method (JWT, OAuth, API key)
- Scopes/permissions used
Request Details
- HTTP method (GET, POST, PUT, DELETE)
- Endpoint/route
- Request parameters
- Request body (sanitized of sensitive data)
Response Details
- Status code
- Response time
- Error messages (if applicable)
Context
- IP address
- User agent
- Geolocation
- Timestamp (with timezone)

API Audit Log Schema

CREATE TABLE api_audit_logs (
    id BIGSERIAL PRIMARY KEY,

    -- Request identification
    request_id UUID NOT NULL UNIQUE,
    correlation_id UUID,
    session_id VARCHAR(100),

    -- Authentication
    user_id VARCHAR(100),
    service_account VARCHAR(100),
    auth_method VARCHAR(50),

    -- Request details
    http_method VARCHAR(10) NOT NULL,
    endpoint TEXT NOT NULL,
    route_pattern VARCHAR(200), -- e.g., "/api/v1/orders/:id"
    query_params JSONB,
    request_body JSONB,
    request_headers JSONB,

    -- Response details
    status_code INT NOT NULL,
    response_time_ms INT,
    response_body JSONB,
    error_message TEXT,

    -- Context
    ip_address INET,
    user_agent TEXT,
    geo_location JSONB,

    -- Timing
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    -- Additional metadata
    metadata JSONB
);

-- Indexes for common query patterns
CREATE INDEX idx_api_audit_user ON api_audit_logs(user_id, created_at DESC);
CREATE INDEX idx_api_audit_endpoint ON api_audit_logs(route_pattern, created_at DESC);
CREATE INDEX idx_api_audit_status ON api_audit_logs(status_code, created_at DESC);
CREATE INDEX idx_api_audit_created ON api_audit_logs(created_at DESC);
CREATE INDEX idx_api_audit_correlation ON api_audit_logs(correlation_id);

-- GIN index for JSONB queries
CREATE INDEX idx_api_audit_metadata ON api_audit_logs USING GIN(metadata);

API Audit Logging Best Practices

Log Asynchronously
- Don't block API responses
- Use queues (RabbitMQ, Kafka)
- Buffer and batch writes
Sanitize Sensitive Data
- Never log passwords, tokens, credit cards
- Mask or redact PII
- Use allowlist for safe fields
Structured Logging
- Use JSON format
- Consistent field names
- Enable easy parsing/analysis
Implement Log Rotation
- Archive old logs
- Partition tables by date
- Set retention policies
Monitor and Alert
- Set up alerts for anomalies
- Track error rates
- Monitor unusual access patterns
Compliance Considerations
- GDPR: Support right to erasure
- HIPAA: Encrypt at rest and in transit
- SOC 2: Tamper-proof logs

7. Go/PostgreSQL/GORM Implementation Patterns

Architecture Overview

┌─────────────────────────────────────────┐
│         HTTP Handler Layer              │
│  (Middleware: Context, Auth, Logging)   │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│         Service Layer                   │
│  (Business Logic, Validation)           │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│       Repository Layer                  │
│  (Data Access, GORM Operations)         │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│         Database Layer                  │
│  (PostgreSQL + Audit Tables)            │
└─────────────────────────────────────────┘

Pattern 1: GORM Callbacks for Automatic Audit Logging

Concept: Use GORM's hook system to automatically log changes

package models

import (
    "context"
    "encoding/json"
    "time"

    "gorm.io/gorm"
)

// AuditLog represents the audit log table
type AuditLog struct {
    ID          uint           `gorm:"primaryKey"`
    TableName   string         `gorm:"index;not null"`
    RecordID    string         `gorm:"index;not null"`
    Operation   string         `gorm:"index;not null"` // CREATE, UPDATE, DELETE, READ
    OldValue    json.RawMessage `gorm:"type:jsonb"`
    NewValue    json.RawMessage `gorm:"type:jsonb"`
    ChangedBy   string         `gorm:"index"`
    ChangedAt   time.Time      `gorm:"index;not null"`
    IPAddress   string
    UserAgent   string
    SessionID   string         `gorm:"index"`
    RequestID   string         `gorm:"index"`
    Metadata    json.RawMessage `gorm:"type:jsonb"`
}

// Auditable interface for models that support audit logging
type Auditable interface {
    TableName() string
    GetID() string
}

// Order model with audit support
type Order struct {
    ID           uint      `gorm:"primaryKey"`
    OrderNumber  string    `gorm:"uniqueIndex;not null"`
    CustomerID   uint      `gorm:"not null"`
    TotalAmount  float64
    Status       string
    CreatedAt    time.Time
    UpdatedAt    time.Time
}

func (Order) TableName() string {
    return "orders"
}

func (o Order) GetID() string {
    return fmt.Sprintf("%d", o.ID)
}

// RegisterAuditCallbacks registers GORM callbacks for audit logging
func RegisterAuditCallbacks(db *gorm.DB) {
    // After Create
    db.Callback().Create().After("gorm:after_create").Register("audit:after_create", func(db *gorm.DB) {
        if db.Statement.Schema == nil {
            return
        }

        // Check if model implements Auditable
        if auditable, ok := db.Statement.Dest.(Auditable); ok {
            createAuditLog(db, auditable, "CREATE", nil, db.Statement.Dest)
        }
    })

    // After Update
    db.Callback().Update().After("gorm:after_update").Register("audit:after_update", func(db *gorm.DB) {
        if db.Statement.Schema == nil {
            return
        }

        // Get old values before update (stored in context)
        oldValue := db.Statement.Context.Value("audit:old_value")

        if auditable, ok := db.Statement.Dest.(Auditable); ok {
            createAuditLog(db, auditable, "UPDATE", oldValue, db.Statement.Dest)
        }
    })

    // Before Update - capture old values
    db.Callback().Update().Before("gorm:before_update").Register("audit:before_update", func(db *gorm.DB) {
        if db.Statement.Schema == nil {
            return
        }

        // Fetch current values
        if auditable, ok := db.Statement.Dest.(Auditable); ok {
            var oldModel interface{}
            // Clone the model
            db.Session(&gorm.Session{}).
                Where(db.Statement.Schema.PrioritizedPrimaryField.Name+" = ?", auditable.GetID()).
                First(&oldModel)

            // Store in context for after_update
            ctx := context.WithValue(db.Statement.Context, "audit:old_value", oldModel)
            db.Statement.Context = ctx
        }
    })

    // After Delete
    db.Callback().Delete().After("gorm:after_delete").Register("audit:after_delete", func(db *gorm.DB) {
        if db.Statement.Schema == nil {
            return
        }

        if auditable, ok := db.Statement.Dest.(Auditable); ok {
            createAuditLog(db, auditable, "DELETE", db.Statement.Dest, nil)
        }
    })
}

func createAuditLog(db *gorm.DB, auditable Auditable, operation string, oldValue, newValue interface{}) {
    // Get audit context from request context
    ctx := db.Statement.Context

    var oldJSON, newJSON json.RawMessage

    if oldValue != nil {
        oldJSON, _ = json.Marshal(oldValue)
    }
    if newValue != nil {
        newJSON, _ = json.Marshal(newValue)
    }

    auditLog := AuditLog{
        TableName:  auditable.TableName(),
        RecordID:   auditable.GetID(),
        Operation:  operation,
        OldValue:   oldJSON,
        NewValue:   newJSON,
        ChangedBy:  getFromContext(ctx, "user_id"),
        ChangedAt:  time.Now(),
        IPAddress:  getFromContext(ctx, "ip_address"),
        UserAgent:  getFromContext(ctx, "user_agent"),
        SessionID:  getFromContext(ctx, "session_id"),
        RequestID:  getFromContext(ctx, "request_id"),
    }

    // Use a new session to avoid triggering callbacks recursively
    db.Session(&gorm.Session{SkipHooks: true}).Create(&auditLog)
}

func getFromContext(ctx context.Context, key string) string {
    if val := ctx.Value(key); val != nil {
        if str, ok := val.(string); ok {
            return str
        }
    }
    return ""
}

Pattern 2: Repository Pattern with Explicit Audit Logging

Concept: Repository layer explicitly logs changes

package repository

import (
    "context"
    "encoding/json"
    "fmt"
    "time"

    "gorm.io/gorm"
)

// OrderRepository handles order data access
type OrderRepository interface {
    Create(ctx context.Context, order *Order) error
    Update(ctx context.Context, order *Order) error
    Delete(ctx context.Context, id uint) error
    FindByID(ctx context.Context, id uint) (*Order, error)
}

type orderRepository struct {
    db *gorm.DB
    auditRepo AuditRepository
}

func NewOrderRepository(db *gorm.DB, auditRepo AuditRepository) OrderRepository {
    return &orderRepository{
        db: db,
        auditRepo: auditRepo,
    }
}

func (r *orderRepository) Create(ctx context.Context, order *Order) error {
    return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
        // Create order
        if err := tx.Create(order).Error; err != nil {
            return err
        }

        // Log audit
        newValue, _ := json.Marshal(order)
        return r.auditRepo.Log(ctx, AuditEntry{
            TableName: "orders",
            RecordID:  fmt.Sprintf("%d", order.ID),
            Operation: "CREATE",
            NewValue:  newValue,
        })
    })
}

func (r *orderRepository) Update(ctx context.Context, order *Order) error {
    return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
        // Get old values
        var oldOrder Order
        if err := tx.First(&oldOrder, order.ID).Error; err != nil {
            return err
        }

        // Update order
        if err := tx.Save(order).Error; err != nil {
            return err
        }

        // Log audit
        oldValue, _ := json.Marshal(oldOrder)
        newValue, _ := json.Marshal(order)
        return r.auditRepo.Log(ctx, AuditEntry{
            TableName: "orders",
            RecordID:  fmt.Sprintf("%d", order.ID),
            Operation: "UPDATE",
            OldValue:  oldValue,
            NewValue:  newValue,
        })
    })
}

func (r *orderRepository) Delete(ctx context.Context, id uint) error {
    return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
        // Get current values before delete
        var order Order
        if err := tx.First(&order, id).Error; err != nil {
            return err
        }

        // Soft delete
        if err := tx.Delete(&order, id).Error; err != nil {
            return err
        }

        // Log audit
        oldValue, _ := json.Marshal(order)
        return r.auditRepo.Log(ctx, AuditEntry{
            TableName: "orders",
            RecordID:  fmt.Sprintf("%d", id),
            Operation: "DELETE",
            OldValue:  oldValue,
        })
    })
}

Pattern 3: State Machine with Audit Trail

Concept: Explicit state transitions with validation and audit

package statemachine

import (
    "context"
    "fmt"
    "time"

    "gorm.io/gorm"
    "gorm.io/gorm/clause"
)

// OrderState represents valid order states
type OrderState string

const (
    StateCreated         OrderState = "created"
    StatePaymentPending  OrderState = "payment_pending"
    StatePaid            OrderState = "paid"
    StateProcessing      OrderState = "processing"
    StateShipped         OrderState = "shipped"
    StateDelivered       OrderState = "delivered"
    StateCompleted       OrderState = "completed"
    StateCancelled       OrderState = "cancelled"
    StateRefunded        OrderState = "refunded"
)

// StateTransition defines valid transitions
type StateTransition struct {
    FromState OrderState `gorm:"primaryKey"`
    ToState   OrderState `gorm:"primaryKey"`
}

// OrderStateHistory tracks state changes
type OrderStateHistory struct {
    ID              uint       `gorm:"primaryKey"`
    OrderID         uint       `gorm:"index;not null"`
    FromState       OrderState `gorm:"not null"`
    ToState         OrderState `gorm:"not null"`
    TransitionedAt  time.Time  `gorm:"index;not null"`
    TransitionedBy  string     `gorm:"index;not null"`
    Reason          string
    SortKey         int        `gorm:"not null"`
    IsCurrent       bool       `gorm:"not null;default:true"`
    Metadata        string     `gorm:"type:jsonb"`
}

// OrderStateMachine manages order state transitions
type OrderStateMachine struct {
    db *gorm.DB
}

func NewOrderStateMachine(db *gorm.DB) *OrderStateMachine {
    return &OrderStateMachine{db: db}
}

// TransitionTo attempts to transition order to new state
func (sm *OrderStateMachine) TransitionTo(
    ctx context.Context,
    orderID uint,
    toState OrderState,
    user string,
    reason string,
) error {
    return sm.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
        // Lock order row
        var order Order
        if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
            First(&order, orderID).Error; err != nil {
            return fmt.Errorf("order not found: %w", err)
        }

        currentState := OrderState(order.Status)

        // Validate transition
        if err := sm.validateTransition(tx, currentState, toState); err != nil {
            return err
        }

        // Get next sort key
        var maxSortKey int
        tx.Model(&OrderStateHistory{}).
            Where("order_id = ?", orderID).
            Select("COALESCE(MAX(sort_key), 0)").
            Scan(&maxSortKey)
        nextSortKey := maxSortKey + 1

        // Mark current state as not current
        tx.Model(&OrderStateHistory{}).
            Where("order_id = ? AND is_current = ?", orderID, true).
            Update("is_current", false)

        // Create new state history entry
        history := OrderStateHistory{
            OrderID:        orderID,
            FromState:      currentState,
            ToState:        toState,
            TransitionedAt: time.Now(),
            TransitionedBy: user,
            Reason:         reason,
            SortKey:        nextSortKey,
            IsCurrent:      true,
        }

        if err := tx.Create(&history).Error; err != nil {
            return fmt.Errorf("failed to create state history: %w", err)
        }

        // Update order status
        if err := tx.Model(&order).Update("status", string(toState)).Error; err != nil {
            return fmt.Errorf("failed to update order status: %w", err)
        }

        return nil
    })
}

func (sm *OrderStateMachine) validateTransition(tx *gorm.DB, from, to OrderState) error {
    var count int64
    tx.Model(&StateTransition{}).
        Where("from_state = ? AND to_state = ?", from, to).
        Count(&count)

    if count == 0 {
        return fmt.Errorf("invalid state transition: %s -> %s", from, to)
    }
    return nil
}

// GetStateHistory returns the complete state history for an order
func (sm *OrderStateMachine) GetStateHistory(ctx context.Context, orderID uint) ([]OrderStateHistory, error) {
    var history []OrderStateHistory
    err := sm.db.WithContext(ctx).
        Where("order_id = ?", orderID).
        Order("sort_key ASC").
        Find(&history).Error
    return history, err
}

// GetCurrentState returns the current state of an order
func (sm *OrderStateMachine) GetCurrentState(ctx context.Context, orderID uint) (*OrderStateHistory, error) {
    var history OrderStateHistory
    err := sm.db.WithContext(ctx).
        Where("order_id = ? AND is_current = ?", orderID, true).
        First(&history).Error
    return &history, err
}

Pattern 4: Middleware for API Audit Logging

Concept: HTTP middleware captures API request/response details

package middleware

import (
    "bytes"
    "context"
    "encoding/json"
    "io"
    "log"
    "net/http"
    "time"

    "github.com/gin-gonic/gin"
    "github.com/google/uuid"
    "gorm.io/gorm"
)

// APIAuditLog represents API audit log entries
type APIAuditLog struct {
    ID             uint            `gorm:"primaryKey"`
    RequestID      string          `gorm:"uniqueIndex;not null"`
    CorrelationID  string          `gorm:"index"`
    SessionID      string          `gorm:"index"`
    UserID         string          `gorm:"index"`
    HTTPMethod     string          `gorm:"not null"`
    Endpoint       string          `gorm:"not null"`
    RoutePattern   string          `gorm:"index"`
    QueryParams    json.RawMessage `gorm:"type:jsonb"`
    RequestBody    json.RawMessage `gorm:"type:jsonb"`
    RequestHeaders json.RawMessage `gorm:"type:jsonb"`
    StatusCode     int             `gorm:"index"`
    ResponseTimeMs int
    ResponseBody   json.RawMessage `gorm:"type:jsonb"`
    ErrorMessage   string
    IPAddress      string
    UserAgent      string
    CreatedAt      time.Time       `gorm:"index"`
    Metadata       json.RawMessage `gorm:"type:jsonb"`
}

// APIAuditMiddleware logs all API requests and responses
func APIAuditMiddleware(db *gorm.DB) gin.HandlerFunc {
    return func(c *gin.Context) {
        startTime := time.Now()

        // Generate request ID if not present
        requestID := c.GetHeader("X-Request-ID")
        if requestID == "" {
            requestID = uuid.New().String()
            c.Header("X-Request-ID", requestID)
        }

        // Store request ID in context
        ctx := context.WithValue(c.Request.Context(), "request_id", requestID)
        c.Request = c.Request.WithContext(ctx)

        // Capture request body
        var requestBody []byte
        if c.Request.Body != nil {
            requestBody, _ = io.ReadAll(c.Request.Body)
            // Restore body for handler
            c.Request.Body = io.NopCloser(bytes.NewBuffer(requestBody))
        }

        // Create custom response writer to capture response
        blw := &bodyLogWriter{body: bytes.NewBufferString(""), ResponseWriter: c.Writer}
        c.Writer = blw

        // Process request
        c.Next()

        // Calculate response time
        responseTime := time.Since(startTime).Milliseconds()

        // Prepare audit log (async to not block response)
        go func() {
            auditLog := APIAuditLog{
                RequestID:      requestID,
                CorrelationID:  c.GetHeader("X-Correlation-ID"),
                SessionID:      c.GetString("session_id"), // From auth middleware
                UserID:         c.GetString("user_id"),    // From auth middleware
                HTTPMethod:     c.Request.Method,
                Endpoint:       c.Request.URL.Path,
                RoutePattern:   c.FullPath(),
                QueryParams:    toJSON(c.Request.URL.Query()),
                RequestBody:    sanitizeRequestBody(requestBody),
                RequestHeaders: toJSON(sanitizeHeaders(c.Request.Header)),
                StatusCode:     c.Writer.Status(),
                ResponseTimeMs: int(responseTime),
                ResponseBody:   sanitizeResponseBody(blw.body.Bytes()),
                IPAddress:      c.ClientIP(),
                UserAgent:      c.Request.UserAgent(),
                CreatedAt:      startTime,
            }

            // Save to database
            if err := db.Create(&auditLog).Error; err != nil {
                // Log error but don't fail the request
                log.Printf("Failed to create audit log: %v", err)
            }
        }()
    }
}

type bodyLogWriter struct {
    gin.ResponseWriter
    body *bytes.Buffer
}

func (w bodyLogWriter) Write(b []byte) (int, error) {
    w.body.Write(b)
    return w.ResponseWriter.Write(b)
}

func toJSON(v interface{}) json.RawMessage {
    b, _ := json.Marshal(v)
    return b
}

func sanitizeRequestBody(body []byte) json.RawMessage {
    if len(body) == 0 {
        return nil
    }

    var data map[string]interface{}
    if err := json.Unmarshal(body, &data); err != nil {
        return nil
    }

    // Remove sensitive fields
    sensitiveFields := []string{"password", "token", "api_key", "secret", "credit_card"}
    for _, field := range sensitiveFields {
        if _, exists := data[field]; exists {
            data[field] = "[REDACTED]"
        }
    }

    return toJSON(data)
}

func sanitizeResponseBody(body []byte) json.RawMessage {
    // Similar to request sanitization
    return sanitizeRequestBody(body)
}

func sanitizeHeaders(headers http.Header) http.Header {
    sanitized := make(http.Header)
    for k, v := range headers {
        // Skip authorization headers
        if k == "Authorization" || k == "Cookie" {
            sanitized[k] = []string{"[REDACTED]"}
        } else {
            sanitized[k] = v
        }
    }
    return sanitized
}

8. Complete Code Examples

Example 1: Complete Order Management System with Audit

// main.go
package main

import (
    "log"

    "github.com/gin-gonic/gin"
    "gorm.io/driver/postgres"
    "gorm.io/gorm"
)

func main() {
    // Database connection
    dsn := "host=localhost user=postgres password=postgres dbname=orders port=5432"
    db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
    if err != nil {
        log.Fatal("Failed to connect to database:", err)
    }

    // Auto-migrate tables
    db.AutoMigrate(
        &Order{},
        &OrderStateHistory{},
        &StateTransition{},
        &AuditLog{},
        &APIAuditLog{},
    )

    // Seed valid state transitions
    seedStateTransitions(db)

    // Register audit callbacks
    RegisterAuditCallbacks(db)

    // Initialize repositories
    auditRepo := NewAuditRepository(db)
    orderRepo := NewOrderRepository(db, auditRepo)

    // Initialize state machine
    stateMachine := NewOrderStateMachine(db)

    // Initialize services
    orderService := NewOrderService(orderRepo, stateMachine)

    // Setup router
    router := gin.Default()

    // Global middleware
    router.Use(APIAuditMiddleware(db))
    router.Use(AuthMiddleware()) // Your auth middleware

    // Routes
    v1 := router.Group("/api/v1")
    {
        orders := v1.Group("/orders")
        {
            orders.POST("", orderService.CreateOrder)
            orders.GET("/:id", orderService.GetOrder)
            orders.PUT("/:id", orderService.UpdateOrder)
            orders.DELETE("/:id", orderService.DeleteOrder)
            orders.POST("/:id/transition", orderService.TransitionState)
            orders.GET("/:id/history", orderService.GetStateHistory)
        }
    }

    log.Fatal(router.Run(":8080"))
}

func seedStateTransitions(db *gorm.DB) {
    transitions := []StateTransition{
        {FromState: "created", ToState: "payment_pending"},
        {FromState: "payment_pending", ToState: "paid"},
        {FromState: "payment_pending", ToState: "cancelled"},
        {FromState: "paid", ToState: "processing"},
        {FromState: "processing", ToState: "shipped"},
        {FromState: "shipped", ToState: "delivered"},
        {FromState: "delivered", ToState: "completed"},
        {FromState: "paid", ToState: "refunded"},
        {FromState: "processing", ToState: "cancelled"},
    }

    for _, t := range transitions {
        db.FirstOrCreate(&t, t)
    }
}

Example 2: Service Layer with Context Propagation

// service/order_service.go
package service

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "strconv"
    "time"

    "github.com/gin-gonic/gin"
)

type OrderService struct {
    orderRepo    OrderRepository
    stateMachine *OrderStateMachine
}

func NewOrderService(orderRepo OrderRepository, stateMachine *OrderStateMachine) *OrderService {
    return &OrderService{
        orderRepo:    orderRepo,
        stateMachine: stateMachine,
    }
}

type CreateOrderRequest struct {
    CustomerID  uint    `json:"customer_id" binding:"required"`
    TotalAmount float64 `json:"total_amount" binding:"required"`
}

func (s *OrderService) CreateOrder(c *gin.Context) {
    var req CreateOrderRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    // Build context with audit information
    ctx := buildAuditContext(c)

    // Generate order number
    orderNumber := fmt.Sprintf("ORD-%d", time.Now().Unix())

    order := &Order{
        OrderNumber: orderNumber,
        CustomerID:  req.CustomerID,
        TotalAmount: req.TotalAmount,
        Status:      string(StateCreated),
    }

    if err := s.orderRepo.Create(ctx, order); err != nil {
        log.Printf("Failed to create order: %v", err)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to create order"})
        return
    }

    c.JSON(http.StatusCreated, order)
}

func (s *OrderService) TransitionState(c *gin.Context) {
    orderID := c.Param("id")

    var req struct {
        ToState string `json:"to_state" binding:"required"`
        Reason  string `json:"reason"`
    }

    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    ctx := buildAuditContext(c)
    userID := c.GetString("user_id")

    id, _ := strconv.ParseUint(orderID, 10, 64)

    err := s.stateMachine.TransitionTo(
        ctx,
        uint(id),
        OrderState(req.ToState),
        userID,
        req.Reason,
    )

    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    c.JSON(http.StatusOK, gin.H{"message": "State transitioned successfully"})
}

func (s *OrderService) GetStateHistory(c *gin.Context) {
    orderID := c.Param("id")
    id, _ := strconv.ParseUint(orderID, 10, 64)

    ctx := buildAuditContext(c)

    history, err := s.stateMachine.GetStateHistory(ctx, uint(id))
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to get history"})
        return
    }

    c.JSON(http.StatusOK, history)
}

// buildAuditContext extracts audit info from request and builds context
func buildAuditContext(c *gin.Context) context.Context {
    ctx := c.Request.Context()

    // Add audit fields to context
    ctx = context.WithValue(ctx, "user_id", c.GetString("user_id"))
    ctx = context.WithValue(ctx, "session_id", c.GetString("session_id"))
    ctx = context.WithValue(ctx, "ip_address", c.ClientIP())
    ctx = context.WithValue(ctx, "user_agent", c.Request.UserAgent())
    ctx = context.WithValue(ctx, "request_id", c.GetHeader("X-Request-ID"))

    return ctx
}

Example 3: Querying Audit Logs

// repository/audit_repository.go
package repository

import (
    "context"
    "encoding/json"
    "time"

    "gorm.io/gorm"
)

type AuditRepository interface {
    Log(ctx context.Context, entry AuditEntry) error
    GetByRecordID(ctx context.Context, tableName, recordID string) ([]AuditLog, error)
    GetByUser(ctx context.Context, userID string, limit int) ([]AuditLog, error)
    GetByDateRange(ctx context.Context, start, end time.Time) ([]AuditLog, error)
    GetByOperation(ctx context.Context, operation string, limit int) ([]AuditLog, error)
}

type auditRepository struct {
    db *gorm.DB
}

func NewAuditRepository(db *gorm.DB) AuditRepository {
    return &auditRepository{db: db}
}

type AuditEntry struct {
    TableName string
    RecordID  string
    Operation string
    OldValue  json.RawMessage
    NewValue  json.RawMessage
}

func (r *auditRepository) Log(ctx context.Context, entry AuditEntry) error {
    auditLog := AuditLog{
        TableName:  entry.TableName,
        RecordID:   entry.RecordID,
        Operation:  entry.Operation,
        OldValue:   entry.OldValue,
        NewValue:   entry.NewValue,
        ChangedBy:  getFromContext(ctx, "user_id"),
        ChangedAt:  time.Now(),
        IPAddress:  getFromContext(ctx, "ip_address"),
        UserAgent:  getFromContext(ctx, "user_agent"),
        SessionID:  getFromContext(ctx, "session_id"),
        RequestID:  getFromContext(ctx, "request_id"),
    }

    return r.db.WithContext(ctx).Create(&auditLog).Error
}

func (r *auditRepository) GetByRecordID(ctx context.Context, tableName, recordID string) ([]AuditLog, error) {
    var logs []AuditLog
    err := r.db.WithContext(ctx).
        Where("table_name = ? AND record_id = ?", tableName, recordID).
        Order("changed_at DESC").
        Find(&logs).Error
    return logs, err
}

func (r *auditRepository) GetByUser(ctx context.Context, userID string, limit int) ([]AuditLog, error) {
    var logs []AuditLog
    err := r.db.WithContext(ctx).
        Where("changed_by = ?", userID).
        Order("changed_at DESC").
        Limit(limit).
        Find(&logs).Error
    return logs, err
}

func (r *auditRepository) GetByDateRange(ctx context.Context, start, end time.Time) ([]AuditLog, error) {
    var logs []AuditLog
    err := r.db.WithContext(ctx).
        Where("changed_at BETWEEN ? AND ?", start, end).
        Order("changed_at DESC").
        Find(&logs).Error
    return logs, err
}

func (r *auditRepository) GetByOperation(ctx context.Context, operation string, limit int) ([]AuditLog, error) {
    var logs []AuditLog
    err := r.db.WithContext(ctx).
        Where("operation = ?", operation).
        Order("changed_at DESC").
        Limit(limit).
        Find(&logs).Error
    return logs, err
}

9. Summary & Best Practices

Key Takeaways

Choose the Right Pattern
- Simple audit: Row versioning or shadow tables
- Complex domains: Event sourcing
- API tracking: Middleware-based logging
GORM Integration
- Use callbacks for automatic logging
- Leverage context for audit metadata
- Implement repository pattern for clean separation
State Management
- Use state machines for complex workflows
- Enforce valid transitions at database level
- Maintain complete history with sort keys
API Audit Logging
- Log asynchronously to avoid blocking
- Sanitize sensitive data
- Use correlation IDs for distributed tracing
Performance
- Index strategically (user_id, timestamp, table_name)
- Partition large tables by date
- Archive old logs to cold storage
- Use JSONB for flexible metadata
Compliance
- Encrypt sensitive audit data
- Implement log retention policies
- Support right-to-erasure (GDPR)
- Make logs tamper-proof (write-once)
Testing
- Unit test state transitions
- Integration test audit log creation
- Verify sensitive data is sanitized
- Test concurrent state changes

New Year, New You Portfolio Challenge - Building & Deploying My Portfolio with Google Cloud Run

Akkarapon Phikulsri — Fri, 09 Jan 2026 15:22:58 +0000

New Year New You Portfolio Challenge

This is a submission for the New Year, New You Portfolio Challenge Presented by Google AI

About Me

Akkarapon Phikulsri — Software Engineer specializing in Go, Python, C#, and TypeScript. I build scalable systems with modern web frameworks and microservices.

Portfolio

portfolio.refactorroom.com

✨ Take a look at it on Akkarapon Foliokub

How I Built It

I used Google AI Studio to ideate and implement my portfolio for the New Year, New You challenge. I then refined the project locally using Antigravity Editor, enhancing each section with relevant images and showcasing my certificates.

The portfolio is built using React, TypeScript, and Tailwind CSS, focusing on a clean, responsive design and maintainable component structure.

Antigravity I leverage Antigravity to bring my concepts to life, allowing for rapid prototyping and superior design quality.

What I'm Most Proud Of

Custom Animation System Built five reusable animation components (Aurora, ClickSpark, GlitchText, Bounce, FadeContent) that bring the portfolio to life without compromising performance.

Performance-First Custom useInViewOnce hook optimizes animations using Intersection Observer, triggering only when elements enter the viewport.

Project Showcase Two distinct sections (grid + timeline) highlight 14+ projects across backend APIs, mobile apps, and full-stack applications.

Production Deployment Dockerized with Nginx, deployed to Google Cloud Run with automatic scaling—ready for real-world use.

Interactive Portfolio Experience & Leveling System
The portfolio uses an experience (XP) and leveling system that rewards visitors and unlocks sections.
Features

Five XP categories Scroll, Game, Chat, Activity, and Other
Level progression Total level combines all categories (up to 1000)
Section unlocking New sections unlock as level increases
Persistent progress XP saved in localStorage across sessions
Expandable XP bar Shows total XP and detailed category breakdown with progress bars
Level-up celebration Confetti animation on level up with notifications
Visual feedback Gradient progress bars and real-time XP tracking

3D Interactive Skills Sphere
I built an interactive 3D sphere to showcase my technical skills using React Three Fiber. Skills are distributed evenly using the Fibonacci sphere algorithm, and users can rotate and explore the sphere with smooth hover interactions.

Dark Theme Switcher
A custom Dark theme toggle button that smoothly switches between light and dark modes. It remembers user preferences, respects system settings, and includes smooth animations. The entire site, including the 3D sphere, adapts dynamically to theme changes.
Both features improve the user experience and demonstrate modern web development techniques with 3D graphics and smooth state management.

White

Dark

"Take a Break" Game

To add interactivity and a fun easter egg, I built a full-screen canvas-based game that visitors can play directly on the portfolio.

Key Features

Canvas-based gameplay Built with HTML5 Canvas and requestAnimationFrame for smooth 60fps animations
Mouse-controlled ship Players move their cursor to collect colorful orbs floating across the screen
Multiple themes Three visual themes (Space, Neon, Retro) that can be switched on the fly
XP integration Scores earn XP points that integrate with the portfolio's gamification system Animated background Procedurally generated stars that create a dynamic space environment
Collision detection Real-time collision detection using distance calculations
Full-screen immersion Full-screen overlay with hidden cursor for an immersive experience

🐍 Snake Game (Arcade Zone)

Overview
Classic Snake implemented as a responsive web game. Earn XP while playing.

Features

Responsive board 20x20 grid that adapts to screen size (12–25px cells)
Speed settings Slow, Normal, Fast, Very Fast
Controls
- Keyboard Arrow keys or WASD
- Mobile Touch direction buttons
- Spacebar to pause
Scoring 10 XP per food eaten
Game mechanics
- Grow by eating food (red pulsing dots)
- Game over on wall or self collision
- Pause/Resume
- Reset

🎯 Career Simulator Games

Example

Playgroud

Stats

Interactive role-playing scenarios based on real tech work. Earn XP through problem-solving, design decisions, and code challenges.

All simulators use a chat/log interface where you

Receive scenario briefings
Input solutions, code, or decisions
Get AI feedback from role-played colleagues (Junior/Senior Dev, Tech Lead, etc.)
Earn XP based on solution quality
Track progress with saved stats and achievements

Game List

Senior Engineer Simulator
Backend Developer Simulator
Frontend Developer Simulator
System Analysis Simulator
Project Manager Simulator
Database Admin Simulator

The Local Site-Based Simple Chatbot
Instead of relying on external AI APIs, I built a locally-powered chatbot that runs entirely client-side using a curated knowledge base.
Key Features

Zero API dependencies No external API keys or calls—everything runs locally in the browser Curated knowledge base Pre-built responses covering tech stack, projects, career, and engineering philosophy
Smart keyword matching Fuzzy matching and category-based routing to find relevant answers
Suggested questions Category-based question suggestions to guide conversations XP integration Each interaction rewards XP points, encouraging engagement
Typing indicators Realistic typing delays to simulate natural conversation flow
Privacy-first All conversations stay in the browser—no data is sent to external servers

Crafting software requires artistry, guided by imagination, grounded in logic, endlessly enduring. - Akkarapon Phikulsri

Deploy to Google Cloud Run

I will guide you through deploying a static React portfolio website to Google Cloud Run, a fully managed serverless platform.

What is Google Cloud Run?

Google Cloud Run is a fully managed compute platform that automatically scales your stateless containers. It's perfect for deploying static websites and web applications with minimal configuration. Cloud Run automatically handles

HTTPS/TLS certificates
Load balancing
Auto-scaling (including scaling to zero when not in use)
Pay-per-use pricing

Prerequisites

Before starting, ensure you have:

Google Cloud Account (already registered)
Google Cloud SDK - Will be installed in Step 1 below
Docker (optional, for local testing) Install from docker.com

Step 1 Install Google Cloud SDK

Since your internet connection may be unreliable, this step is broken into parts with checkpoints after each section. Each part can be completed independently and verified before proceeding.

Part A Choose Installation Method

First, choose your operating system and preferred installation method:

macOS

Option 1 Homebrew (Recommended - Better for Interruptions)

Homebrew handles retries and resume automatically
Easier to manage updates
Preferred if you already have Homebrew installed

Option 2 Manual Installation

Direct download from Google Cloud
Works without package managers
Requires manual updates

Linux

Option 1 Package Manager (Recommended - Better for Interruptions)

apt for Debian/Ubuntu
yum for Red Hat/CentOS/Fedora
Package managers handle retries better than manual downloads

Option 2 Manual Installation

Direct download script
Works on any Linux distribution

Windows

Option 1 Installer (Recommended)

Windows installer (.msi file)
Handles installation automatically
Can be resumed if interrupted

Option 2 Package Manager (Chocolatey/Winget)

Requires Chocolatey or Windows Package Manager
Easier updates

Part B Installation by Platform

macOS Installation

Using Homebrew (Recommended)

# Check if Homebrew is installed (if not, install from https://brew.sh)
brew --version

# Install Google Cloud SDK
brew install --cask google-cloud-sdk

# Checkpoint Verify installation started
which gcloud

If installation is interrupted

Homebrew automatically resumes from where it left off
Simply re-run brew install --cask google-cloud-sdk
Homebrew will continue from the last checkpoint

Using Manual Installation

# Step 1 Download the SDK (can be resumed if interrupted)
curl https://sdk.cloud.google.com | bash

# If download is interrupted, remove partial download and retry:
# rm -rf ~/google-cloud-sdk
# Then re-run the curl command above

# Step 2 Restart your shell or source the path
exec -l $SHELL

# Or manually add to PATH in your ~/.zshrc or ~/.bash_profile:
# echo 'source "$HOME/google-cloud-sdk/path.bash.inc"' >> ~/.zshrc
# source ~/.zshrc

Checkpoint Verify Part B Complete

# Check if gcloud is accessible
gcloud version

# If successful, you should see version information
# If command not found, restart your terminal or source your shell config

Linux Installation

Using apt (Debian/Ubuntu)

# Part 1 Add Google Cloud SDK repository
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

# If interrupted here, you can skip if the repository was already added (check with):
# cat /etc/apt/sources.list.d/google-cloud-sdk.list

# Part 2 Import Google Cloud public key
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

# If interrupted here, check if key exists:
# sudo apt-key list | grep Google

# Part 3 Update package list
sudo apt-get update

# Part 4 Install Google Cloud SDK
sudo apt-get install google-cloud-sdk

# If installation is interrupted, apt-get will resume automatically:
# sudo apt-get install -f google-cloud-sdk

Checkpoint Verify Part B Complete

gcloud version
# Should display version information if successful

Using yum (Red Hat/CentOS/Fedora)

# Part 1 Add Google Cloud SDK repository
sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-sdk]
name=Google Cloud SDK
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el7-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg
       https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM

# If interrupted here, check if repo file exists:
# cat /etc/yum.repos.d/google-cloud-sdk.repo

# Part 2 Install Google Cloud SDK
sudo yum install google-cloud-sdk

# If interrupted, yum will handle resume automatically

Checkpoint Verify Part B Complete

gcloud version
# Should display version information if successful

Using Manual Installation (Any Linux)

# Step 1 Download the SDK (can be resumed if interrupted)
curl https://sdk.cloud.google.com | bash

# If download is interrupted:
# rm -rf ~/google-cloud-sdk
# Then re-run the curl command

# Step 2 Restart shell or source the path
exec -l $SHELL

# Or add to PATH manually:
# echo 'source "$HOME/google-cloud-sdk/path.bash.inc"' >> ~/.bashrc
# source ~/.bashrc

Checkpoint Verify Part B Complete

gcloud version
# Should display version information if successful

Windows Installation

Using Installer

Download the Google Cloud SDK installer:
- Visit https://cloud.google.com/sdk/docs/install-sdk
- Download the Windows installer (.msi file)
- If download is interrupted, resume or re-download
Run the installer:
- Double-click the downloaded .msi file
- Follow the installation wizard
- If interrupted, re-run the installer (it will resume)
Checkpoint Verify Part B Complete
- Open a new Command Prompt or PowerShell window
- Run gcloud version
- Should display version information if successful

Using Chocolatey (if installed)

# Install Google Cloud SDK
choco install gcloudsdk

# Checkpoint Verify installation
gcloud version

Using Winget (Windows Package Manager)

# Install Google Cloud SDK
winget install Google.CloudSDK

# Checkpoint Verify installation
gcloud version

Part C Initialize and Authenticate

Now that gcloud is installed, initialize and authenticate:

# Step 1 Initialize gcloud
gcloud init

# This will prompt you to
# - Log in with your Google account
# - Choose or create a project
# - Set default region/zone

# If interrupted during initialization:
# Simply re-run gcloud init
# It will resume from where it left off

Alternative Manual Authentication

If gcloud init is interrupted, you can authenticate separately:

# Step 1 Authenticate
gcloud auth login

# This will open a browser for authentication
# If browser doesn't open, use gcloud auth login --no-browser

# Step 2 Set project (after authentication)
gcloud config set project YOUR_PROJECT_ID

# Step 3 Set region (optional, recommended)
gcloud config set run/region asia-southeast1
# or us-central1, europe-west1, etc.

Checkpoint Verify Part C Complete

# Verify authentication
gcloud auth list

# Should show your authenticated account with an asterisk (*)

# Verify current configuration
gcloud config list

# Should show your project, region, etc.

Part D Enable Required APIs

After authentication, enable the APIs needed for Cloud Run

# Enable Cloud Build API
gcloud services enable cloudbuild.googleapis.com

# If interrupted, check which APIs are enabled:
# gcloud services list --enabled

# Enable Cloud Run API
gcloud services enable run.googleapis.com

# Verify both APIs are enabled
gcloud services list --enabled | grep -E "cloudbuild|run"

Checkpoint Verify Part D Complete

# Should show both cloudbuild and run APIs as enabled
gcloud services list --enabled | grep -E "cloudbuild|run"

Installation Complete!

If all checkpoints passed, your Google Cloud SDK is ready. You can verify everything works:

# Full verification
gcloud version
gcloud components list
gcloud config list
gcloud auth list

Step 2 Prepare Your Application

This application uses a multi-stage Docker build:

Build stage Compiles the React application using Node.js
Production stage Serves the static files using Nginx

The Dockerfile is already configured for Cloud Run with:

Port 8080 (Cloud Run default)
Nginx configuration for SPA routing
Optimized multi-stage build

No additional configuration needed. The application is ready to deploy.

Step 3 Deploy to Cloud Run

Method 1 Direct Deployment from Source (Recommended)

This is the easiest method - Cloud Run will build and deploy your application automatically

But it also can do that if you want to build Dockerfile on your locally first before run this command

gcloud run deploy portfolio \
  --source . \
  --platform managed \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --labels dev-tutorial=devnewyear2026 \
  --port 8080

if success it will show like this

Notes

Replace portfolio with your preferred service name
Choose a region closest to your users (e.g., us-central1, asia-southeast1, europe-west1)
The --labels dev-tutorial=devnewyear2026 flag is required if submitting to the Dev.to challenge
--allow-unauthenticated makes your service publicly accessible
--port 8080 matches the port exposed in your Dockerfile

Method 2 Build Docker Image First

If you prefer to build the Docker image locally or using Cloud Build:

# Build the Docker image using Cloud Build
gcloud builds submit --tag gcr.io/$(gcloud config get-value project)/portfolio

# Deploy to Cloud Run
gcloud run deploy portfolio \
  --image gcr.io/$(gcloud config get-value project)/portfolio \
  --platform managed \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --labels dev-tutorial=devnewyear2026 \
  --port 8080

Method 3 Using Cloud Build Config

You can also use the provided cloudbuild.yaml:

gcloud builds submit --config cloudbuild.yaml

Then deploy the built image:

gcloud run deploy portfolio \
  --image gcr.io/$(gcloud config get-value project)/portfolio \
  --platform managed \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --labels dev-tutorial=devnewyear2026 \
  --port 8080

Step 4 Verify Deployment

After deployment, Cloud Run will provide you with a URL

https://portfolio-xxxxx-uc.a.run.app

Visit the URL to verify your portfolio is live! Cloud Run automatically provides:

HTTPS encryption
A custom domain (or you can configure your own)
Global CDN distribution

Step 5 Update and Redeploy

To update your application after making changes

# Simply redeploy (Cloud Run will rebuild if needed)
gcloud run deploy portfolio \
  --source . \
  --platform managed \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --labels dev-tutorial=devnewyear2026 \
  --port 8080

Cost Considerations

Google Cloud Run offers a generous free tier

CPU First 240,000 vCPU-seconds free per month
Memory First 450,000 GiB-seconds free per month
Requests First 2 million requests free per month

For a portfolio website with moderate traffic, you should stay well within the free tier. Cloud Run only charges when requests are being processed (scales to zero).

Useful Commands

# List all Cloud Run services
gcloud run services list

# View service details
gcloud run services describe portfolio --region asia-southeast1

# View logs
gcloud run services logs read portfolio --region asia-southeast1

# Delete service
gcloud run services delete portfolio --region asia-southeast1

# View service URL
gcloud run services describe portfolio --region asia-southeast1 --format='value(status.url)'

Good luck with your deployment! 🚀

DEV Community: Akkarapon Phikulsri

Agent Skill for Debugging Things

Signing PDFs in Go? Meet pdfsign v1.0.0

digitorus / pdfsign

Add/verify Advanced Electronic Signature (AES) and Qualified Electronic Signature (QES) in PDF (using pure Go)

Signing PDF files with Go

Quick Start

Package Architecture

What is pdfsign?

Example 1: Sign a PDF using Go

Example 2 Verify a signed PDF

akkaraponph / pdf-playground

PDF signing playground — pdfsign v1.0.0

Fun Fact

Your AI-Generated UI Doesn't Need Another Gradient

Impeccable: The missing design vocabulary for agents

Start with the task

Pick the relevant prompt

Simpler doesn't mean emptier

Check the awkward states

Keep the change reviewable

akkaraponph / prompt-impeccable

Impeccable UX/UI Prompt Collection

🎯 Categorized by Purpose

1. General Polish & AI-Slop Elimination

Theory of Humanistic Architecture

Humanistic Architecture Learning to See Problems Differently

Anatomy of a Problem

Another model is the 3 Centers Model

The Anatomy of a Problem

The Anatomy of a Problem

The Anatomy of a Problem

Git - Commit Message Format

PostgreSQL Cheat Sheet: Investigating and Terminating Database Blocking Sessions

Why Can PostgreSQL Sessions Block Each Other?

Step 1: Inspect All Non-Idle Sessions

Step 2: Use a Quick Triage Query

Step 3: Find Idle-in-Transaction Sessions

Step 4: Terminate an Idle Transaction

Step 5: Cancel a Running Query

pg_cancel_backend() vs pg_terminate_backend()

Step 6: Find Who Is Blocking a Query

Finding the Root Blocker

Step 7: Check Which Database Uses the Most Connections

Step 8: Check Connection Headroom

Preventing Idle Transactions

Protect Against Long-Running Queries

Log Lock Problems

Fix the Problem in the Application

Connection Pools Matter Too

My Production Troubleshooting Flow

Useful Commands Summary

Final Thoughts

Fixing "GOPROXY list is not the empty string, but contains no entries" in Go

What This Error Actually Means

Step-by-Step Fix

1. Check for a shell-level override

2. Clear the session override

3. Persist a valid proxy in Go's config

4. Sanity-check related settings

5. Clear Go's caches if the problem persists

6. Retry

Windows/MINGW64 Gotcha

Quick Reference Checklist

Command Cheat Sheet

GitHub Spark - A First Look at GitHub’s New Developer Tool

What is GitHub Spark?

Quick prompt

Referencing Repositories

Comparison with Lovable

Playground

Theme

Data Mockup

Assets

Turning Assets into Action

akkaraponph / income-expense

for fundamental data science

Datasets-Income-Expense

For fundamental data science

Simple Datasets

`pg_cancel_backend()` vs `pg_terminate_backend()`