DEV Community: Kevin Nambubbi

Why RAG Pipelines Fail on East African Documents — and What I Built to Fix It

Kevin Nambubbi — Thu, 02 Jul 2026 09:58:46 +0000

I have been watching AI teams in Nairobi build retrieval systems on Kenyan regulatory and legal documents and hit the same invisible wall. They tune their prompts. They swap embedding models. They adjust retrieval parameters. The answers are still wrong.

The failure is not in the LLM. It is not in the vector store. It is happening one layer below all of that, before any of it runs.

It is in the chunking step.

The problem with generic chunking

Every mainstream RAG framework — LangChain, LlamaIndex, Amazon Bedrock Knowledge Bases — chunks documents the same way: fixed character counts or sentence boundaries. This works reasonably well for English-language enterprise documents. It fails on East African regulatory and legal documents in ways that are hard to debug because the failure is invisible.

Here is a concrete example. Take a CBK (Central Bank of Kenya) circular. Its structure looks like this:

1. Purpose
   This circular provides guidelines on...

2. Scope
   This circular applies to all institutions...

3. Customer Data Protection Requirements
   3.1 All DCPs must implement end-to-end encryption...
   3.2 Customer data must be stored within Kenya...
   3.3 DCPs must appoint a dedicated Data Protection Officer...

A generic chunker splitting at 500 characters will cut somewhere inside section 3. The chunk boundary lands mid-requirement. The embedding model encodes an incomplete regulatory instruction. When a compliance team queries "what are the data protection requirements for DCPs", the retrieval system returns a fragment — missing the subsections that define the actual obligations.

The LLM fills in the gap with its training data. The answer looks confident and is wrong.

The same failure mode hits every East African document type:

SACCO loan policies — penalty clauses separated from the grace period conditions they govern. A chunk containing "a penalty of 2% per month will be charged" with no surrounding context about when the grace period ends is not a useful retrieval unit.

Kenyan court judgments — the FINDINGS section separated from the ORDER that follows from them. A RAG system that retrieves the order without the findings cannot explain why the court ruled that way.

Kenyan legislation — the CBK Act (Cap. 491) has been amended repeatedly. It contains alphanumeric section numbers: 33N, 33O, 33U, 51B. A generic chunker treating these as arbitrary text has no way to know that 33U. is a section boundary and (1) is a subsection that should stay inside its parent chunk.

The root cause

Generic chunkers do not know what kind of document they are reading. They apply the same strategy to a CBK circular, a SACCO policy, a Kenyan Act, and a Silicon Valley terms-of-service document. Structure that is obvious to any lawyer or compliance officer — numbered sections, ALL-CAPS headings, legislative part headers — is invisible to a chunker that only sees character counts.

The fix is obvious once you see it: detect the document type first, then apply the correct structural cutting grammar for that type.

Building Hekima

I built Hekima to solve this. The name means "wisdom" in Swahili.

The architecture is simple:

Input: document (.txt or .pdf)
          ↓
[ Document Type Detector ]
          ↓
[ Structure-Aware Chunker ]
          ↓
Output: JSON chunks with section labels, token counts, metadata

Detection

Detection is deterministic and stateless. No ML model. Each document type has a set of lexical fingerprints — phrases that appear in that type and not in others.

signatures := map[models.DocumentType][]string{
    models.TypeLegislation: {
        "Laws of Kenya",
        "An Act of Parliament",
        "Cap.",
        "Short title",
        "Interpretation",
        "PRELIMINARY",
    },
    models.TypeCBKCircular: {
        "Central Bank of Kenya",
        "Governor",
        "Ref. No. CBK",
        "pursuant to",
        "Banking Act",
        "all institutions",
    },
    // ...
}

The detector scores each type by counting phrase matches. Minimum score of 2 required — prevents single accidental matches from mislabeling. Ties return TypeUnknown. The same document always produces the same result.

One subtlety worth noting: CBK circulars and Kenyan legislation share vocabulary. A CBK circular cites "Central Bank of Kenya" and "Banking Act" because it is issued under those authorities. The CBK Act itself also contains those phrases. The disambiguation comes from score gap — legislation uniquely contains "Laws of Kenya", "An Act of Parliament", "Cap.", "Short title", "Interpretation", and "PRELIMINARY". A real Act scores 5-6 on TypeLegislation and 1-2 on TypeCBKCircular. A circular scores 4-5 on TypeCBKCircular and 0-1 on TypeLegislation. The gap is decisive.

Chunking strategies

Each document type has its own splitting strategy:

CBK Circulars — splitByNumberedSections

Splits at top-level integer sections only. isNumberedSection() uses rune iteration (not byte indexing) for unicode safety, and explicitly rejects subsections:

// "3. Requirements" → new chunk boundary
// "3.1 Specific requirement" → stays inside section 3's chunk
func isNumberedSection(line string) bool {
    runes := []rune(line)
    i := 0
    // must start with digits
    for i < len(runes) && unicode.IsDigit(runes[i]) { i++ }
    // must be followed by dot
    if i >= len(runes) || runes[i] != '.' { return false }
    i++
    // must NOT be followed by another digit (that would be a subsection)
    if i >= len(runes) || unicode.IsDigit(runes[i]) { return false }
    return len(strings.TrimSpace(string(runes[i:]))) > 1
}

Kenyan Legislation — splitLegislation

This was the most interesting to build. The CBK Act (Cap. 491) PDF, extracted via pdftotext -layout, contains:

