This resume is also available in English.

CHAPTER 03

Tech articles

One online shop's order service grows from a single Go program into a microservice system on Kubernetes. 43 articles, each picking up where the last left off.

1. Go foundations

  1. 01 Go Project Layout and Go Modules Starting from go mod init, this article explains how modules, packages and directories relate, how to lay out cmd and internal, how Go picks dependency versions, and when a multi-service repository should use one module or a go.work workspace. Create a module and understand go.mod · A package is a directory · Lay out the skeleton with cmd and internal · Let the entry point know its own version · Add dependencies and understand minimal version selection 18 min read
  2. 02 Error Handling in Go: Wrapping, Sentinels and Custom Types Starting from the fact that error is just an interface, this article layers on %w wrapping, sentinel errors, custom error types, errors.Join and boundary translation to build error handling that services can inspect, log and expose safely. error is just an interface · Wrap with %w to keep the error chain · Sentinel errors and errors.Is · Custom error types and errors.As · Multiple errors: errors.Join 15 min read
  3. 03 Goroutines, Channels and Concurrency Patterns in Go Starting from launching a goroutine, this article walks through WaitGroup, data races and mutexes, channel semantics, select, worker pools and pipelines, then bounded concurrency, error collection and goroutine leaks. Start a goroutine and wait for it to finish · Shared memory, data races and Mutex · Channels: passing data between goroutines · select: waiting for several things at once · Worker pools and pipelines 16 min read
  4. 04 Go context: Cancellation, Timeouts and Request-Scoped Values This article shows how contexts form a cancellation tree, how WithCancel and WithTimeout carry cancellation and deadlines from an HTTP handler to every goroutine and downstream call, and how to use WithCancelCause, AfterFunc, WithoutCancel and WithValue correctly. The Context interface and the basic rules · WithCancel and the cancellation tree · WithTimeout, WithDeadline and the timeout budget · Explain why with WithCancelCause · AfterFunc: run clean-up on cancellation 14 min read

2. Writing a service

  1. 05 net/http and Middleware in Go Build the HTTP entry point of an order service with only the standard library: Go 1.22 method and wildcard routing, composable middleware (request IDs, slog logging, panic recovery, body limits) and sensible http.Server timeouts. Understand the Handler interface first · Go 1.22's routing rules · Middleware is just a function · Intercept the status code and write a logging middleware · Assemble a complete middleware chain 18 min read
  2. 06 Layered Architecture and Dependency Injection in Go Split the order service into handler, service and repository layers: consumer-defined interfaces, constructor injection and a single composition root in main give you testable, swappable Go code without any DI framework. Separate the three responsibilities · Directories and packages · The consumer defines the interface · Constructor injection · Connect the three layers, keeping errors intact across them 15 min read
  3. 07 database/sql, Transactions and Connection Pools in Go Write a database-backed repository for the order service: understand that sql.DB is a connection pool, close rows correctly, handle NULL and ErrNoRows, use transactions so stock and orders change together, and tune the pool to avoid overselling and exhaustion. sql.DB is not a connection, it is a connection pool · Create the tables and read data correctly · Pass a context with every call · Tune the connection pool · Use a transaction so several writes succeed or fail together 17 min read
  4. 08 Testing in Go: Table-Driven Tests, httptest and Integration Tests Test every layer of the order service: table-driven tests for business-rule edge cases, httptest to verify handlers without a running server, and build-tagged integration tests against a real database that prove transactions and oversell protection actually work. The basic rules of go test · Table-driven tests · Isolate dependencies with test doubles · Test the handler with httptest · Integration tests against a real database 18 min read

