Shannon's Software Engineering Blog

Project — Agentic DDD Platform

2026-03-24T00:00:00Z

This post is still a work-in-progress, and will most likely be worked-on in stealth mode. (:

Before diving deeper into the Agentic Workflow space, let's work on a project to have some direction.

Domain Driven Design (DDD) has a large influence on how I think about systems, but is hard to apply effectively, especially when working in teams within an organization who do not know much about it.

Now that Agentic Workflows are becoming the norm, and LLMs can heavily abstract away the mechanics of applying DDD effectively, this seems like a good project to work on.

Agentic DDD Platform

The DDD methodology provides a framework from converting formal business language into working systems. By having visibility into actual business workflows, an engineer can effectively implement just enough features to meet business objectives, hence reducing the overall complexity, and achieving maximum impact or value creation.

The goal of this platform is to translate a business from a user's point-of-view, described by a business domain expert, and construct deployable technical artifacts to create a minimal working system to meet those business needs.

The inputs will be from 2 personas: (1) Domain Expert; (2) Software Engineer. The domain expert will describe the user interactions with the system, and the software engineer will enhance the intermediary artifacts generated by the platform from the domain expert's input. The platform will support multiple iterations between the domain expert and the software engineer before generating outputs. This output construct will be in the form of multiple technical artifacts like code, binaries, containers, infrastructure-as-code descriptions, etc, which the software engineer will use to deploy the system.

The value of this platform is in the iterative collaboration aspect between technical and non-technical folks. When building a large system, it is largely a discovery process where the constraints may not be known upfront; i.e. its not possible to fully describe an entire system in a few prompts or a markdown file. By building iteratively, the team can create checkpoints at various points in the project lifecycle and branch out when an idea or experiment does not work.

The structure of this System Design document is explained in this post.

System Design

DDD Strategic Design

Persona	Interaction
Expert	Enters a prompt in the Role-Feature-Reason format describing the business from a certain user's point-of-view, so that an agent can create a System Design document from the prompt.
Expert	Reviews & edit the generated System Design document (non-technical) so that it can be as accurate as possible.
Expert	Saves the workspace with a specific version number so that it can be build upon in the future.
Engineer	Reviews the technical portion of the generated System Design document so that one can understand more about the business domain.
Engineer	Enters a prompt in Cucumber / Gherkin format to describe how the aggregates interact within the overall system so that the technical portion of the System Design can get updated automatically.
Engineer	Edits the technical portion of the generated System Design document so that more details can be manually added or corrected.
Engineer	Saves the workspace with a specific version number so that it can be build upon in the future.
Engineer	Initiates generation of deployment artifacts so that the system can be deployed in an out-of-band manner.

The domain of the Agentic DDD Platform is as follows:

Events	Objects	Transactions
WorkspaceCreated	Workspace	CreateWorkspace
WorkspaceUpdated		UpdateWorkspace
WorkspaceDeleted		DeleteWorkspace
PromptSent	Prompt	SendPrompt
PromptResponse
DocumentCreated	Document	CreateDocument
DocumentEdited		EditDocument
UserCreated	User	CreateUser
UserUpdated		UpdateUser
UserDeleted		DeleteUser

DDD Tactical Design

Collaboration Workflow

sequenceDiagram
  actor user as Expert / Engineer / AI Agent
  participant docServer as Document Server
  participant Database@{ "type" : "database" }
  docServer->>user: Server-Sent-Events connection
  user ->> docServer: POST: Updates document
  docServer -->> user: 200
  docServer ->> Database: Periodically saves document to DB
  Database -->> docServer: 200

Prompt Workflow

sequenceDiagram
  actor expert as Expert / Engineer
  participant promptServer as Prompt Server
  participant Database@{ "type" : "database" }
  participant agent as Agent
  participant llm as LLM Server
  participant docServer as Document Server
  expert->>promptServer: POST: prompt
request
  promptServer->>promptServer: Validate prompt
  promptServer->>Database: insert prompt request
  Database-->>promptServer: success
  promptServer-->>expert: 200
  agent->>Database: POLL: Read prompt request
  Database-->>agent: success
  loop till no more prompts
    agent->>llm: Prompt the LLM
    llm-->>agent: LLM response
    alt new prompt
      agent->>Database: insert prompt request
      Database-->>agent: success
    end
  end
  agent->>Database: Create prompt response
  Database-->>agent: success
  agent->>docServer: POST: Updates document
  docServer-->>agent: 200
  expert->>promptServer: GET: prompt
response
  promptServer->>Database: Read prompt response
  Database-->>promptServer: success
  promptServer-->>expert: 200

Artifact Generation Workflow

sequenceDiagram
  actor engineer as Engineer
  participant artifactServer as Artifact Server
  participant Database@{ "type" : "database" }
  participant agent as Agent
  participant llm as LLM Server
  engineer->>artifactServer: POST: Generate
Artifacts
  artifactServer->>Database: insert GenerateArtifacts request
  Database-->>artifactServer: success
  agent->>Database: POLL: Read GenerateArtifacts request
  Database-->>agent: success
  agent->>Database: Read current Document state
  Database-->>agent: success
  agent->>llm: Convert Document to structured JSONL
  llm-->>agent: JSONL responses
  loop till no more JSONL
    agent->>agent: Generate Technical Artifact based on current JSONL
    agent->>Database: Save Artifact into DB
    Database-->>agent: success
  end
  agent->>Database: Create GenerateArtifacts response
  Database-->>agent: success
  engineer->>artifactServer: GET: GenerateArtifacts
response
  artifactServer->>Database: Read GenerateArtifacts response
  Database-->>artifactServer: success
  artifactServer->>artifactServer: Compress Artifacts into a single object
  artifactServer-->>engineer: Compressed Artifacts download

Non-Functional Requirements

TBD

API Endpoints

TBD

Capacity Estimation

TBD

Cost Estimation

TBD

System Architecture

TBD

Context Engineering

2026-02-16T00:00:00Z

In the previous post, Ollama was setup locally and it can be queried upon through the HTTP API. The question now is how do we enhance the LLM with tools such that it can help the users achieve what they want, without over-engineering a solution.

IMPORTANT! DO NOT OVER-ENGINEER A SOLUTION!

REPEAT AFTER ME.

DO NOT OVER-ENGINEER A SOLUTION!

It is so easy to fall into the trap of over-engineering. If the LLM does not respond correctly, excited engineers may just start writing IF-ELSE statements to correct the answer. Do not get in the LLM way. If there is no straight forward path with a prompt and one level of depth of tools, just ask your scientist to give you a better model.

Start Simple

Let's start with a simple scenario.

Prompt: What is 1+1?
Response:
{
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{ \"result\": \"2\" }"
  },
  // ...
}

Prompt: What is a LLM?
Response:
{
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{ \"answer\": \"A Large Language Model (LLM) is an artificial intelligence model that can generate human-like text based on input data. It has been trained on vast amounts of text data and can understand, analyze, and generate language in various ways.\" }"
  },
  // ...
}

Asking 2 different simple questions, will result in totally 2 different responses with differing data structures. One stores the reply in a result field while the other stores it in the answer field. As an engineer, we need to deterministically retrieve the responses in a structured manner. Luckily there is the Format field we can pass in during the request.

Format Responses

type OllamaResponseFormat struct {
	Type       string                       `json:"type,omitempty"`
	Properties map[string]map[string]string `json:"properties,omitempty"`
	Required   []bool                       `json:"required,omitempty"`
}
// Request Object
{
  // ...
  OllamaResponseFormat{
    Type:       "object",
    Properties: map[string]map[string]string{
      "answer": {
        "type": "string",
      },
    }
  }
}

By setting the format before prompting, we can get structured responses as shown below, where all replies are within the answer field and it must be a string.

Prompt: What is 1+1?
Response:  {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{ \"answer\": \"2\" }"
  },
  // ...
}

Prompt: What is a LLM?
Response:  {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{ \"answer\": \"A Large Language Model (LLM) is an artificial intelligence model that can generate human-like text based on input data. It has been trained on vast amounts of text data and can be used for various applications such as language translation, summarization, question answering, and more.\" }"
  },
  // ...
}

Supercharge the LLM with Tools

As mentioned earlier we need to enhance the LLM with tools such that it can do more than what it was trained to do.

NOTE: The LLM is just a brain that decides which tool to use. The actual computation needs to be written by the engineer. This is currently commonly done through the concept of Model Context Protocol (MCP) servers.

The structure of a Tool is shown below.

type OllamaFunctionParameter struct {
	Type       string          `json:"type" description:"Return type of the current function."`
	Required   []string        `json:"required" description:"Which parameters are required in the function call."`
	Properties json.RawMessage `json:"properties" description:"Details about the parameters."`
}

type OllamaFunction struct {
	Name        string                  `json:"name" description:"Name of the Function."`
	Description string                  `json:"description" description:"What the Function does."`
	Parameters  OllamaFunctionParameter `json:"parameters" description:"Parameters that get passed to the Function."`
}

type OllamaTool struct {
	Type     string         `json:"type" description:"The type of Tool; i.e. Function"`
	Function OllamaFunction `json:"function" description:"A Tool that is of Function type."`
}

tools := []OllamaTool{{
		Type: "function",
		Function: OllamaFunction{
			Name:        "GetWeatherTemperature",
			Description: "Get the Temperature.",
			Parameters:  OllamaFunctionParameter{},
		},
	}, {
		Type: "function",
		Function: OllamaFunction{
			Name:        "GetTime",
			Description: "Get the Time.",
			Parameters:  OllamaFunctionParameter{},
		},
	}, {
		Type: "function",
		Function: OllamaFunction{
			Name:        "GetLLMDefinition",
			Description: "Get the LLM definition.",
			Parameters:  OllamaFunctionParameter{},
		},
	}
}

Let's ask the LLM, what the weather is.

When querying with the Tools defined, the response is as follows:

Prompt: What is the Weather now?
Tools: <tools>
Response: {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{\"answer\":\"GetWeatherTemperature\"}"
  },
  // ...
}

We can then Prompt again with the Tool result as follows:

type OllamaMessage struct {
	Role    string `json:"role" description:"Who is requesting the message."`
	Content string `json:"content" description:"The actual message content."`
}
// Request Object
{
  // ...
  []OllamaMessage{{
    Role:    "user",
    Content: "What is the Weather now?",
  }, {
    Role:    "assistant",
    Content: "{\"answer\": \"GetWeatherTemperature\"}",
  }, {
    Role: "tool",
    Content: "11 degrees celsius",
  }}
}

The second Prompt request includes the conversation history along with the Tool call and its result.

The response can be seen below.

Response:  {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{\"answer\": \"The current temperature is 11 degrees Celsius.\"}"
  },
  // ...
}

Hallucination

Prompt: What is the time now?
Tools: <tools>
Response: {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{\"answer\":\"1683240000\\"}"
  },
  // ...
}