A Table of Contents with the same Part and Section patterns as the body — but every TOC entry has dot-leaders ("1. Short title ............... 1"). Detection: strings.Contains(line, "...")
Part headers with Roman numerals and sub-part suffixes introduced by amendment: Part VIA, Part VIB, Part VIC, Part VID.
Section numbers with uppercase letter suffixes: 33N, 33O, 33U, 51B.
Repealed sections that match the section header regex but contain only a bracketed repeal notice below minChunkLength — correctly producing no chunk.

The regex that handles all of this:

// Handles: "1.", "4A.", "33U.", "51B."
var sectionHeader = regexp.MustCompile(`^(\d+[A-Z]*)\.\s+\S`)

// Handles: "Part I", "Part VIA", "Part VIB"
var partHeader = regexp.MustCompile(
    `(?i)^Part\s+[IVXLCDM]+(A|B|C|D)?\s+[–-]\s+\S`,
)

Part identity is preserved in Metadata["part"] on every section chunk beneath it, so a RAG pipeline can filter or boost by Part without needing a dedicated Part-only chunk.

The chunk output

Every chunk carries:

{
  "id": 3,
  "text": "3.1 All DCPs must implement end-to-end encryption...\n3.2 Customer data must be stored within Kenya...",
  "section": "3. Customer Data Protection Requirements",
  "doc_type": "cbk_circular",
  "filename": "cbk_circular.pdf",
  "token_count": 89,
  "metadata": {}
}

token_count uses a word count × 1.3 heuristic (approximates BPE token counts for English and Swahili prose). Use it to enforce context window limits when batching chunks for an embedding model.

overlap_words is available via the API — repeats the last N words of each chunk at the start of the next. Applied as a single post-processing pass after splitting, written once and shared across all document types. Recommended for dense regulatory prose: 15–25 words.

The HTTP API

Hekima runs as an HTTP server. Integration into any RAG pipeline is one call:

curl -X POST https://hekima-production.up.railway.app/chunk \
  -F "file=@cbk_circular.pdf" \
  -F "overlap_words=20"

Response is a JSON array of chunks, ready to feed to any embedding model — Titan Embeddings, OpenAI Embeddings, Cohere Embed, whatever you are using.

The server runs behind a per-IP rate limiter (10 requests/minute, burst of 5) with structured request logging. The Docker image is 19MB — multi-stage build, non-root user, poppler-utils included for PDF extraction.

Technical choices worth explaining

Why Go?

Single binary. No runtime. No dependency hell. The Docker image is 19MB including PDF extraction. A Python equivalent with FastAPI and dependencies would be 300MB+ just to start. For infrastructure that needs to run reliably in constrained East African deployment environments, that matters.

Outside stdlib, Hekima has one dependency: golang.org/x/time/rate for the token bucket rate limiter. Everything else — HTTP server, JSON, multipart parsing, file I/O — is stdlib.

Why pdftotext and not a Go PDF library?

pdftotext -layout preserves the spatial layout of the document, which is critical for section detection. The -layout flag reconstructs the visual column structure from the PDF's character position data. A pure Go PDF parser that extracts raw text loses this layout information, and section headers become indistinguishable from body text.

The tradeoff: poppler-utils must be installed as a system dependency. The Dockerfile handles this. For CLI users it is one apt install command.

Why deterministic detection and not an ML classifier?

East African regulatory documents have stable structural conventions that have not changed significantly in decades. "Ref. No. CBK" appears on every CBK circular. "Laws of Kenya" appears on every revised statute. "REPUBLIC OF KENYA" appears in every court judgment header. These are not probabilistic signals — they are definitive identifiers.

A trained classifier would require a labeled dataset, introduce a dependency on a model file, add latency, and produce probabilistic outputs that need a confidence threshold. The lexical fingerprint approach is faster, requires no training data, produces deterministic results, and is trivially explainable. For this use case it is the right choice.

What is next

The engine covers the five highest-value East African document types. The pattern for adding new types is established and documented in CONTRIBUTING.md — if you work with NTSA forms, KRA notices, or county government circulars and have real document samples, contributions are welcome.

The live demo is at https://hekima-production.up.railway.app — upload any supported document type and see the chunks.

The repo is at https://github.com/the-veez/hekima — open source, MIT licensed, CI green.

If you are building RAG systems on East African documents and this solves a problem you have been fighting, I would like to hear about it.

Built in Nairobi. Solving African problems with African context.

AI Isn't Replacing Developers. It's Exposing Them.

Kevin Nambubbi — Fri, 26 Jun 2026 13:46:00 +0000

"The more AI writes your code, the more your understanding becomes your competitive advantage."

Introduction

When I came across the meme comparing AI-assisted coding to human evolution, I couldn't help but laugh.

The first image shows a developer confidently walking alongside AI, looking like they've reached the next stage of evolution.

The second image tells a different story.

After thirty minutes of debugging, the AI is having a sophisticated discussion while the developer stands there looking like a confused caveman.

It's funny because it's painfully relatable.

Almost every developer using AI has experienced both sides of this meme.

The Illusion of Instant Expertise

Modern AI tools are remarkable.

Need an authentication system?

AI can generate one.

Need a REST API?

Done.

Need unit tests?

Done.

Need Docker configuration?

Done.

Within minutes you've built features that once required hours of research and implementation.

This creates a dangerous illusion.

It feels like you're becoming a significantly better developer simply because you're producing more code.

But writing code has never been the difficult part of software engineering.

Thinking is.