3. Splitting into microservices

  1. 09 When to Split: Service Boundaries and Decomposition Strategies Microservices are not the default answer. Starting from a modular monolith, this article shows how to find boundaries with bounded contexts and data ownership, migrate piece by piece with the strangler fig pattern, and recognise when not to split at all. First, admit the monolith is not the problem · Draw module boundaries inside the monolith · Find the real boundaries with bounded contexts · Data ownership is the real dividing line · Move one small piece at a time with the strangler fig pattern 15 min read
  2. 10 gRPC and Protocol Buffers in Go Define service-to-service interfaces with a single .proto contract, generate type-safe Go code with protoc, implement unary and streaming calls, and learn deadlines, status codes, interceptors and the rules for evolving fields without breaking clients. Design the proto contract · Generate the Go code · Implement the server · Implement the client: connections, deadlines and status codes · Interceptors: gRPC's middleware 13 min read
  3. 11 Building an API Gateway in Go: Routing, Authentication and Rate Limiting Build a small API gateway from scratch with Go's standard httputil.ReverseProxy, adding request IDs, API key and JWT checks and token-bucket rate limiting, then learn when an off-the-shelf gateway is the better choice. Routing with ReverseProxy · Adding a request ID to every request · Authentication: API keys and JWT · Rate limiting with a token bucket · Assembling the complete gateway 14 min read
  4. 12 Service Discovery and Load Balancing for Go Microservices When services run as many instances whose IPs keep changing, how does a caller find the healthy ones? This article compares client-side and server-side load balancing, builds a heartbeat-based registry and round-robin, least-connections and consistent-hashing balancers in Go, and explains DNS-based discovery in Kubernetes. Client-side or server-side load balancing · The registry and heartbeats · Active and passive health checks · Three load-balancing algorithms · Why consistent hashing reduces movement 14 min read

4. Reliability

  1. 13 Timeouts, Retries and Circuit Breakers Downstream services will be slow or fail. Starting from deadline budgets, this article builds retries with exponential backoff and jitter, retry budgets, a three-state circuit breaker in Go and bulkheads, so the order service survives misbehaving dependencies. Every call needs a deadline · Telling which errors are worth retrying · Exponential backoff plus jitter · Retry budgets to avoid retry amplification · The three states of a circuit breaker 17 min read
  2. 14 Idempotency and Distributed Locks Retries and at-least-once delivery make duplicate work the norm. This article uses idempotency keys, unique constraints and dedupe tables so duplicates take effect once, then dissects Redis locks, lease expiry and fencing tokens, and why locks alone cannot protect payments. First, tell which operations are naturally idempotent · Blocking duplicate business records with unique constraints · Idempotency keys and a request dedupe table · Running idempotency keys in Go · At-least-once delivery makes idempotency a necessity 15 min read
  3. 15 Message Queues and Event-Driven Design Replacing synchronous calls with events decouples services in time. This article compares work queues and pub/sub, covers Kafka, RabbitMQ and NATS concepts, then partitions and ordering, consumer groups, acks and redelivery, dead-letter queues, idempotent consumers and event schema versioning. Commands and events, queues and publish/subscribe · The core differences between Kafka, RabbitMQ and NATS · Partitions, ordering and consumer groups · Acknowledgement, redelivery and delivery semantics · Retries, dead-letter queues and idempotent consumers 15 min read
  4. 16 Distributed Transactions: Sagas and the Outbox Pattern Order, inventory and payment each own their database, so no single transaction spans them. This article explains why not two-phase commit, compares orchestrated and choreographed sagas with compensations, then uses a transactional outbox, a relay and an inbox to keep data and events consistent. Why not two-phase commit · Sagas and compensating actions · Orchestration and choreography · Implementing an orchestrated saga in Go · The dual write problem and the transactional outbox 16 min read

5. Going live and operating

  1. 17 Observability in Go: Logs, Metrics and Tracing Build observability for Go microservices step by step: structured logs with log/slog and request IDs, RED/USE metrics exposed to Prometheus, OpenTelemetry tracing with context propagation, and correlating all three through a shared trace ID. Structured logs with log/slog · Linking a request's logs with a request ID · Deciding what to measure: RED and USE · Exporting metrics with Prometheus · Basic concepts of distributed tracing 15 min read
  2. 18 Configuration and Graceful Shutdown in Go Load configuration the 12-factor way from environment variables, flags and files with validation and careful secret handling, then shut Go services down gracefully with signal.NotifyContext, http.Server.Shutdown, consumer draining and a unified lifecycle. The 12-factor configuration principles · Read into a struct and validate at startup · Handling secrets · Receiving the shutdown signal with signal.NotifyContext · Graceful shutdown for the HTTP server and the consumer 12 min read
  3. 19 Deploying One Go Service with Docker and Kubernetes Package a single Go service into a small, non-root distroless image with a multi-stage Dockerfile and a static binary, then run it on Kubernetes with a Deployment, Service, probes, resource limits, ConfigMap/Secret and safe rolling updates. A multi-stage Dockerfile and a static binary · Choosing a base image and running as non-root · Building, tagging and pushing the image · Injecting configuration with ConfigMaps and Secrets · Deployment, Service and probes 15 min read
  4. 20 Performance Tuning in Go: pprof and Benchmarks Measure before you optimise: write reliable benchmarks with testing.B and b.Loop, compare runs with benchstat, profile CPU, heap, goroutines and mutexes with pprof, understand escape analysis and allocations, then tune GOMAXPROCS, GOGC, GOMEMLIMIT and apply PGO. Writing benchmarks with testing.B · Compare with benchstat instead of reading one run · Finding CPU and memory hot spots with pprof · Sampling a running service: net/http/pprof · Escape analysis and memory allocation 16 min read