When querying with the Prompt above, the LLM assumes that it knows the answer, but it is clearly wrong.

Because we expect an 'answer' as defined in Format options, the LLM responds with what it assumes is the current time.

// Request Object
{
  // ...
  OllamaResponseFormat{
    Type:       "object",
    Properties: map[string]map[string]string{
      "answer": {
        "type": "string",
      },
      "function_call": {
        "type": "string",
      },
    }
  }
}

By adding a new field function_call to the Format options, we allow the LLM to make a choice to call a Tool.

The response is as follows:

Response: {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{\"function_call\": \"GetTime\"}"
  },
  // ...
}

We can see that the LLM now uses the Tool to get the time.

Testing the changes with other Prompts

Let's ask the 1+1 question again.

Prompt: What is 1+1?
Tools: <tools>
Response: {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{\"function_call\":\"GetLLMDefinition\\\"}"
  },
  // ...
}

What... Why is it asking for LLM definition??? Is it just a lousy model? Is it bad prompting? Can't be... This is such a simple scenario. Honestly, who knows? The LLM is a black box! MOVING ON!

If we remove all the Tools from the Prompt request, then it can respond with the answer "2".

Dynamic Contexts

We need a way to dynamically inject tools to the Prompt request. However, remember that we DO NOT WANT to over-engineer a solution.

Let's ask the LLM to do it for us.

System Prompt:
Tools available:
- GetWeatherTemperature: Get the current temperature.
- GetTime: Get the current time.
- GetLLMDefinition: Get the definition of a LLM.

Prompt:
What tool is needed to answer the question "What is 1+1?"
You may return empty string if no suitable tool is available.

Response: {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{\"function_call\":\"\\\"}"
  },
  // ...
}

After defining the Tools available in the System Prompt, we ask the LLM to setup which Tools we should use for our Prompt. In this scenario, none of the Tools are compatible to answer the question "What is 1+1?"

Now we can programmatically know to not send the Tools with the Prompt, allowing the LLM to derive the answer.

Prompt: What is 1+1?
Tools: nil
Response:  {
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{ \"answer\": \"2\" }"
  },
  // ...
}

Conclusion

Start simple with the goal of defining the structure of the responses.
Iterate across sample prompts, to catch edge cases.
Establish 2-stage prompting, whereby the LLM first decides what Tools to use, followed by fulfilling the actual prompt made by the user using the insight gained on the compatibility of Tools available in the first prompt.

By following the above methodology, I believe an "AI Engineer" may find more success in achieving business objectives!

Appendix (Data Structures for Ollama)

type OllamaMessage struct {
  Role    string `json:"role" description:"Who is requesting the message."`
  Content string `json:"content" description:"The actual message content."`
}

type OllamaFunctionParameter struct {
  Type       string          `json:"type" description:"Return type of the current function."`
  Required   []string        `json:"required" description:"Which parameters are required in the function call."`
  Properties json.RawMessage `json:"properties" description:"Details about the parameters."`
}

type OllamaFunction struct {
  Name        string                  `json:"name" description:"Name of the Function."`
  Description string                  `json:"description" description:"What the Function does."`
  Parameters  OllamaFunctionParameter `json:"parameters" description:"Parameters that get passed to the Function."`
}

type OllamaTool struct {
  Type     string         `json:"type" description:"The type of Tool; i.e. Function"`
  Function OllamaFunction `json:"function" description:"A Tool that is of Function type."`
}