Production Doesn't Care Who Wrote the Code

Everything works perfectly until it reaches production.

Then reality begins.

A customer reports a bug.

Performance suddenly degrades.

Memory consumption increases.

Logs become impossible to understand.

Eventually someone asks the question every engineer fears:

"Why was this implemented this way?"

At that moment, AI cannot answer for you.

You become responsible for every line that was merged into production.

Whether you wrote it yourself or copied it from an AI assistant doesn't matter.

Responsibility always belongs to the engineer.

AI Makes Understanding More Valuable

There's a common fear that AI will replace software developers.

I don't think that's what's happening.

Instead, AI is exposing the difference between developers who understand software and developers who merely produce it.

When AI generates code instantly, typing speed is no longer a competitive advantage.

Understanding becomes the advantage.

The developers who will succeed are those who can:

Evaluate AI-generated solutions.
Identify hidden bugs.
Understand architectural trade-offs.
Recognize security risks.
Explain design decisions.
Debug systems when they fail.

Those skills cannot be copied and pasted.

My Rule for Using AI

I rely on AI every day.

It's become an essential part of my workflow.

But before I accept any generated code, I ask myself five questions.

1. Why does this solution work?

If I can't explain the underlying logic, I probably shouldn't merge it.

2. What problem is this actually solving?

Sometimes AI solves a different problem than the one I intended.

Understanding the objective matters more than the implementation.

3. What are the trade-offs?

Every solution has compromises.

Better performance may reduce readability.

Simpler code may sacrifice flexibility.

Knowing those trade-offs is what separates engineering from code generation.

4. Could I debug this in production?

If the answer is no, I haven't learned enough yet.

5. Could I explain it to another developer?

Teaching is one of the best tests of understanding.

If I can't explain it, I probably don't understand it.

The Most Dangerous Technical Debt

Technical debt isn't limited to messy codebases.

AI introduces another form of debt:

Mental technical debt.

Imagine AI writes 100 lines of code.

If you understand every line, you've gained knowledge.

If you understand only ten, you've borrowed ninety lines of understanding that you'll eventually have to repay.

Usually during a production incident.

That's the worst possible time to discover you don't understand your own system.

AI Should Be Your Junior Developer

The healthiest way I've found to think about AI is this:

Treat AI as your most productive junior developer.

It can generate ideas.

It can draft implementations.

It can automate repetitive work.

It can explain unfamiliar concepts.

But you remain the senior engineer responsible for reviewing, improving, and approving every decision.

That's where real growth happens.

Final Thoughts

AI has fundamentally changed software development.

It has made us faster.

More productive.

More efficient.

But speed without understanding is fragile.

The developers who will build lasting careers won't simply be those who generate the most code.

They'll be the ones who combine AI-assisted productivity with deep engineering knowledge and sound judgment.

AI isn't replacing developers.

It's revealing who truly understands the systems they're building.

And in the long run, understanding will always outperform dependency.

Discussion

How has AI changed your development workflow?

Have you adopted any habits that ensure you're still learning instead of becoming dependent on AI?

I'd love to hear your perspective in the comments.

Why Developers Shouldn't Blindly Trust AI-Generated Code: Lessons From a Real Project

Kevin Nambubbi — Tue, 09 Jun 2026 01:06:42 +0000

Artificial intelligence has become a permanent part of modern software development.

Tools like ChatGPT, GitHub Copilot, Claude, Cursor, and others can generate code in seconds that would otherwise take minutes or hours to write manually.

But after recently completing a JavaScript project, I learned an important lesson:

AI-generated code is not the same thing as production-ready code.

The Project

The assignment involved building a superhero directory application using data from a public API.

The application required:

Data fetching
Table rendering
Pagination
Live search
Column sorting
Modal detail views
URL state persistence
Performance considerations

At first glance, this seems like the perfect use case for AI assistance.

So I started relying heavily on AI-generated solutions.

The Trap

Every time I encountered a bug, I requested a complete replacement for the affected code.

Examples included:

Pagination issues
Search behavior
Sorting problems
Modal bugs
Missing table data

The AI frequently provided code that looked correct.

Sometimes it even sounded confident.

Unfortunately, confidence is not correctness.

Several generated solutions introduced new problems while attempting to solve existing ones.

Examples included:

1. HTML and JavaScript Mismatches

The table rendering function produced fifteen columns of data while the HTML contained only eight table headers.

The result:

Misaligned data
Broken sorting
Confusing UI behavior

The code technically executed, but the application was incorrect.

2. Incorrect Numerical Sorting

Strings like:

78 kg
100 kg

were being compared alphabetically rather than numerically.

This caused:

100 kg

to appear before

78 kg

because string comparison evaluates "1" before "7".

The correct solution required extracting numeric values before sorting.

3. Regressions

A common pattern emerged:

Bug identified.
AI generated fix.
Original bug disappeared.
Two new bugs appeared.

This created a cycle where progress felt constant but actual completion remained distant.

What Finally Worked

Instead of asking for another complete rewrite, I began auditing the application manually.

I checked:

DOM structure
Event listeners
Render functions
Data mappings
Sort implementations
API response structure

Within a short period, I found several root causes that had been hidden beneath layers of generated code.

The lesson was simple:

Understanding the system is faster than repeatedly replacing the system.

Where AI Excels

Despite the challenges, AI was still useful.

It helped with:

Boilerplate

Generating repetitive code quickly.

Documentation

Explaining APIs and concepts.

Brainstorming

Suggesting approaches I might not have considered.