6. Deploying the system

  1. 21 Deploying a Whole Microservice System with Docker Compose Put the api-gateway, order, payment and inventory services together with PostgreSQL, NATS and Redis into one compose.yaml, covering network isolation, healthcheck-driven startup order, migrations as one-off jobs, secrets and config, and where Compose stops being enough. Sketch the whole system and the directory layout · One Dockerfile shared by four services · Write the infrastructure: database, message broker, cache · Add the four services and use networks to decide who can see whom · Configuration, secrets and env files 20 min read
  2. 22 Deploying a Microservice System on Kubernetes Move the api-gateway, order, payment and inventory services onto Kubernetes with a Deployment and Service per service, Gateway API routing, NetworkPolicy, HPA and PDB, Kustomize overlays for dev and prod, and a release flow covering image tags, migrations, rollouts, rollback and debugging. Plan namespaces, labels and the directory structure · One Deployment and Service per service · Each service's own ConfigMap and Secret · Stateful dependencies — databases and message queues · The external entry point and NetworkPolicy 23 min read
  3. 23 From Monolith to Microservices: Evolving the Architecture at 100K, 1M and 10M Scale How the same online shop should evolve with scale: a modular monolith first, then horizontal scaling and caching, read replicas and the first extracted services, and finally sharding and multiple regions, with the signals that justify each step and a safe procedure for splitting a service out. Define “scale” clearly · Getting started (10K) — a modular monolith is enough · 100K — horizontal scaling and caching, still a monolith · 1M — read/write splitting, message queues and the first extracted services · 10M — sharding, read models and multiple regions 36 min read
  4. 24 Adding Indexes Safely: Indexing Large Tables Without an Outage Adding an index to a large table that is taking orders can block writes and take the whole service down if one step is wrong. This article starts from how indexes work and the evidence in EXPLAIN, designs the right index, and ships it safely with CONCURRENTLY, lock_timeout and a retrying Go migration runner. How indexes work, just enough to decide · Finding the right index from evidence · Designing the index correctly · Adding an index to a large live table without an incident · A safe migration runner in Go 38 min read
  5. 25 Hot and Cold Data, Sharding and Splitting Databases: What to Do When the Data Grows When the data outgrows one database, measure first, use the cheap fixes in order, and only then split. This article covers hot and cold data, time partitioning and archiving, vertical splits, shard keys and routing, IDs with embedded shard bits, cross-shard queries, zero-downtime migration and operations. Diagnose before you decide to split · Hot and cold data — move the rarely used data out of the way first · Vertical splits — by business domain, or by column · Horizontal sharding — shard keys, routing and globally unique IDs · What breaks after sharding 42 min read

7. Pitfalls in practice

  1. 26 Concurrency Pitfalls: From Data Races to Overselling Ten concurrency problems that show up when a Go microservice system meets real traffic, from data races, goroutine leaks and deadlocks to lost updates, overselling, hot rows, cache stampedes and duplicate messages, each with symptoms, causes, detection and fixes. Problem 1: Data races · Problem 2: Concurrent map writes kill the program · Problem 3: Loop variables captured by closures · Problem 4: Goroutine leaks · Problem 5: Deadlocks and lock ordering 27 min read
  2. 27 Payment Pitfalls: Double Charges, Callbacks and Reconciliation The hardest part of payments is not failure but not knowing whether a charge succeeded. Ten common pitfalls, from double charges, state machines and timeouts to webhook verification and ordering, cancellations, amounts, refunds, reconciliation, ledgers and sensitive data, with a checklist. Problem 1: Double charges · Problem 2: States jump around and a success is overwritten by a failure · Problem 3: Treating a timeout as a failure · Problem 4: Webhooks that are forged, resent, out of order, or arrive before the synchronous response · Problem 5: A webhook and a user cancellation happen at the same time 21 min read
  3. 28 Preventing Duplicate Payments and Handling Payment Incidents: From the Button to the Provider, and How to Stop the Bleeding Duplicate payment orders can enter at any layer, from the button and client to the gateway, services, provider and webhooks; this article shows how each layer stops them. It then covers preventing, alerting on and responding to payment incidents, with Go code for query-before-retry and a stuck-payment sweeper. Part 1: Where duplicates come from · Layer 1: The pay button · Layer 2: The client (web and app) · Layer 3: Gateways, load balancers and retries between services · Layer 4: The order service, one checkout makes one order 29 min read
  4. 29 Reconciliation: Matching Payment Provider Statements Reliably Two systems recording the same money will always drift apart, and reconciliation is how you find every difference, every day. This article covers fetching and keeping statements, parsing and day cut-offs, line-by-line matching, classifying and handling differences, tying the ledger to payouts, and alerts and month-end close, with a tested Go reconciler. what reconciliation is and isn't · fetching statements reliably · matching line by line · classifying differences · handling differences 28 min read
  5. 30 Handling Money in Go: Minor Units, Decimals, Currencies, Rounding and Allocation Why money must never be a float64, and how to model it in Go as int64 minor units plus a currency: differing decimal places, JSON, rounding for tax and FX rates, allocation that never loses a cent, database columns and tests. See exactly what goes wrong with float64 · Represent money as an int64 in minor units · Currency decimal places and ISO 4217 · Parse and output safely: user input and JSON · Applying tax rates, discounts and exchange rates: exact computation with math/big and explicit rounding 26 min read