// ModelOptions defines common model parameters for the Options field
type ModelOptions struct {
  // Temperature controls randomness (0.0 to 1.0)
  Temperature *float64 `json:"temperature,omitempty"`

  // TopP controls diversity via nucleus sampling (0.0 to 1.0)
  TopP *float64 `json:"top_p,omitempty"`

  // TopK limits token selection to top K
  TopK *int `json:"top_k,omitempty"`

  // NumPredict sets maximum number of tokens to predict
  NumPredict *int `json:"num_predict,omitempty"`

  // RepeatPenalty penalizes repetition (1.0 = no penalty)
  RepeatPenalty *float64 `json:"repeat_penalty,omitempty"`

  // PresencePenalty penalizes new tokens based on presence
  PresencePenalty *float64 `json:"presence_penalty,omitempty"`

  // FrequencyPenalty penalizes new tokens based on frequency
  FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`

  // Mirostat enables mirostat sampling
  Mirostat *int `json:"mirostat,omitempty"`

  // MirostatTau sets target entropy for mirostat
  MirostatTau *float64 `json:"mirostat_tau,omitempty"`

  // MirostatEta sets learning rate for mirostat
  MirostatEta *float64 `json:"mirostat_eta,omitempty"`

  // Stop sets custom stop sequences
  Stop []string `json:"stop,omitempty"`

  // Seed sets random seed for reproducibility
  Seed *int `json:"seed,omitempty"`
}

type OllamaResponseFormat struct {
  Type       string                       `json:"type,omitempty"`
  Properties map[string]map[string]string `json:"properties,omitempty"`
  Required   []bool                       `json:"required,omitempty"`
}

type OllamaRequest struct {
  Model string       `json:"model" description:"LLM model to be used."`
  Tools []OllamaTool `json:"tools" description:"List of Tools the LLM can use."`

  // Depending on the model, either field is used
  Messages []OllamaMessage `json:"messages,omitempty" description:"List of messages in the current prompt."`
  Prompt   string          `json:"prompt,omitempty"`

  // Optional fields
  Suffix    string               `json:"suffix,omitempty"`
  Images    []string             `json:"images,omitempty"` // base64-encoded images
  Format    OllamaResponseFormat `json:"format,omitempty"`
  Options   ModelOptions         `json:"options,omitempty"`
  System    string               `json:"system,omitempty"`
  Template  string               `json:"template,omitempty"`
  Stream    *bool                `json:"stream,omitempty" description:"To stream the response or not."`
  Raw       bool                 `json:"raw,omitempty"`
  KeepAlive int                  `json:"keep_alive,omitempty"`

  // Experimental image generation fields
  Width  int `json:"width,omitempty"`
  Height int `json:"height,omitempty"`
  Steps  int `json:"steps,omitempty"`

  // Thinking models parameter
  Think bool `json:"think,omitempty"`
}

type OllamaResponse struct {
  Model     string        `json:"model" description:"LLM model to be used."`
  Message   OllamaMessage `json:"message" description:"List of messages in the current prompt."`
  Response  string        `json:"response"`
  Done      bool          `json:"done" description:"Response is done streaming."`
  CreatedAt time.Time     `json:"created_at" description:"Timestamp when response was created."`

  // Additional fields present only when Done = true
  Context            []int  `json:"context,omitempty"`
  TotalDuration      int64  `json:"total_duration,omitempty"` // nanoseconds
  LoadDuration       int64  `json:"load_duration,omitempty"`  // nanoseconds
  PromptEvalCount    int    `json:"prompt_eval_count,omitempty"`
  PromptEvalDuration int64  `json:"prompt_eval_duration,omitempty"` // nanoseconds
  EvalCount          int    `json:"eval_count,omitempty"`
  EvalDuration       int64  `json:"eval_duration,omitempty"` // nanoseconds
  DoneReason         string `json:"done_reason,omitempty"`
}

type AnyFunc func(...interface{}) interface{}

AI Agents

2026-02-08T00:00:00Z

Disclaimer: I am not an "AI Engineer" or whatever that means. This post describes my thoughts and reflections on the current landscape at this current point in time, and may very well change in the future.

RAG

I was scrolling X one day and saw this post about RAG. I thought "Whoa! The AI landscape has evolved so much!". So I started going down the rabbit hole, trying to understand what RAG is.

Retrieval-augmented generation (RAG) is a technique that enhances large language models (LLMs) by allowing them to retrieve and incorporate new information from external data sources before generating responses. This approach improves the accuracy and relevance of the information provided by the LLMs.
- Wikipedia

So apparently this is a technique used to interface with an LLM? Okay, what exactly is this technique I wondered. So I went to setup my own LLM, and since I have a MacBook, I went with the Ollama setup.

Ollama

Looking at the docs, Ollama exposes a HTTP endpoint where we can send HTTP request to interface with the model.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5-coder:3B",
  "messages": [{
    "role": "user",
    "content": "What are you?"
  }],
  "stream": false
}'

There is this concept of Tools as well, which we can prompt the LLM to use.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5-coder:3B",
  "messages": [{
    "role": "user",
    "content": "What are you?"
  }],
  "stream": false,
  "tools": [
    "type": "function",
    "function": {
      "name": "ask_god",
      "description": "Prays to God for an answer.",
      "parameters": {
        "type": "object",
        "required": ["god_name"],
        "properties": {
          "god_name": {
            "type": "string",
            "description": "The name of the God you wish to pray to."
          }
        },
      },
    }
  ]
}'

If the LLM does not know the answer, the response will request the use of Tools available. The engineer will then have to write code to call the specific tool and pipe the response back to the LLM. An example is shown below.

// Initial Response
{
  "model": "qwen2.5-coder:3B",
  "message": {
    "role": "assistant",
    "content": "{\"name\": \"ask_god Prays to God for an answer.\", \"arguments\": {\"god_name\": \"Some God\"}}"
  },
  //...
}
// Reply with Tool answer
{
  //...
  {"role": "tool", "tool_name": "ask_god", "content": "I am GOD!"}
}

So apparently this technique is just a mechanism for piping JSON object messages back-and-forth between an engineer's code and the LLM. Why is there a need to create so many complicated fancy names for this back-and-forth messaging?

Engineers VS Scientists

From an engineer's point-of-view, we only care about improving production metrics.

When developing a feature, the first question we ask ourselves is that is it working or is it correct. When relying on an LLM system, the correctness largely depends on the LLM component as it is probabilistic in nature. It is not the job of an engineer to solve accuracy issues but that of a data scientist. But hey, RAG exists so that engineers can direct the LLM to find a correct answer right? NO! I strongly believe that is the wrong thought process to have as one would end up over-engineering a solution to the problem. If one cares about complete correctness, an engineer should not rely on a probabilistic engine but code out the exact requirements needed for the problem.

Okay so we accept that it may not be accurate but it can still provide good summaries of information and possibly be a good assistant. Using ChatGPT, DeepSeek, Grok, etc. is great for querying or generating information and content. So why do we not just embed these models into our applications? The answer is cost; it is expensive to host and maintain such a large model while scaling it to many clients.

The value comes from choosing a small model to keep cost low, and making it work for a particular business use-case; possibly using RAG.

The engineer can monitor the number of tokens consumed by the model, along with the end-to-end latency of request(s), when attempting to "solve" a business problem. The results can be benchmarked with the latest state-of-the-art models in terms of accuracy, with the goal of reducing the metrics mentioned above as much as possible to keep cost low.

My future posts will dive deeper into such problems, and attempt to define what an "AI Engineer" actually is.

Fun Fact: The So-So-Ah-So post tag is just to state that the current post is a reflection post. So-So-Ah-So is a Singapore singlish way of talking, whereby our sentences continuously have the word "so" to prove a point.

pprof CPU

2026-02-03T00:00:00Z

This is Part 7 of the Magic Link System Design Series.

CPU

The above CPU flamegraph shows the CPU utilization after the memory optimizations made in the previous post.

As seen in the flamegraph, the Magic Link handler takes up less than half of the CPU utilization during the sample period. This is expected as it is a very simple handler. Majority of the compute in the handler is used for encryption, while the rest is part of the HTTP lifecycle.

One area of optimization would be the fmt.Fprint section that is part of the Gin logger. Every request coming in will be logged synchronously, triggering syscalls which consumes CPU utilization.

Benchmarks

When dealing with CPU utilization or latency, we need to gather baseline metrics of our system before making improvements, such that we can compare the results.

// benchmark_test.go
package main

import (
	"net/http"
	"net/http/httptest"
	"testing"
)

const (
	Host               = "http://127.0.0.1:8080"
	GenerateMagicRoute = "/magic/generate"
)

func BenchmarkGin(b *testing.B) {
	router := NewRouter(true)
	req, err := http.NewRequest(http.MethodPost, Host+GenerateMagicRoute, nil)
	req.Header.Set("X-CSRF-Token", generateCsrf())
	if err != nil {
		b.Error(err)
		return
	}
	b.ResetTimer()
	for b.Loop() {
		w := httptest.NewRecorder()
		router.ServeHTTP(w, req)
	}
}

The above code shows a simple benchmark test that is focus on the Magic Link handler, with the results shown below.

Benchmark Results (baseline)

Metrics Legend

Symbol	Description
op	Operation
ns	Nano-seconds
allocs	Number of Memory Allocations
B	Bytes Allocated

Buffered Logging

Writing logs to disk synchronously per request is slow. Unless your system is fragile, and you fear that logs go missing on your critical path, it makes sense to buffer the incoming logs before writing them to disk; grouping such calls reduce syscalls.

The logging library Zap, supports this and is the fastest so far among other libraries.

...using encoding/json and fmt.Fprintf to log tons of interface{} makes your application slow...
- https://github.com/uber-go/zap

When replacing the default Gin logger, we need to add 2 middlewares: (1) Logging; (2) Recovery.

func MiddlewareZapLogger(logger *zap.Logger) gin.HandlerFunc {
	return func(c *gin.Context) {
		start := time.Now()
		path := c.Request.URL.Path
		raw := c.Request.URL.RawQuery
		if raw != "" {
			path = path + "?" + raw
		}

		c.Next()

		latency := time.Since(start)

		logger.Info("http request",
			zap.Int("status", c.Writer.Status()),
			zap.String("method", c.Request.Method),
			zap.String("path", path),
			zap.String("ip", c.ClientIP()),
			zap.Duration("latency", latency),
			zap.String("user_agent", c.Request.UserAgent()),
			zap.Int("bytes_out", c.Writer.Size()),
			zap.String("errors", c.Errors.ByType(gin.ErrorTypePrivate).String()),
		)
	}
}

func MiddlewareZapRecovery(logger *zap.Logger) gin.HandlerFunc {
	return gin.CustomRecovery(func(c *gin.Context, recovered any) {
		logger.Error("panic recovered",
			zap.Any("error", recovered),
			zap.String("method", c.Request.Method),
			zap.String("path", c.Request.URL.Path),
		)
		c.AbortWithStatus(http.StatusInternalServerError)
	})
}

func main() {
  // ...

  logger, err := zap.NewProduction()
	if err != nil {
		_ = fmt.Errorf("failed to run router: %w", err)
		return
	}
	defer logger.Sync()
  router := gin.New()
	router.Use(MiddlewareZapLogger(logger))
	router.Use(MiddlewareZapRecovery(logger))

  // ...
}

Running the benchmarks again, we can see the optimized results below.

Benchmark Results (Optimized)

Using the Zap logger, latency was improved by (22614-5430) / 22614 = ~76%. This is a huge speed improvement!

CPU (Optimized)

Looking at the flamegraph, we can see that the fmt.Fprint section is gone, and that the syscalls are greatly reduced.

The CPU utilization is still low as we can't increase the number of concurrent requests due to the RSS limit mentioned here.

Check out the example project here!
https://github.com/sh4nnongoh/go-csrf-magic-links/tree/cpu

pprof Memory Optimization

2026-02-01T00:00:00Z

This is Part 6 of the Magic Link System Design Series.

In the previous post we identified areas for optimization, with the memory allocation being the most obvious one.

Heap Allocated Space

The Magic Link Generation handler has 2 main areas with high memory allocation: (1) Cookie Serialization; (2) HTML Generation.

The serializer exists to convert client information, in the form of key-value pairs, into an encoded string that represents the cookie. This cookie is attached to the HTTP request.

// Serialize encodes a value using gob.
func (e GobEncoder) Serialize(src interface{}) ([]byte, error) {
	buf := new(bytes.Buffer)
	enc := gob.NewEncoder(buf)
	if err := enc.Encode(src); err != nil {
		return nil, cookieError{cause: err, typ: usageError}
	}
	return buf.Bytes(), nil
}

Looking at the Serialize function above, each time it is called a new bytes buffer is created. This is inefficient as the buffer will be discarded after each request; we need a way to reuse the buffer across requests.

Sync Pool is a library that aims to solve this, by creating a pool of objects that can be reused without triggering the GC.

Furthermore, the GobEncoder uses reflection to infer types during runtime which takes up memory and introduces latency.

go-json is a library aimed to solve these shortcomings by using Sync Pool for buffer reuse along with other optimizations mentioned here.


import (
   // ...
	"bytes"

	"github.com/goccy/go-json"
)

type JSONEncoder struct{}

func (e JSONEncoder) Serialize(src interface{}) ([]byte, error) {
	var data interface{}
	switch v := src.(type) {
	case map[string]interface{}:
		data = src
	case map[interface{}]interface{}:
		converted := make(map[string]interface{})
		for k, val := range v {
			converted[fmt.Sprint(k)] = val
		}
		data = converted
	default:
		data = src
	}
	buf := new(bytes.Buffer)
	enc := json.NewEncoder(buf)
	if err := enc.Encode(data); err != nil {
		return nil, cookieError{cause: err, typ: usageError}
	}
	return buf.Bytes(), nil
}

func (e JSONEncoder) Deserialize(src []byte, dst interface{}) error {
	dec := json.NewDecoder(bytes.NewReader(src))
	if err := dec.Decode(dst); err != nil {
		return cookieError{cause: err, typ: decodeError}
	}
	return nil
}

func main() {
  // ...
  codec := securecookie.New(authKeyMagic, encryptKeyMagic)
  codec.SetSerializer(JSONEncoder{})
  // ...
}

Since we are using JSON encoding, we need to cast the interface{} data type to map[string]interface{}, in order for the library to serialize successfully.

Heap Allocated Space Serializer Optimized

By switching to the new library, we can see the allocated memory drop by ~300MB! That is a significant improvement.

HTML Generation

The default HTML template parses the the file system for template files and uses reflection at runtime to infer what the HTML should be as seen in the flamegraph. This is done for each request and is extremely slow and memory inefficient.

Using the Templ library, these HTML templates are converted to Go code in the build stage, and compiles down to native binary together with the webserver. As a result, rendering a HTML response is extremely fast with minimal memory allocations.

Heap Allocated Space HTML Optimized

By switching to the new library, we can see the allocated memory further drop by ~200MB! That is another significant improvement.

Check out the example project here!
https://github.com/sh4nnongoh/go-csrf-magic-links/tree/templ

pprof Analysis

2026-01-31T00:00:00Z

This is Part 5 of the Magic Link System Design Series.

Now that we have generated the pprof profiles for our Magic Link app, let's start analyzing them.

There are a lot of information provided by the profiles, and in order to not get overwhelmed, we need to adopt a strategy to analyze them.

Strategy

Flamegraph is a visualization of hierarchical data to visualize stack traces of profiled software so that the most frequent code-paths can be identified quickly and accurately.
- brendangregg

We will be mostly using flamegraphs to analyze the profile data. Flamegraphs provide a high level overview of the time or resource spent in certain areas of your app, and because it uses a collection of bar graphs, we can easily identify bottlenecks by looking at the width of a bar relative to the overall app.

Below are the various sections of profile analysis, and I recommend going through them sequentially in order to not get overwhelmed.

Resource Utilization

Latency Reduction

Resource Utilization

Blocking Operation

For I/O-bound latency, blocking profiles reveal goroutines waiting. Examples include: Network calls (HTTP, database, Redis); Channel operations with slow consumers; Mutex contention (use mutex profile separately).

go tool pprof -http=:8082 ./block.pprof

Most likely due to the fact that we are running everything on localhost, hence, there is no information here. Will elaborate more on this in future posts!

Mutex

The mutex profile builds on the block profile to focus on mutexes.

go tool pprof -http=:8082 ./mutex.pprof

The Magic Link Generation handler is currently not dealing with mutexes for resource sharing, hence, there is no information here.

Goroutine

The Goroutine profile shows the goroutines present within the sample period, with each branch representing different types of goroutines triggered within the app. When looking at the flamegraph, identify the total number of goroutines spawned in the top right corner. It should be similar to the number of concurrent requests made during the load test. Also to look out for "waiting on channel that never receives" in your application code to identify leaks.

go tool pprof -http=:8082 ./goroutine.pprof

Number of Goroutines

By referencing the flamegraph, it can be seen that the number of goroutines spawned (517) is approximately equal to the concurrent requests (500) made during the load test. It can also be seen that there is only one branch of goroutines which is inline with our implementation. In conclusion, there is no issue here.

Heap

The heap profiles show the amount of memory allocated along with the amount of memory actually in-use during the sample period. The allocated memory is usually large as the Garbage Collector (GC) is constantly reclaiming memory throughout the app lifecycle, whilst the in-use memory details memory that the GC will not work on, and should remain low.

go tool pprof -http=:8082 ./heap_rate.pprof

Heap Allocated Space

Heap In-Use Space

Click to show/hide invalid old content

I had a wrong understanding on the matter, detailed below.

Looking at the 2 flamegraphs above, it can be seen that the in-use space (10.24MB) is much smaller than the allocated space (1.33GB). That means that the current allocated memory utilization is only ~0.7%! That is extremely low! The in-use memory utilization is very low as well (10.24MB / 64MB ~= 16%).

~~There are opportunities for improvements here.~~

Remember that our Docker container is only allocated 64MB of memory? Have you wondered how is it possible for the memory allocation during load test to reach 1.8GB? This is because of the wonderful Garbage Collector present in Go programs. It is so efficient that it can handle our badly written code effectively at scale; i.e. 500 concurrent requests. Memory is constantly allocated per request and discarded at the end. Although the GC is efficient, it still provides an opportunity to make improvements to our app.

Basically, we do not want the allocated memory to grow exponentially over time, such that we rely too much on the GC. Each time the GC runs, the app basically pauses and that introduces latency. Once the allocated memory utilization is stable, we mostly likely can increase the number of concurrent requests to increase the in-use memory utilization, making full use of our resources while increasing throughput.

Looking at the top right corner of each memory profile, we can see the memory allocated or in-use by the app during the load test. I once thought that the high allocated memory was an issue but in fact, that number alone does not mean anything. Instead, we need to take the rate of change of how the allocated memory grows with the increase in concurrent requests. For this app, the allocated memory and in-use memory remains relatively constant as the concurrent requests increases. The in-use memory should also be much lower than the allocated memory to ensure that there are no memory leaks in the app such that the GC is unable to reclaim them; in this case the in-use memory is fine as well.

Another reason to optimize the allocated memory is when the CPU utilization on GC is high (>10%); more on that in the next section.

Areas of optimization can be seen in the flamegraph: the Serializer and the HTML templating engine.

CPU

The CPU profile shows the time spent processing tasks in various sections of the app. The CPU utilization of the app can be calculated by taking the percentage of the CPU time spent (top right corner of the flamegraph) against the sample period. A low CPU utilization means that the app can handle more concurrent requests to make more use of the CPU.

go tool pprof -http=:8082 ./cpu.pprof

CPU

Resident Set Size (RSS) is the portion of memory (measured in kilobytes) occupied by a process that is held in main memory (RAM).
- Wikipedia

The current CPU utilization is (14.83s / 30s ~= 49%). This means that the CPU still has room to process more concurrent requests, but due to the app reaching the RSS limits as seen in the Docker metrics, the app can't handle more concurrent requests.

CPU GC (TOP 10)

The Top 10 GC related functions utilize only about ~5% of the CPU utilization. Hence, there is no issue with the memory allocation mentioned in the previous section.

Latency Reduction

CPU

When focusing on latency reduction, one needs to dive deep into the sections of the flamegraph to identify optimization areas. Once an area is identified, perform benchmarking to get a baseline of the current metrics, make the necessary improvements, then run the benchmark again to quantify the actual improvements gained.

Referencing the CPU flamegraph in the previous section, we can see that our Magic Link Generation handler consumed 38.6% of the overall CPU, and (38.6% / 89.8% ~= 43%) of the http request & response lifecycle.

Before optimizing the actual application code written by the developer, we should try to remove or reduce other sections of code that consumes the CPU.

Looking at the fmt.Fprint under the gin.LoggerWithConfig.func1 section, we can see that it takes up 9.2% of the overall CPU. We can look at optimizing the default logger for gin, before optimizing else where.

When dealing with latency, we will need to do proper benchmarking in-order to quantify the potential gains achieved. Betterstack has a good article describing this process.

Conclusion

The app is currently fine and there is no need for optimizations as there will be diminishing returns with respect to the effort needed.

However for practice, the priority of optimization tasks is as follows:

To increase the allocated memory utilization of the app.
To increase the in-use memory utilization of the app.
To reduce the latency of our app.

Stay tuned to future blog posts where we will dive deep into each area!

Check out the example project here!
https://github.com/sh4nnongoh/go-csrf-magic-links

pprof & Load Testing

2026-01-26T00:00:00Z

This is Part 4 of the Magic Link System Design Series.

pprof is a tool for visualization and analysis of profiling data. It reads a collection of profiling samples in profile.proto format and generates reports to visualize and help analyze the data. It can generate both text and graphical reports (through the use of the dot visualization package).
- Google

In the previous post, we built a simple Go webapp using the Gin webserver for authentication of users using Magic Links. However, how do we know that it actually works at scale? We need a way to benchmark the app with a proper load and see if it can support the number of users expected to use our app with an appropriate level of resource constraints to match business requirements. This is where pprof comes in handy, as it is already built into the Go package.

import (
	// ...

	//nolint:gosec // G108: pprof is only exposed on internal environments
	_ "net/http/pprof"

    // ...
)

func main() {
	// Start pprof HTTP server
	go func() {
		srv := &http.Server{
			Addr:         ":6060",
			ReadTimeout:  5 * time.Second,
			WriteTimeout: 5 * time.Second,
			IdleTimeout:  5 * time.Second,
		}

		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			log.Fatalf("server failed: %v", err)
		}
	}()
    // ...
}

Importing the "net/http/pprof" package and spinning up a http server, will enable pprof analysis at the /debug/pprof/ route of your application.

As a side-note, gosec linting package will flag this as a security issue as it assumes you are exposing profiling data publicly. Remember that in the larger system architecture, your webserver will not be public facing and is usually hidden behind a proxy. A bastion host is usually setup for system administrators or engineers to interact with the pprof endpoints. Therefore, we can ignore this specific linting rule.

BASE_URL=http://localhost:6060
SAMPLING_PERIOD=30

# CPU Profile
curl -s "${BASE_URL}/debug/pprof/profile?seconds=${SAMPLING_PERIOD}"
# I/O Profile
curl -s "${BASE_URL}/debug/pprof/block?seconds=${SAMPLING_PERIOD}"
# Lock Contention Profile
curl -s "${BASE_URL}/debug/pprof/mutex?seconds=${SAMPLING_PERIOD}"
# # To answer: "How many objects are we creating per request?"
curl -s "${BASE_URL}/debug/pprof/heap?seconds=${SAMPLING_PERIOD}"

# Goroutine Profile
curl -s "${BASE_URL}/debug/pprof/goroutine?debug=2"
# Save inuse_objects (currently live objects)
curl -s "${BASE_URL}/debug/pprof/heap"
# Save inuse_space (bytes currently in use)
curl -s "${BASE_URL}/debug/pprof/heap"

# The ?gc=1 parameter triggers garbage collection before sampling

# Save alloc_objects (total allocations during profile)
curl -s "${BASE_URL}/debug/pprof/heap?gc=1"
# Save alloc_space (bytes allocated)
curl -s "${BASE_URL}/debug/pprof/heap?gc=1"

Once the server is up, we can gather metrics of our system by perform a GET request on the respective endpoints shown above.

We can then use the command line go tool to evaluate each profile accordingly; i.e. go tool pprof -http=:8081 ./cpu.pprof

The benchmarking script is defined in the repository as well.

Load Testing

Now that our server is ready to gather profiling metrics. We need to write a script to perform actual load testing on our server.

// ...

const (
	ConcurrentRequestsCount   = 500
	BenchmarkDurationSeconds  = 60
	Host                      = "http://127.0.0.1:8080"
	GenerateMagicRoute        = "/magic/generate"
)

func main() {

    // ...

	client := &http.Client{
		Timeout: 5 * time.Second,
	}

    // (1) Defining Context and Resource Management Constructs
	ctx, cancel := context.WithTimeout(context.Background(), BenchmarkDurationSeconds*time.Second)
	defer cancel()
	group, ctx := errgroup.WithContext(ctx)
	semaphore := make(chan struct{}, ConcurrentRequestsCount)

loop:
	for {
		select {
		case <-ctx.Done():
			break loop
		default:
            // (2) Trigger Requests in Goroutines
			semaphore <- struct{}{}
			group.Go(func() error {
				defer func() {
					<-semaphore
				}()
				req, err := http.NewRequestWithContext(ctx, http.MethodPost, Host+GenerateMagicRoute, nil)
				if err != nil {
					return err
				}
				req.Header.Set("X-CSRF-Token", generateCsrf())
				res, err := client.Do(req)
				if err != nil {
					return err
				}
                // Important! Need to read the body to release the http connection back to the pool.
				io.ReadAll(res.Body)
				defer res.Body.Close()
				return nil
			})
		}
	}
	if err := group.Wait(); err != nil {
		log.Println("request failed:", err)
	}

    // ...
}

In the /cmd/benchmark/main.go directory, a Go program is written to perform concurrent requests to the server's endpoints.

(1) Defining Context & Resource Management Constructs

A context is defined with a timeout parameter, to tell our program to exit once it reaches the time limit. This context is attached to an errgroup which is the construct that performs the actual concurrent requests. (For those familiar with Javascript, an errgroup is similar to Promise.All()). A semaphore is also defined which represents the maximum number of concurrent requests that can be made to our server.

(2) Trigger Requests in Goroutines

The whole request lifecycle is encapsulated within a Goroutine, and this Goroutine is only triggered once a lock can be claimed from the semaphore. For this load testing, the endpoint for Magic Link generation will be used.

An important note when performing a high number of HTTP requests is that most libraries will pool the HTTP connections, such that the program does not overload the number of network sockets on the system. In order for a HTTP connection to be considered "completed", the body of the response received after performing a request needs to be read fully. Otherwise, the HTTP connection will not be returned to the connection pool, and as a result, the client will experience a socket exhaustion error while performing the load test.

Docker

"What do you mean there is an issue? IT WORKS ON MY MACHINE!"
- I am always right engineer

In order for our experiment to produce consistent results, we leverage on Containers to encapsulate our program.

# Stage 1: Build the Go application
FROM golang:1.25-alpine AS builder

WORKDIR /app

# Copy go mod files
COPY go.mod go.sum ./
RUN go mod download

# Copy source code
COPY . .

# Build the application with optimizations
# -ldflags="-s -w" strips debug symbols, reducing binary size
# CGO_ENABLED=0 creates static binary, no C dependencies
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -a -o main .

# Stage 2: Create minimal runtime image
FROM scratch

# Copy only the built binary, and public assets from the builder stage
COPY --from=builder /app/main /main
COPY --from=builder /app/static /static
COPY --from=builder /app/templates /templates

# Copy CA certificates for HTTPS if needed
# COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# Expose ports
EXPOSE 8080 6060

# Run as non-root user for security
USER 1000:1000

# Set minimal environment
ENV GOMAXPROCS=1

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD ["/main", "health"] || exit 1

ENTRYPOINT ["/main"]

The above script shows a Dockerfile, for packaging our application into a production ready container.

docker run -d \  --name myapp \
  --memory=64m \     
  --memory-swap=64m \
  --memory-swappiness=0 \
  --cpus="0.5" \
  -p 8080:8080 \
  -p 6060:6060 \
  -e GIN_MODE=release \
  myapp:latest

When invoking the container, a strict constrained environment can be defined to test specific areas of our application. An example is shown above.

The parameters of our Load Testing script can be defined by experimenting with the values, and observing the stability of the container metrics in the Docker Desktop UI. In our scenario, 500 concurrent requests is a good number to start with for a 64MB container.

Check out the example project here!
https://github.com/sh4nnongoh/go-csrf-magic-links

More details into pprof analysis will be in the next post. Stay tuned!

CSRF with Magic Links

2026-01-22T00:00:00Z

This is Part 3 of the Magic Link System Design Series.

As a recap, a Magic Link contains an encrypted token containing the identity of a particular user. By that definition, anyone clicking that link can impersonate the identify encoded in the link. Doesn't that sound familiar? (Cough, Cough - Netflix)

In order to prevent that we need a way for the link to only work for the original requester, and that is where CSRF tokens come in handy.

Cross-Site Request Forgery (CSRF) is an attack that forces an end user to execute unwanted actions on a web application in which they’re currently authenticated. With a little help of social engineering (such as sending a link via email or chat), an attacker may trick the users of a web application into executing actions of the attacker’s choosing. If the victim is a normal user, a successful CSRF attack can force the user to perform state changing requests like transferring funds, changing their email address, and so forth. If the victim is an administrative account, CSRF can compromise the entire web application.
- OWASP

CSRF + Cookies

Before discussing CSRF tokens with Magic Links, let's take a look at how CSRF tokens work with cookies. After a user gets authenticated, a cookie is usually created by the server and assigned to the user. This cookie would contain data identifying the user, and will be attached to every request made by the user to the server. Knowing this, an adversary could trick users into submitting authenticated transactions without their knowledge. A common example would be the user visiting the adversary site which triggers requests to a known webapp used by the user.

<!-- Adversary site has the following elements -->

 <!-- A form that secretly performs a POST 
  to a known site used by the User -->
<form action="https://bank.example.com/transfer" method="POST">
  <input type="hidden" name="to_account" value="attacker123">
  <input type="hidden" name="amount" value="1000">
</form>

<!-- OR -->

<!-- Loading an img element which basically 
 performs a hidden GET request -->
<img src="https://bank.example.com/transfer?to=attacker123&amount=1000">

A CSRF token is a nounce of a certain size that is random across sessions and users.

In order to prevent such attacks, the CSRF token needs to be sent with the requests alongside the authentication cookies. The server will compare the request's CSRF token with the session's state, which could either be stored server-side like in Redis, or in our scenario, in the encrypted cookie.

The above sequence diagram shows the following:

When the user navigates to the /login page, a CSRF token generated by the server is present in the meta tag of the page.
Upon logging in, the CSRF token is attached in the header of the POST request along with the login credentials.
The server verifies the credentials and, if successful, creates an encrypted cookie containing the user's identity along with the CSRF token.
Any future authenticated requests made to the server will have the attached CSRF token in the header compared with the CSRF token stored in the encrypted cookie. Even if the cookie is valid, an invalid CSRF token check will render the request invalid.

There is no way for an adversary site to capture this CSRF token embedded in our site.

CSRF + Magic Links

A Magic Link basically has the encrypted cookie as part of the URL. The question now is how does the user send the CSRF token in the header by just clicking a link? You might have noticed when using certain secure sites like banking, there is some sort of "/verification" intemediary page before the site shows you your dashboard. This intermediary page actually captures the encrypted cookie in the Magic Link along with the CSRF token in the browser and performs the actual POST request of logging into the secure site.

The above sequence diagram shows the following:

The Magic Link navigates the user to the "/verification" page.
The "/verification" page performs a POST request with the encrypted cookie and CSRF token to login the user.
The server decrypts the cookie and compare the embedded CSRF token, with the token in the header.
If valid, a new session is created for the user with a new encrypted cookie returned to the user.
Future requests to the secure site, will have the encrypted cookie in the request. The client will have to send the CSRF token in the header for the requests to be successful.

When navigating the secure site through the UI, the CSRF token can be easily accessed to be attached to the request. However, if the user were to click on a link to access the site, a "/verification" page willstill be needed to properly authenticate the user by capturing the CSRF token in the browser.

So back to the issue at hand, the Magic Link needs to only work in the same browser that triggers the Magic Link generation. Similar to the /login page example in the previous section, the CSRF token is embedded in the browser when the users generate a Magic Link with their email. Therefore, the Magic Link sent to their emails will only work if the users open the links with the same browser session that triggered the generation; as that is where the CSRF token is embedded.

Implemention

In this section we will cover the implementation details for a minimal CSRF Magic Link example with Go, Gin, HTML templating, and HTMX.

HTMX is amazing but we will not be covering that in this post.

The web server is setup as follow:

package main

import (
	"crypto/rand"
	"net/http"

	"github.com/gin-contrib/sessions"
	"github.com/gin-contrib/sessions/cookie"
	"github.com/gin-gonic/gin"
	"github.com/gorilla/securecookie"
)

func main() {
    // (1) Defining keys & store
	authKeyMagic := make([]byte, 32)
	encryptKeyMagic := make([]byte, 32)
	rand.Read(authKeyMagic)
	rand.Read(encryptKeyMagic)
	codec := securecookie.New(authKeyMagic, encryptKeyMagic)
	codec.MaxAge(60 * 60 * 15)
	codecs := []securecookie.Codec{codec}

	authKeyCookie := make([]byte, 32)
	encryptKeyCookie := make([]byte, 32)
	rand.Read(authKeyCookie)
	rand.Read(encryptKeyCookie)
	storeCookies := cookie.NewStore(authKeyCookie, encryptKeyCookie)
	storeCookies.Options(sessions.Options{
		Path:     "/",
		MaxAge:   60 * 60 * 60 * 3,
		HttpOnly: true,
		Secure:   false,
	})

    // (2) Routes
	router := gin.Default()
	err := router.SetTrustedProxies([]string{"127.0.0.1"})
	if err != nil {
		panic(err)
	}
	router.LoadHTMLGlob("templates/*.go.tmpl")
	router.Static("/static", "./static")
	router.Use(sessions.Sessions(COOKIE_STORE_NAME, storeCookies))
	router.POST("/magic/generate", handleMagicLinkGeneration(codecs))
	router.POST("/magic/verify/:magic", handleMagicLinkVerification(codecs))
	router.GET("/magic/verify/:magic", func(c *gin.Context) {
		c.HTML(http.StatusOK, "check-auth.go.tmpl", gin.H{
			"route": "",
		})
	})
	router.GET("/secure/:id", func(c *gin.Context) {
		c.HTML(http.StatusOK, "check-auth.go.tmpl", gin.H{
			"route": c.Request.URL.Path,
		})
	})
	router.POST("/secure/:id", handleSecure)
	router.GET("/login", MiddlewareNoCache(), func(c *gin.Context) {
		c.HTML(http.StatusOK, "login.go.tmpl", gin.H{
			"csrfToken": generateCsrf(),
		})
	})
	router.Run()
}

(1) Defining keys & store

Hash-based Message Authentication Code (HAMC), is a cryptographic technique that combines a hash function with a secret key to verify the integrity and authenticity of a message. It ensures that the message has not been altered during transmission and confirms that it comes from a legitimate source.

The reason why we have 2 keys, is that one is used for HMAC while the other is for encryption. HMAC is needed so that adversaries are not able to successfully mutate the ciphertext of the encrypted cookie such that the decrypted version is still semantically valid.

We also define 2 separate key pairs as one is for Magic Links, while the other is for the actual encrypted session cookies.

The expiry of the keys are defined here as well and should match what is stated in the Non-Functional requirements.

(2) Routes

You may have noticed that secured routes have both a GET and a POST method. This is to support URL navigation, whereby the check-auth page is rendered to capture the CSRF token in the browser before attempting to retrieve the secured resources with a POST.

(3) Minimal Javascript

// Read from meta tag and store in localStorage
const csrfMeta = document.querySelector('meta[name="csrf-token"]')?.content;
if (csrfMeta) {
  localStorage.setItem('csrfToken', csrfMeta);
}

// Attach CSRF token from meta tag or localstorage to HTMX request
document.addEventListener('htmx:configRequest', (event) => {
  event.detail.headers['X-CSRF-Token'] =
    csrfMeta || localStorage.getItem('csrfToken')
});

With HTMX, there is minimal need to introduce javascript into our webapp. However, as we will be using the browser's localstorage to store the CSRF token, javascript is still needed. The above code snippet shows the minimal code needed to store and retrieve the CSRF token.

Demo

Your browser does not support the video tag.

The above video shows the full capabilities of our Magic Link site!

Check out the example project here!
https://github.com/sh4nnongoh/go-csrf-magic-links

Magic Links

2026-01-19T00:00:00Z

This is Part 2 of the Magic Link System Design Series.

"Hey Shannon! Your previous post talks about Magic Links but there were no details at all about implementing them!"
- random reader

Hey, I hear you! In the previous post, I gave an example System Design writeup for XYZ Auth to implement Magic Links for the organisation. However, remember that System Design documents are living documents, and the previous post was just to highlight the structure of the document.

In this post we will build upon the System Design in the previous post with details on how Magic Links will be implemented. Specifically, we will create technical artifacts to be placed in the Tactical Design section of the System Design document.

Magic Links are a mechanism for users to access secure resources without needing to enter passwords.

Sequence Diagrams

The best way to explain how Magic Links work is to use Sequence Diagrams.

The above sequence diagram shows the happy path of a Magic Link usage.

Users enter their email in the Login page.
The backend checks if the email exists in the database.
If the email exists, generate an encrypted cookie detailing who the user is.
Create a Magic Link with the encrypted cookie as a URL param.
Send the Magic Link to the user's email address.
User clicks the Magic Link, and upon success, gets redirected to the protected page.

One of the beautiful features of Magic Links is that they use Stateless Cookies. Stateless means that the backend does not need to verify if the content in the Cookie is valid or not; it simply trusts it. This greatly reduces the number of network calls to databases as shown in the sequence diagram above; there is only 1 database call at the beginning, and future visits to protected resources will simply succeed if the Cookie has not expired.

"But won't clients just mutate their Cookies to impersonate other people?"
- concerned reader

In order to prevent manipulation of the Cookie, the Cookie will be encrypted by the server during creation. Only the server has the private key, hence adversaries will not be able to mutate the Cookie to suit their needs. Referring to the System Architecture diagram in the previous post, these private encryption keys will be stored in Vercel's Key-Value stores, such that the backend will have access to them to decrypt / validate incoming requests and their respective Cookies.

Non-Functional Requirements

There are security pitfalls associated with Stateless Cookies, and these need to be captured in the Non-Functional Requirements of a System Design document.

Example Additional requirements:

The encryption key needs to be rotated every 7 days.
The Cookie in the Magic Link should expire within 15 minutes.
Refreshed Cookies should expire within 60 minutes, before needing a new Magic Link.
To adopt the Double-Submit Cookie Pattern, when generating a Cookie.

Check out my new Go library for creating encrypted Cookies!
https://github.com/sh4nnongoh/ironsession

System Design

2026-01-16T00:00:00Z

This is Part 1 of the Magic Link System Design Series.

System Design is such a broad topic, with many different styles adopted by different people. It only became popular recently when it became a requirement during interviews for software engineering roles. This blog is not about tips & tricks for passing half-hour session interviews, but a more realistic take on building systems that lasts.

The basic study of system design is the understanding of component parts and their subsequent interaction with one another.
- Wikipedia

Every system is built to solve a problem faced by someone or a business, and people tend to lose sight of that when the team or organisation starts growing. This could be because of how workers are hired for a specific role within a problem but are not directed to solve the business problem. As it is human nature to want to suceed and improve, these individual workers start implementing and improving onto their individual areas in isolation, which Inevidently, results in creating a more complicated and messy system over time.

The heart of software is its ability to solve domain-related problems for its user.
- Eric Evans

That is where Domain Driven Design (DDD) comes in, as it brings the problem-solving focus back to the actual issue at hand. It starts by formalizing the language used by the domain-experts and stakeholders, such that engineers can actually use those terminologies during their design and implementation. This solves a huge communication gap between the non-technical and technical folks. As conversations regularly take place between stakeholders, DDD provides a framework for capturing important details in the domain. These details are also commonly known as Objects & Events in the software engineering world (more on that later).

I will not be diving deep into what DDD is in this blog, but will cherry-pick concepts from it to apply to my approach to System Design.

To give you a glimpse of what I am talking about, below is a simple System Design document leveraging DDD for building an authentication service for XYZ startup. These System Design documents are living documents that gets updated over time, and what is shown below is just a snapshot in the whole system life cycle.

XYZ Auth

Company XYZ requires a secure way to authenticate its users accessing its app. To keep costs low, and not be subjected to GDPR related policies, passwords cannot be stored within the system. Consulting with the Security Engineer in the team, he advises to use Magic Links as a quick and simple way to authenticate users.

System Design

DDD Strategic Design

The goal of strategic design is to formalize the language between stakeholders and can be categorized into 3 categories: (1) Events; (2) Objects; (3) Transactions.

Events represent the past and act as the source of truth; they are stored in databases. Objects are models that represent the current state of the domain and are derived from the events that occur over time. Transactions work with objects within the domain to generate events that changes the various objects of the domain.

Conversations need to happen with the Domain Experts, and I personally use a simple Persona table to describe such conversations on what they expect the interaction will be like.

The expected interactions with XYZ Auth are as follows:

Persona	Interaction
User	User enters email and requests for Magic Link.
User	User clicks on Magic Link and navigates to the Home page of the App.
User	User clicks on expired / invalid Magic Link and navigates to the HTTP 401 page of the App.
Admin	Admin enters email and requests for Magic Link.
Admin	Admin clicks on Magic Link and navigates to the Admin App.
Admin	Admin adds Users to the system by entering their emails.
Admin	Admin removes Users from the system by deleting their emails.

The domain of XYZ Auth is as follows:

Events	Objects	Transactions
UserAdded	User	AddUser
UserRemoved		RemoveUser
UserRequestsMagicLink		RequestMagicLink
UserLogin		LoginUser

DDD Tactical Design

This section is where a software engineer provides technical artifacts such as ER diagrams or sequence diagrams.

Based on the events and objects identified in the Strategic Design stage, the above Entity-Relationship diagram is drawn.

Non-Functional Requirements

Non-Functional requirements are tricky; and can very often be mixed up with the Domain requirements.

These are very important requirements that are not part of the domain.

The Magic Link will only work on the same browser that was used to generate the Magic Link. This is enforced using CSRF tokens.

API Endpoints

The endpoints are derived from transactions needed in the Strategic Design phase

POST /api/v1/login
POST /api/v1/login?magic={string}
POST /api/v1/users
POST /api/v1/users/{id}
GET /api/v1/users
GET /api/v1/users/{id}

Capacity Estimation (Data Storage)

Using the ER diagrams described in the Tactical Design stage, provide a back-off-the-envelope estimation of the storage / memory needed for an estimated number of users.

Referencing the data structures for Postgres, the estimation is as follows:

id: 16 bytes
event_type: 1 byte * size = 16 bytes
user_id: 16 bytes
created_at: 16 bytes
email: 128 bytes
is_admin: 1 byte

Hence, an AuthEvent is estimated to be at most (16 + 16 + 16 + 16 + 128 + 1) = 193 bytes.

With a 1GB Postgres instance, we can store approximately ~5.1 million auth events.

Cost Estimation

Based on the estimates done earlier, you can also estimate the cost of your design. Depending on your service provider, there may be calculators available to estimate the costs of the system.

AWS Calculator

System Architecture

This is where the whole architecture of your system is shown. If the system is large, you may add accompanying flow diagrams as well.

Shannon's Software Engineering Blog

Project — Agentic DDD Platform

Agentic DDD Platform

Table of Contents

System Design

DDD Strategic Design

DDD Tactical Design

Collaboration Workflow

Prompt Workflow

Artifact Generation Workflow

Non-Functional Requirements

API Endpoints

Capacity Estimation

Cost Estimation

System Architecture

Context Engineering

Start Simple

Format Responses

Supercharge the LLM with Tools

Hallucination

Testing the changes with other Prompts

Dynamic Contexts

Conclusion

Appendix (Data Structures for Ollama)

AI Agents

Engineers VS Scientists

pprof CPU

Benchmarks

Metrics Legend

Buffered Logging

pprof Memory Optimization

Cookie Serialization

HTML Generation

pprof Analysis

Strategy

Table of Contents

Resource Utilization

Blocking Operation

Mutex

Goroutine

Heap

CPU

Latency Reduction

CPU

Conclusion

pprof & Load Testing

Load Testing

(1) Defining Context & Resource Management Constructs

(2) Trigger Requests in Goroutines

Docker

CSRF with Magic Links

CSRF + Cookies

CSRF + Magic Links

Implemention

(1) Defining keys & store

(2) Routes

(3) Minimal Javascript

Demo

Magic Links

Sequence Diagrams

Non-Functional Requirements

System Design

XYZ Auth

Table of Contents

System Design

DDD Strategic Design

DDD Tactical Design

Non-Functional Requirements

API Endpoints

Capacity Estimation (Data Storage)

Cost Estimation

System Architecture