Learning

Helping understand unfamiliar patterns.

Used correctly, AI significantly improved productivity.

Where AI Should Not Be Trusted Blindly

Production Logic

Always verify.

Architecture Decisions

Always review.

Security-Critical Code

Always inspect manually.

Performance Optimization

Always benchmark.

Bug Fixes

Always reproduce and validate.

Practical Advice

If you use AI in development:

Treat AI like a junior developer

Review everything.

Read generated code line by line

If you cannot explain it, do not ship it.

Keep requirements visible

Many AI mistakes come from drifting away from the original specification.

Test continuously

Never assume generated code works because it looks reasonable.

Debug before regenerating

Understanding the bug is often faster than generating another solution.

Final Thoughts

AI is transforming software development.

But there is a difference between:

"AI helped me write code"

and

"AI built my application."

One is a productivity multiplier.

The other is a gamble.

The strongest developers will not be those who reject AI.

They will be those who understand when to trust it, when to challenge it, and when to ignore it completely.

AI can write code.

Engineers are still responsible for making sure that code is correct.

From Syntax to Systems

Kevin Nambubbi — Thu, 04 Jun 2026 12:07:48 +0000

From Learning Syntax to Building Systems

When I started programming, I believed that mastering syntax was the main challenge.

If I could understand variables, loops, functions, structs, and conditionals, then surely I'd be ready to build software.

Recently, while working on a social network project, I discovered something important:

Knowing syntax and building systems are two completely different skills.

The Alphabet Analogy

Imagine a child who can confidently recite:

A, B, C, D, E, F, G...

That's impressive.

The child knows the alphabet.

But now ask the same child to write a report, tell a story, or explain a scientific concept.

Suddenly, knowing the alphabet is no longer enough.

The challenge has shifted from recognizing letters to organizing ideas.

Programming feels the same way.

I know Go syntax.

I can define structs.

I can write functions.

I can use loops and conditionals.

But when I was asked to help build a social network, I found myself facing questions that syntax couldn't answer.

The Numbers Analogy

Another comparison helped me understand the problem.

Imagine someone who knows numbers:

1, 2, 3, 4, 5...

They can recognize them perfectly.

But that doesn't automatically mean they can solve algebra, calculus, or complex mathematical problems.

The symbols are only tools.

The real challenge is knowing how to use them.

Programming syntax works the same way.

What Building Systems Actually Looks Like

For example, I was assigned responsibility for features such as:

Followers
Posts
Comments
Feed
Notifications

At first, I thought:

"Which Go syntax should I use?"

But experienced developers approach the problem differently.

They ask:

What data exists?
What relationships exist?
What questions must the system answer?
What business rules must be enforced?

For a simple follow request, the thought process becomes:

Does the sender exist?
Does the receiver exist?
Is the sender trying to follow themselves?
Is there already a pending request?
Are they already following the user?

Only after answering those questions does the code become relevant.

The Biggest Lesson So Far

The biggest lesson I've learned is that software engineering is not primarily about code.

It's about modeling real-world behavior.

The code is simply the implementation of that model.

Today I'm learning to move from:

"I know the syntax."

"I understand the system."

And I think that transition is where real software engineering begins.

How Zone01 Kisumu "Build from Scratch" Approach Transformed Me from a Framework User to a Problem Solver

Kevin Nambubbi — Sun, 31 May 2026 06:24:40 +0000

The Moment I Realized I Didn't Really Know JavaScript
I was 2 months into learning JavaScript. I could use .map(), .filter(), .reduce() like any bootcamp grad. I felt confident.

Then my instructor asked me one question:

"How does .reverse() actually work?"

I froze.

I had used it hundreds of times. But I had no idea what was happening inside. I was a user, not a builder.

That was the day everything changed.

The 01EDU Difference: Build Tools, Not Just Use Them
Most coding courses teach you to use built-in methods. 01EDU does something different.

They disable the built-in methods.

Then they say: "Now build it yourself."

No .split(). No .join(). No .indexOf(). No .slice().

Just you, a text editor, and your brain.

What I Built in 2 Weeks (Without Using Built-ins)
Here are the JavaScript methods I re-created from scratch:

Method What I Learned
abs() Math is logic, not magic
multiply(), divide(), modulo() Arithmetic is repeated addition/subtraction
indexOf(), lastIndexOf(), includes() Searching is just looping and comparing
slice() Negative indexes count from the end
reverse() Arrays and strings are both indexed collections
join() Building strings step by step
split() Parsing is character-by-character inspection
round(), floor(), ceil(), trunc() Decimals are just numbers between whole numbers
Each function took hours of thinking, failing, debugging, and finally — understanding.

The Most Painful Lesson: Loops
The first time I tried to build repeat() without using .repeat(), I wrote an infinite loop.

My computer froze. I had to force restart.

That failure taught me more than any working code ever could. I learned to trace each iteration mentally. I learned to check my exit conditions. I learned to respect the loop.

You don't truly understand loops until you've crashed your computer with one.

What 01EDU Taught Me That No Bootcamp Could

I learned how computers think, not just how to write code

When you build .split() from scratch, you understand string parsing at a deep level. You know that every character is checked, one by one. You know that separators are just conditional triggers.

I stopped fearing errors

Error messages became my teachers. Each "undefined" or "not a function" showed me exactly where my mental model was wrong. I learned to read the stack trace before asking for help.

I can now learn any language faster

When I look at Python or Go, I don't see strange syntax. I see loops, conditions, and variables — the same building blocks I already mastered.