8. Security and working with AI

  1. 31 Microservice Security: Authentication, Authorisation, Secrets and Supply Chain Starting from a threat model of the shop system: validate JWTs at the gateway and propagate identity, enforce object-level authorisation in every service to stop BOLA, use mTLS between services, keep secrets out of code and logs, and guard the supply chain with govulncheck, SBOMs and image signing. Draw the threat model first, then decide what to defend against · Centralise authentication at the gateway: validate every field of the JWT · Pass the identity to the backend, in a way that can't be forged · Authorise in every service: stop BOLA · Use mTLS between services to confirm identity, and enforce least privilege 24 min read
  2. 32 Building Go Microservices with Claude Code: Rules, Permissions and Security Review Bring Claude Code into the shop system: project rules in CLAUDE.md, allow/deny permissions in settings.json, hooks that run gofmt and block protected paths, subagents, skills, plan mode and a test-first loop, plus prompt injection risks and who reviews what. Understand how it works first — the agent loop and the layers of control · Write a CLAUDE.md — the project's working instructions · Permission rules — explicitly what is allowed and what is forbidden · Use hooks to turn rules into checks that run automatically · Subagents and skills — pinning down specialised work and repeated workflows 19 min read
  3. 33 Bringing AI Workflows into the Team Process: PR Review, CI and Human Gates Fit AI agents into a team's development lifecycle from ticket to pull request: what AI may do and what only humans or automated gates decide, with CI checks, branch protection, least-privilege tokens and versioned prompts, and how to measure the effect honestly. First map where AI sits in the development lifecycle · Tickets and planning — write requirements so both AI and people can verify them · Required CI gates — AI output must pass the same checks as code people write · Add AI review to CI — suggestions only, no power to decide · Human gates — branch protection, CODEOWNERS and "whoever merges is responsible" 17 min read
  4. 34 Automating Deployments and Troubleshooting with AI Workflows Turn the shop system's deployment into a pipeline of build, scan, render, diff, policy and approval gates where AI summarises releases, flags risky manifest changes and drafts rollout plans, then use a read-only agent to gather incident evidence while rules and humans decide on promotion and rollback. Draw the deployment pipeline clearly, with every step able to block · What AI can do before deployment: release summaries and manifest risks · Check database migrations: expand, migrate, contract · Progressive delivery: canary and blue-green, decided by metrics and rules · Something has broken: gather evidence with a read-only agent 29 min read
  5. 35 Debugging a Project with AI: From Reproduction to Fix A disciplined way to debug the shop system with an AI coding agent: describe the symptom precisely, reproduce it with a failing test, feed evidence instead of guesses, let git bisect run find the culprit commit, test one hypothesis at a time, fix the root cause, and prove the fix with tests, -race and repeated runs. Describe the symptom precisely: expected, actual, scope and frequency · Reproduce first: let the agent write a failing test, and confirm it fails for the right reason · Feed it evidence, not guesses · Let the agent find the culprit commit automatically with git bisect run · Test one hypothesis at a time, and have the agent read the whole path 28 min read
  6. 36 Security Checks with AI: Threat Modelling, Tracing Input and Verifying Findings Use AI to check a Go service for security problems without trusting it blindly: scope the work from a threat model, run deterministic tools such as govulncheck, gosec and gitleaks first and let AI triage them, have the agent trace untrusted input from source to sink, demand a path, a proof of concept and a test for every finding, and protect the review process itself. Set the scope from the threat model, not "find me some vulnerabilities" · Run deterministic tools first; AI only classifies · Let the agent trace untrusted input, from source to sink · A worked example: path traversal and BOLA in receipt download · Every finding needs evidence: a fixed format and severity rules 26 min read
  7. 37 Writing an MCP Server in Go: Connecting AI to OpenProject Build a four-tool MCP server in Go with the official SDK so Claude Code can read OpenProject work packages, post PR links and change status after you confirm, covering API v3, HAL and lockVersion, least privilege, prompt injection, auditing and team deployment. What MCP is: host, client and server · The OpenProject API v3: HAL, authentication, filters and optimistic locking · Design the tools: small, explicit and read-mostly · Write the OpenProject client with the standard library · Test against a fake OpenProject built with httptest 34 min read