I interview differently

When an interviewer asks "How does array.map() work?", I don't just describe its behavior. I explain the loop, the callback, the new array creation, and the return. I've actually built it.

The Hard Truth: Shortcuts Create Ceilings
Using built-in methods is like using a calculator. It's fast. It's efficient. But if you never learn long division, you'll never truly understand numbers.

The same applies to code.

If you only use .sort(), you won't understand sorting algorithms

If you only use .split(), you won't understand string parsing

If you only use Math.round(), you won't understand floating-point math

Built-in methods are not the enemy. But they should be earned, not given.

How You Can Do This Too (Without Enrolling in 01EDU)
You don't need a special school to learn this way.

Try this challenge:

For one week, pretend these methods don't exist:

.map(), .filter(), .reduce()

.split(), .join()

.indexOf(), .includes()

Math.round(), Math.floor(), Math.ceil()

.slice(), .reverse()

Build your own versions. Use only loops, conditionals, and basic math.

You will struggle. You will feel slow. But after one week, you will understand JavaScript better than most developers with years of experience.

What's Next for Me
I am now building:

My own map() and filter()

A deep understanding of recursion by building tree traversal

A basic promise implementation to understand async JavaScript

Each one is harder than the last. But that's the point.

The goal is not to finish. The goal is to understand.

Why I’m Learning Go and JavaScript Together Instead of Separately

Kevin Nambubbi — Fri, 29 May 2026 20:10:27 +0000

Most programming tutorials teach technologies in isolation.

You learn a language.
Then a framework.
Then a database.
Then eventually build a small CRUD project.

But real systems are not built in isolation.

Modern applications are combinations of specialized services, each optimized for a particular responsibility.

That realization changed how I approached learning software engineering.

My Background

I recently completed an intensive introduction to Go and I’m currently transitioning into JavaScript and Node.js.

One thing became obvious almost immediately:

JavaScript and Go overlap in interesting ways on the backend.

At first, this confused me.

Why would a system use both?
Why not choose one language and use it everywhere?

The deeper I looked into production systems, the more the answer made sense.

Different Strengths, Different Responsibilities

Go excels at:

concurrency
resource efficiency
scalable backend services
systems programming
infrastructure tooling

JavaScript (through Node.js) excels at:

rapid API development
realtime systems
event-driven architecture
frontend/backend integration
ecosystem flexibility

These strengths are complementary rather than competitive.

A realistic production architecture might look like this:

Frontend (React)
        ↓
Node.js API Gateway
        ↓
Go Processing Service
        ↓
PostgreSQL

The Node.js layer handles:

authentication
REST APIs
realtime websocket communication
frontend coordination

The Go service handles:

concurrent processing
analytics
alert generation
heavy background workloads

This separation reflects how many modern distributed systems are designed.

Building Something Production-Minded

Instead of building tutorial projects, I decided to start building a system called “Sentra.”

Sentra is an incident reporting and monitoring platform designed to simulate real operational systems.

The platform will include:

authentication
incident management
realtime alerts
concurrent event processing
audit logging
service-to-service communication

The objective is not simply to “finish an app.”

The objective is to learn:

architectural boundaries
production thinking
operational reliability
security-first engineering

Security From Day One

One principle I strongly believe in:

“Security is not a feature but the fundamental of systems.”

Many beginner tutorials postpone security until later.
That creates dangerous engineering habits.

Even at the earliest stages, systems should account for:

input validation
password hashing
environment variable protection
rate limiting
secure headers
least privilege principles
proper logging practices

A system that works but is insecure is incomplete.

What I’m Focusing On

As I continue building Sentra, I’ll be focusing heavily on:

backend architecture
Go concurrency patterns
Node.js middleware design
PostgreSQL data modeling
Dockerized environments
observability and monitoring
clean repository practices

I’m less interested in “toy apps” and more interested in understanding how production systems evolve from simple foundations into scalable services.

The goal is to think like a systems engineer early, even while still learning.

Final Thought

Learning syntax is important.

But learning how systems communicate, fail, recover, scale, and remain secure is where software engineering becomes truly interesting.

That’s the direction I’m pursuing now.

The Golang Trinity: Functions, Methods, Interfaces

Kevin Nambubbi — Thu, 28 May 2026 01:32:09 +0000

Function: Does something with inputs
Method Does something attached to a type
Interface Says what methods a type must have

A method is a function with a receiver.
An interface is a set of method signatures.
If a type has those methods → it satisfies the interface. Automatically.

No implements. No inheritance. Just behavior.

// Function
func Add(a, b int) int { return a + b }

type Counter struct{ val int }

// Method (receiver is the "attachment")
func (c Counter) Add(n int) int { return c.val + n }

Function vs. Method // Function func Add(a, b int) int { return a + b }

type Counter struct{ val int }

// Method (receiver is the "attachment")
func (c Counter) Add(n int) int { return c.val + n }
Same logic. Different style.
Use functions for stateless operations.
Use methods when behavior belongs to a type.

The Interface Glue

type Stringer interface {
String() string
}

type User struct{ Name string }

// User now implements Stringer automatically
func (u User) String() string { return u.Name }

func Print(s Stringer) { fmt.Println(s.String()) }

func main() {
Print(User{Name: "Alice"}) // Works!
}
Key: The function Print doesn't care about User. It cares about the String() method.

The Twist: Functions Can Be Interfaces This is the pattern that confuses people.