9. RAG and tools

  1. 38 RAG Basics: Look It Up Before Answering, and Why That Matters Start from the three problems a model has when it answers on its own: it doesn’t know your data, its knowledge has a cutoff, and you can’t tell when it’s wrong. Then the two paths of RAG, its four core values, how it compares with long context, fine-tuning and plain search, and a minimal Go example that calls no API at all. Three problems with a model answering on its own · What RAG is: an open-book exam · The core value: why it’s worth doing · How to choose between the options · A minimal “look it up, then answer” in Go 9 min read
  2. 39 Where RAG Quality Comes From: Chunking, Embeddings, Vector Databases and Hybrid Search Split RAG into five stages and see how each one decides whether the answer is any good. Write heading-based chunking, cosine similarity and RRF fusion in Go, then cover how a vector database fits in and what to watch, metadata filters and the context budget. Five stages, each one loses points · Chunking: size, overlap and splitting by structure · Embeddings: turning text into vectors you can compare · Hybrid vector and keyword search, merged with RRF · Vector databases: how to choose, how they fit, what to watch 12 min read
  3. 40 Evaluating RAG, Hallucinations and Common Failures: How to Know It Answers Right Evaluate retrieval and answers separately with a question set: recall@k, MRR, faithfulness and refusals. Break hallucinations into four sources and block them layer by layer, from data, retrieval and prompt to checks in code and the interface. Then the most common failures and fixes, and monitoring and regression tests once it’s live. A wrong answer isn’t one kind of failure · A golden question set · Retrieval metrics: recall@k and MRR · Answer metrics: faithfulness, correctness and refusals · Where hallucinations come from, and how to block them layer by layer 10 min read
  4. 41 Building a RAG Pipeline in Go: Chunking, Vector Search and Tool Calling Build a cited question-answering pipeline over the shop’s runbooks, API docs and incident notes in Go. Chunk by headings, embed, combine pgvector with keyword search, let Claude call tools to search docs and read order status, then evaluate it and defend against prompt injection. What RAG is, and when you don’t need it · The corpus — the shop’s internal documents · Chunking — by heading, with a size limit and overlap · Embeddings — hidden behind an interface · An in-memory index first — cosine similarity and top-k 34 min read
  5. 42 Writing a Claude Code Skill That Cites Its Sources Wrap the previous article’s document search in an MCP server and write a Claude Code skill that backs every sentence with an exact quote and line range. A small Go verifier rejects uncited sentences and invented citations, and an evaluation set checks that the skill triggers, cites correctly and admits when no source exists. What a citation should look like · Wrap retrieval in an MCP server, `docs-search` · Write the `cite-docs` skill · The verifier, `cmd/verify-citations` · Connecting to Claude Code: `.mcp.json` and permissions 32 min read

Bonus

  1. 43 Bonus: SEO, AEO, GEO and AIO: Getting Found by Search Engines and AI What SEO, AEO, GEO and AIO actually mean and where they overlap, followed by concrete steps for a developer blog or API docs: crawlability and rendering, sitemaps, canonical URLs, JSON-LD, Core Web Vitals, question-shaped answers, llms.txt, robots.txt rules for AI crawlers, and measurement. Pin down the four terms · Understand where they overlap and where they differ · Crawlable and renderable · Sitemaps, canonical URLs and page metadata · Structured data with JSON-LD 20 min read