// An interface
type Handler interface {
Handle(string)
}

// A function type
type HandlerFunc func(string)

// The trick: attach the Handle method to the function type
func (f HandlerFunc) Handle(s string) {
f(s) // calls itself
}

// Now any function with signature func(string) works as a Handler
func Log(s string) { fmt.Println("LOG:", s) }

func main() {
var h Handler = HandlerFunc(Log)
h.Handle("test") // LOG: test
}
Why is this useful?
It lets you use simple functions where interfaces are expected.
The standard http.HandlerFunc works exactly like this.

Putting It All Together go type Greeter interface { Greet() string }

type Person struct{ Name string }
func (p Person) Greet() string { return "Hi, " + p.Name }

type GreetFunc func() string
func (gf GreetFunc) Greet() string { return gf() }

func Party(g Greeter) { fmt.Println(g.Greet()) }

func main() {
Party(Person{Name: "Bob"}) // Method
Party(GreetFunc(func() string { // Function as interface
return "Surprise!"
}))
}
The Golden Rule
Accept interfaces, return structs.

Functions orchestrate.

Methods define behavior on types.

Interfaces abstract the what from the how.

Your Turn
What's your favorite small interface from the standard library?
io.Reader? fmt.Stringer? http.Handler?

Drop it below 👇

Audit Logs: The Silent Guardian of Every Serious System

Kevin Nambubbi — Sat, 23 May 2026 01:54:21 +0000

You build the feature. You test it. It works.

Three months later: data is missing, a transaction failed, a user denies doing something your system says they did.

Where do you look?

The audit log. And if you don't have one, you're blind.

What is an audit log?

A chronological, tamper-evident record of every significant action: who did what, when, and what changed.

Junior developers think audit logs are a compliance checkbox.

That thinking is backwards.

Audit logs aren't for regulators. They're infrastructure for trust. They answer the hardest question any system faces: "What actually happened?"

8 non-negotiables every developer must know:

An audit log is NOT a regular log. Never mix them.

Every entry must answer: Who? Did what? To what? When? From where? Result?

Timestamps in UTC. Always. No exceptions.

Append-only. No UPDATE. No DELETE. Ever.

Use cryptographic hash chaining for tamper-evidence.

Never log passwords, tokens, or secrets.

Define your retention policy before you write the first record.

Treat audit logs as evidence — because someday they will be.

Audit logs feel unnecessary until they're the only thing standing between you and a disaster you cannot explain.

Build them seriously from the start.

Build them as an afterthought, and you will regret it.

📂 The Hidden Superpower of Go's io/fs: Why Your Code Deserves a Universal Remote Control

Kevin Nambubbi — Mon, 16 Mar 2026 18:46:46 +0000

🎬 The Moment Everything Clicked
Picture this: It's 2 AM. I'm debugging a Go program that processes text files. My tests keep failing because I forgot to delete a test file from the previous run. Again.

"You know what?" I muttered to my monitor, "There HAS to be a better way."

Turns out, there was. And it had been sitting in the standard library all along.

📖 The Tale of Two File Readers
Let me tell you a story about two developers: Alice and Bob.

Bob's Approach: The Direct Route
go
// Bob's code - seems simple enough
func ProcessFile(path string) error {
data, err := os.ReadFile(path)
if err != nil {
return err
}
// ... process data
return nil
}
Bob is happy. His code works. Life is good.

Until...

He needs to test: "Now I need to create real files for testing 😰"

He needs to read from an embedded file: "Wait, I can't use os.ReadFile for that 😱"

He needs to read from a ZIP: "Do I rewrite everything? 😭"

Alice's Approach: The Universal Remote
go
// Alice's code - works ANYWHERE
func ProcessFile(fsys fs.FS, path string) error {
data, err := fs.ReadFile(fsys, path)
if err != nil {
return err
}
// ... process data (same code!)
return nil
}
Alice's code is like a universal remote that works with any TV:

Real files? ProcessFile(os.DirFS("."), "input.txt")

Testing? ProcessFile(fstest.MapFS{...}, "input.txt")

Embedded? ProcessFile(embed.FS, "input.txt")

ZIP files? ProcessFile(zipFS, "input.txt")

SAME CODE. EVERY TIME.

🎮 Let's Play: Spot the Difference
I'm going to show you two code snippets. Your job? Spot which one will make your life easier in the long run.

Round 1: Reading a Config File
Option A (The Traditionalist):

go
func LoadConfig() (*Config, error) {
data, err := os.ReadFile("./config.json")
if err != nil {
return nil, fmt.Errorf("failed to read config: %w", err)
}
// parse config...
}
Option B (The Visionary):

go
func LoadConfig(fsys fs.FS) (*Config, error) {
data, err := fs.ReadFile(fsys, "config.json")
if err != nil {
return nil, fmt.Errorf("failed to read config: %w", err)
}
// parse config...
}
See the difference? Option B doesn't care WHERE the file comes from. It just needs A file system.

🧪 The Testing Revelation
This is where io/fs goes from "interesting" to "I CAN NEVER GO BACK".

Testing Bob's Code:
go
func TestBobProcessor(t *testing.T) {
// Step 1: Create a real file (messy)
os.WriteFile("test.txt", []byte("hello"), 0644)
defer os.Remove("test.txt") // Hope we don't forget!

// Step 2: Run the test
err := BobProcessor.ProcessFile("test.txt")

// Step 3: Clean up (if we remembered)

}
Problems:

🐢 Slow (actual disk I/O)

🧹 Need cleanup code

🔒 Permission issues

📁 Leftover files when tests crash

Testing Alice's Code:
go
func TestAliceProcessor(t *testing.T) {
// Step 1: Create a VIRTUAL file system (magic!)
mockFS := fstest.MapFS{
"test.txt": {Data: []byte("hello")},
}

// Step 2: Run the test (NO FILES CREATED!)
err := AliceProcessor.ProcessFile(mockFS, "test.txt")

// Step 3: That's it! Nothing to clean up!

}
Benefits:

⚡ Blazing fast (pure memory)

🧼 No cleanup needed

🔒 No permissions to worry about

🏃‍♂️ Tests can run in parallel safely

🎯 The "Aha!" Moment
Here's when I truly understood the power of io/fs:

go
// My text processor now works ANYWHERE
type TextProcessor struct {
fsys fs.FS // The file system to use
}

func NewTextProcessor(fsys fs.FS) *TextProcessor {
return &TextProcessor{fsys: fsys}
}

// In production: use real files
prod := NewTextProcessor(os.DirFS("./data"))

// In tests: use virtual files
test := NewTextProcessor(fstest.MapFS{
"input.txt": {Data: []byte("1E (hex)")},
})

// In CLI tool: let user specify
cli := NewTextProcessor(os.DirFS(userSpecifiedPath))

// In web server: read from embedded static files
web := NewTextProcessor(embeddedStaticFiles)

// In cloud: read from S3 (if you implement fs.FS for S3)
cloud := NewTextProcessor(s3fs.New("my-bucket"))
ONE PROCESSOR. INFINITE POSSIBILITIES.

🎨 The Architecture Diagram (ASCII Art Edition)
text
┌─────────────────────────────────────┐
│ YOUR APPLICATION CODE │
│ (Works with ANY fs.FS!) │
└─────────────┬───────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ fs.FS Interface │
│ "Give me files!" │
└─────────────┬───────────────────────┘
│
┌─────────┴─────────┐
│ │
▼ ▼
┌────────────┐ ┌────────────┐
│ os.DirFS │ │fstest.MapFS│
│ (Real Disk)│ │(In Memory) │
└────────────┘ └────────────┘
│ │
▼ ▼
┌────────────┐ ┌────────────┐
│ Files on │ │ Virtual │
│ your HD │ │ files for │
│ │ │ testing │
└────────────┘ └────────────┘

AND SO MUCH MORE!
     │
     ▼

┌────────────────────┐
│ embed.FS │
│ (Files in binary) │
├────────────────────┤
│ zip.Reader │
│ (ZIP archives) │
├────────────────────┤
│ Custom FS │
│ (Your imagination!)│
└────────────────────┘
💡 The "Wait, What?" Moments
Moment 1: "But I need to WRITE files!"
Yes, io/fs is READ-ONLY. And that's PERFECT:

go
// READ with fs.FS (flexible)
data, _ := fs.ReadFile(myFS, "input.txt")

// WRITE with os (still need this)
os.WriteFile("output.txt", data, 0644)
The separation is beautiful: reading is abstract, writing is concrete.

Moment 2: "What about paths on Windows?"
io/fs uses forward slashes (/) everywhere. ALWAYS. Even on Windows:

go
// DON'T do this (platform-specific)
path := filepath.Join("folder", "file.txt")

// DO this (works everywhere with fs.FS)
path := "folder/file.txt" // Always use /
Moment 3: "Can I use this in MY project?"
YES! And here's how to start:

go
// Step 1: Change your function signatures
// FROM:
func DoSomething(filename string)
// TO:
func DoSomething(fsys fs.FS, filename string)

// Step 2: Use fs.ReadFile instead of os.ReadFile
// Step 3: Pass in the right FS for each use case
🚀 The Challenge
I dare you to refactor ONE of your existing Go projects to use io/fs. Just one function. See how it feels.

Here's a starter template:

go
package main

import (
"io/fs"
"os"
"testing/fstest"
)

// Your refactored function
func MyFunction(fsys fs.FS, path string) (string, error) {
data, err := fs.ReadFile(fsys, path)
if err != nil {
return "", err
}
return string(data), nil
}

func main() {
// Real usage
result, _ := MyFunction(os.DirFS("."), "real.txt")

// Test usage (in real tests, not main!)
mockFS := fstest.MapFS{
    "test.txt": {Data: []byte("mock data")},
}
testResult, _ := MyFunction(mockFS, "test.txt")

}
Try it. You'll thank me later.

🎁 The Gift That Keeps Giving
Using io/fs is like:

🍕 Ordering pizza that can be delivered by ANY restaurant

🔌 Having a plug that works in ANY country

🎮 Playing games that work on ANY console

It's abstraction done RIGHT.

📢 Join the Revolution
The next time you write a function that reads files, ask yourself:

"Do I need the REAL file system, or do I need A file system?"

If the answer is "A file system" (and it almost always is), use fs.FS.

Your future self (and anyone who tests your code) will thank you.

💬 Let's Discuss!
Have you used io/fs in your projects?
What creative file systems have you implemented?
Any "aha!" moments with file abstraction?

Drop a comment below! 👇

P.S. - The next time you see os.ReadFile in your code, imagine it's 1999 and you're using a dial-up modem. fs.ReadFile is your fiber optic connection to the future. 🚀

GoLang #Programming #SoftwareEngineering #CleanCode #DeveloperTips #iofs #GoProgramming

The Surgical Precision of `strings.Cut`: Why You Should Stop Over-Splitting Your Go Code

Kevin Nambubbi — Sat, 21 Feb 2026 08:42:28 +0000

If you are building text-heavy applications—like the ASCII art generator I’ve been tinkering with—you eventually run into a classic Go dilemma: Convenience vs. Performance.

When we need to parse a string, our "Day 1" instinct is almost always to reach for strings.Split. It’s familiar, it’s friendly, and it’s in every tutorial. But if you’re only looking to divide a string into two parts (like a Key:Value pair or a Header:Body), strings.Split isn't just overkill—it’s a resource hog.

Since Go 1.18, there has been a better way: strings.Cut. Let’s look at why this "scalpel" is superior to the "axe" that is Split.

🕵️ The Hidden Cost of `strings.Split`

To understand why Split is heavy, we have to look under the hood at its return type: []string.

When you execute strings.Split(input, ":"), the Go runtime isn't just finding a character; it’s going on a shopping spree with your RAM:

The Full Scan: It traverses the entire string to find every possible match.
The Allocation: It creates a brand-new slice to hold the results.
The Overhead: It generates new string headers for every single segment discovered.

If you’re processing a 5MB ASCII art file just to find the "Title" at the very beginning, Split will still scan all 5 million characters looking for more colons. That is a lot of unnecessary work for your Garbage Collector (GC).

⚡ Enter `strings.Cut`: The Performance Hero

Introduced to simplify common parsing patterns, strings.Cut has a beautifully simple signature:

Why it wins on the scoreboard:

Zero Slice Allocations: It returns two substrings and a boolean. No slice is created, meaning zero extra heap allocation for the container.
Early Exit: The moment it finds the first separator, it stops. If your delimiter is at index 10 of a 10,000-character string, Cut ignores the other 9,990 characters.
Cleaner Logic: You no longer have to check if len(parts) > 1. The found boolean tells you exactly what happened.

🛠️ Refactoring for Elegance

Moving from Split to Cut doesn't just make your app faster; it makes your code more readable.

The "Old" Way (Clunky):

// We only want the first two parts, but we still pay for a slice
parts := strings.SplitN(input, "=", 2)
if len(parts) < 2 {
    return fmt.Errorf("invalid format")
}
key, value := parts[0], parts[1]

The "Go 1.18+" Way (Sleek):

// Direct, intentional, and allocation-free
key, value, found := strings.Cut(input, "=")
if !found {
    return fmt.Errorf("invalid format")
}

🎓 Final Thoughts

As I continue to build out my career in code, I’ve realized that "Good Go" is about being a good neighbor to the runtime.

By switching to strings.Cut, you reduce CPU cycles and keep your memory footprint flat. For an ASCII art program, this means smoother rendering and less lag. For your career, it shows you care about the "How" just as much as the "What."

Next time you need to break a string in two, put down the axe. Use the scalpel.

DEV Community: Kevin Nambubbi

Why RAG Pipelines Fail on East African Documents — and What I Built to Fix It

The problem with generic chunking

The root cause

Building Hekima

Detection

Chunking strategies

The chunk output

The HTTP API

Technical choices worth explaining

What is next

AI Isn't Replacing Developers. It's Exposing Them.

Introduction

The Illusion of Instant Expertise

Production Doesn't Care Who Wrote the Code

AI Makes Understanding More Valuable

My Rule for Using AI

1. Why does this solution work?

2. What problem is this actually solving?

3. What are the trade-offs?

4. Could I debug this in production?

5. Could I explain it to another developer?

The Most Dangerous Technical Debt

AI Should Be Your Junior Developer

Final Thoughts

Discussion

Why Developers Shouldn't Blindly Trust AI-Generated Code: Lessons From a Real Project

The Project

The Trap

1. HTML and JavaScript Mismatches

2. Incorrect Numerical Sorting

3. Regressions

What Finally Worked

Where AI Excels

Boilerplate

Documentation

Brainstorming

Learning

Where AI Should Not Be Trusted Blindly

Production Logic

Architecture Decisions

Security-Critical Code

Performance Optimization

Bug Fixes

Practical Advice

Treat AI like a junior developer

Read generated code line by line

Keep requirements visible

Test continuously

Debug before regenerating

Final Thoughts

From Syntax to Systems

From Learning Syntax to Building Systems

The Alphabet Analogy

The Numbers Analogy

What Building Systems Actually Looks Like

The Biggest Lesson So Far

How Zone01 Kisumu "Build from Scratch" Approach Transformed Me from a Framework User to a Problem Solver

Why I’m Learning Go and JavaScript Together Instead of Separately

My Background

Different Strengths, Different Responsibilities

Building Something Production-Minded

Security From Day One

What I’m Focusing On

Final Thought

The Golang Trinity: Functions, Methods, Interfaces

Audit Logs: The Silent Guardian of Every Serious System

📂 The Hidden Superpower of Go's io/fs: Why Your Code Deserves a Universal Remote Control

GoLang #Programming #SoftwareEngineering #CleanCode #DeveloperTips #iofs #GoProgramming

The Surgical Precision of `strings.Cut`: Why You Should Stop Over-Splitting Your Go Code

🕵️ The Hidden Cost of strings.Split

⚡ Enter strings.Cut: The Performance Hero

Why it wins on the scoreboard:

🛠️ Refactoring for Elegance

🎓 Final Thoughts

🕵️ The Hidden Cost of `strings.Split`

⚡ Enter `strings.Cut`: The Performance Hero