DEV Community: Ryan Kikayi

RAG Explained Simply: How to Teach AI About Your Private Data

Ryan Kikayi — Mon, 31 Aug 2026 00:18:55 +0000

You've probably seen the term RAG everywhere lately — "RAG pipeline," "RAG chatbot," "build your own RAG app." It sounds complicated, but the idea behind it is actually pretty simple.

In this article, I'll explain RAG in plain language, then walk through how it works using a real project I built: Guidely, an internal knowledge assistant that answers questions using a company's own documents.

The Problem RAG Solves

Large language models (like GPT or Claude) are trained on a huge amount of general knowledge, but they don't know about your specific data — your company's internal docs, your product manuals, your onboarding guides. They also can't be retrained every time a document changes; that's slow and expensive.

RAG solves this without retraining the model at all.

Basically:

RAG means: before answering a question, first go find the relevant pieces of your own documents, and hand those to the AI along with the question.

That's it. "Retrieval" (finding the right information) + "Augmented Generation" (the AI answers using that information). Instead of the AI answering from memory alone, it answers using facts you hand it in the moment.

The Three Core Pieces

Let's break down the three things you need to make this work: chunking, embeddings, and vector search.

1. Chunking — Breaking Documents Into Pieces

You can't hand an AI model an entire 200-page document and ask it to search through it efficiently. So the first step is splitting documents into smaller, manageable pieces called chunks.

In Guidely, I used a token-window chunker — it splits text based on a fixed number of tokens (roughly, pieces of words) per chunk, rather than just splitting by paragraph or sentence. This matters because:

Chunks that are too big waste space and slow things down.
Chunks that are too small lose context and produce confusing answers.

A token-window approach gives you consistent, predictable chunk sizes, which makes the next steps more reliable.

2. Embeddings — Turning Text Into Numbers

Once you have chunks, you need a way to compare "how similar" two pieces of text are — for example, how similar is a chunk to the user's question?

Computers can't compare meaning directly, so each chunk gets converted into a list of numbers called an embedding (a vector). Text with similar meaning ends up with numbers that are mathematically close to each other, even if the wording is completely different.

For example, "How do I reset my password?" and "Steps to change your login credentials" would produce embeddings that are close together, because they mean roughly the same thing — even though the words barely overlap.

One thing I added in Guidely: a SHA-256 hash-based embedding cache. Generating embeddings costs time and money, so before creating a new embedding, I hash the chunk's content and check if it's already been embedded before. If it has, I reuse the cached version instead of generating it again. This alone cut down repeated work significantly, especially when documents get updated but most of the content stays the same.

3. Vector Search — Finding the Right Chunks

Now that every chunk has a numeric embedding, you need a fast way to search through thousands (or millions) of them to find the ones closest to the user's question.

This is where a vector database comes in. In Guidely, I used FAISS (Facebook AI Similarity Search) — a library built specifically for searching through large sets of embeddings quickly.

The flow looks like this:

User asks a question.
The question gets converted into an embedding, using the same method as the chunks.
FAISS compares that embedding against all the stored chunk embeddings and returns the closest matches.
Those matching chunks are the ones most likely to contain the answer.

Putting It All Together

Here's the full RAG flow, using Guidely as the example:

1. Documents come in (company docs, guides, wikis)
        ↓
2. Chunker splits them into token-window chunks
        ↓
3. Each chunk is embedded (with caching to skip repeat work)
        ↓
4. Embeddings are stored in a FAISS index
        ↓
5. User asks a question
        ↓
6. Question is embedded and compared against the FAISS index
        ↓
7. Top matching chunks are retrieved
        ↓
8. Chunks + question are sent to the AI model
        ↓
9. AI generates an answer grounded in the actual documents

The backend for this in Guidely runs on FastAPI, with FAISS handling the vector search, and a React/Vite frontend for the chat interface.

Why This Approach Works Well

No retraining needed. Update a document, re-chunk and re-embed it, and the assistant instantly "knows" the new information.
Answers are grounded in real sources. Instead of the AI guessing from general training data, it answers based on your actual documents — which also means you can show users exactly where an answer came from.
It scales. FAISS is built to handle large volumes of embeddings efficiently, so this approach holds up as your document set grows.

A Few Things I Learned Building This:

Chunk size matters more than you'd expect. Too large, and irrelevant details creep into the AI's context. Too small, and you lose the surrounding meaning needed to answer well.
Caching embeddings isn't just a nice-to-have — it's a real cost and speed saver once you're re-processing documents regularly.
Good retrieval matters more than a fancier AI model. If the wrong chunks get retrieved, even the best model will give a wrong or vague answer.

Conclusion

RAG isn't magic — it's really just: break documents into chunks, turn them into searchable numbers, find the closest matches to a question, and let the AI answer using those matches. Once you see it broken down like this, it becomes a lot less intimidating to build yourself.

If you're building something similar or have questions about any part of the pipeline, drop a comment below.

How to Structure a Project(Next.js + Go)

Ryan Kikayi — Sun, 30 Aug 2026 23:52:54 +0000

How I Structure a Next.js + Go Project (Frontend, Backend, and Deployment)

When you're building a full-stack app with Next.js on the frontend and Go on the backend, one of the first questions you'll face is: how do I organize this so it doesn't turn into a mess later?

I ran into this while building a school management system with Go, Next.js, and PostgreSQL — a project with several modules (students, finance, timetable, staff, and more). In this article, I'll walk through how I split the frontend and backend, how they talk to each other, and how I deploy both together.

1. One Repo or Two?

You have two options:

Monorepo — frontend and backend live in the same repository, in separate folders (e.g. /frontend and /backend).
Separate repos — each app has its own repository.

For a solo project or a small team, I prefer a monorepo. It's easier to keep frontend and backend changes in sync, and you only need to clone one project to get started. Separate repos make more sense once you have separate teams working independently, or when the frontend and backend have very different release schedules.

project/
├── backend/     (Go)
├── frontend/    (Next.js)
└── docker-compose.yml

2. Structuring the Backend (Go)

Instead of organizing your Go code by technical layer only (all handlers in one folder, all models in another), I organize it by feature/module first, then by layer inside each module. This matters a lot once your app has several modules.

backend/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── student/
│   │   ├── handler.go
│   │   ├── service.go
│   │   └── model.go
│   ├── finance/
│   │   ├── handler.go
│   │   ├── service.go
│   │   └── model.go
│   └── ...
├── pkg/
│   └── (shared utilities, e.g. auth, db, validation)
└── go.mod

Why this works well:

Each module is self-contained. If you need to change how "Finance" works, you know exactly where to look.
It's easier to onboard someone new — they can understand one module without reading the whole codebase.
If a module ever needs to become its own service later, it's already mostly separated.

3. Structuring the Frontend (Next.js)

On the frontend, I follow a similar idea — group by feature, and keep a clear separation between UI, data-fetching, and shared code.

frontend/
├── app/
│   ├── students/
│   ├── finance/
│   └── ...
├── lib/
│   ├── api/
│   │   ├── client.ts
│   │   ├── students.ts
│   │   └── finance.ts
│   └── types/
│       └── (shared TypeScript types)
├── components/
└── package.json

The lib/api/client.ts file is important — this is where all requests to the backend go through one place, instead of writing raw fetch calls all over the app.

4. How the Frontend and Backend Talk to Each Other

This is where a lot of things can go wrong if you're not careful, so here's what worked for me:

Keep a single API client. Instead of calling fetch() everywhere, wrap it in one function that adds the base URL, headers, and auth token automatically:

// lib/api/client.ts
const BASE_URL = process.env.NEXT_PUBLIC_API_URL;

export async function apiFetch(path: string, options: RequestInit = {}) {
  const token = getToken(); // however you store it

  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      Authorization: token ? `Bearer ${token}` : "",
      ...options.headers,
    },
  });

  if (!res.ok) {
    throw new Error(`Request failed: ${res.status}`);
  }

  return res.json();
}

Every module then builds on top of this — e.g. lib/api/students.ts calls apiFetch("/students").

Keep your types close to your API shape. In Go, define clear structs for your request/response bodies. On the frontend, write matching TypeScript types. It's manual work, but it saves you from a lot of confusing bugs where the frontend expects a field that the backend doesn't send.

Handle loading and error states the same way everywhere. With several modules, it's easy to end up with five different ways of showing "loading..." or an error message. Pick one pattern (a simple hook, or a wrapper component) and reuse it.

5. Local Development Setup

Running two apps at once can be annoying if it's not automated. I use docker-compose to start everything with one command:

version: "3"
services:
  backend:
    build: ./backend
    ports:
      - "8080:8080"
    env_file: ./backend/.env

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    env_file: ./frontend/.env
    depends_on:
      - backend

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"

For local dev, you also need CORS enabled on the Go backend so the frontend (running on a different port) can call it:

func corsMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
        w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
        w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
        next.ServeHTTP(w, r)
    })
}

In production, you'll usually avoid this problem entirely by putting both apps behind the same domain.

6. Deployment

There are two common ways to deploy a Next.js + Go project:

Option A: Same server, reverse proxy in front.
Both apps run on the same machine. A reverse proxy like Nginx or Caddy sits in front and routes traffic:

/api/* - Go backend
everything else - Next.js frontend

This avoids CORS issues completely and keeps things simple for small to mid-sized projects.

Option B: Separate hosting.
Frontend goes to a platform like Vercel, backend goes to a VM, container platform, or somewhere like Render/Fly.io. This gives you more flexibility to scale each part independently, but you'll need to handle CORS and manage two deployment pipelines instead of one.

For a project like the school management system, I went with Option A — one server, Go binary running behind Caddy, Next.js served alongside it. It kept the deployment simple, and simplicity mattered more than independent scaling at that stage.

7. What I'd Do Differently

If I started this project again, I'd generate the TypeScript types directly from the Go structs instead of writing them by hand on both sides. Keeping them in sync manually works, but it's an easy place to introduce bugs as the project grows. Tools like swaggo (for generating OpenAPI docs from Go) paired with an OpenAPI-to-TypeScript generator would save time and reduce mismatches.

Conclusion

Structuring a Next.js + Go project comes down to a few simple decisions: organize by feature on both sides, centralize how the frontend talks to the backend, and pick a deployment setup that matches the size of your project — not the size you imagine it might become.

If you're working on something similar, I'd love to hear how you've structured yours. Drop a comment below.

Image vs. Container: The Ultimate Guide to Stop Confusing the Two

Ryan Kikayi — Mon, 01 Jun 2026 15:52:00 +0000

We've all been there. You're 45 minutes into a Docker tutorial, feeling great about yourself, and then someone casually drops: "Just pull the image and spin up a container."
And you think: "...wait, aren't those the same thing?"
First - this has happened to a good number of us if we are to be honest. Even almost every single DevOps engineer, cloud architect, and platform wizard you admire has typed the wrong term in a sentence at least once in their career. It's practically a rite of initiation. There should be a badge for it if you ask me.

Why Does This Trip Everyone Up?

Here's the sneaky truth: Docker commands blur the line constantly. You type docker run nginx and something called a "container" starts — but wait, didn't you just use an "image" called nginx? Where did one end and the other begin?
The confusion lives in the fact that they are deeply related — one literally gives birth to the other. But they are fundamentally, completely different things. Getting this distinction straight is your official rite of passage into DevOps. Once it clicks, the rest of Docker feels like cheating.
Basically, A Docker Image is the blueprint: a frozen, static snapshot of everything your app needs - the OS layer, the dependencies, the config files, your actual code. It just sits there on disk, completely inert. You can't run a blueprint.
A Docker Container is the house: the live, running instance that was built from that blueprint. It has processes running, files potentially being written, network ports being listened on. It's alive.
And now, just like one blueprint can produce 10 identical houses on different streets - one Image can launch 10 identical Containers simultaneously; and that's where Docker's scaling magic comes from.

 # The image just sits here, unchanging
docker pull nginx

# Now we BUILD a house (container) from the blueprint
docker run nginx

# Build THREE houses from the same single blueprint
docker run nginx
docker run nginx
docker run nginx

Here is an example using a Class and an Object to help you understand; and it's very simple actually.

class Dog = Image
#The definition. Describes what a Dog has (name, breed) and can do (bark).
#Defined once. Never changes.

new Dog() = Container
#A real, live dog. Created from the class.
#Barking, eating, chewing on things it shouldn't - Even **"running"**😉

The Dog class is your Image - written once, stored, never actually "lives". Every time you call new Dog("Rex"), you're spinning up a Container. And by doing this you can instantiate as many as you like, and they all share the same starting definition while doing their own independent thing at runtime.

Quick Reference: The Cheat Sheet

Stick this onto your wall, tattoo it on your forearms, set it as your desktop backgrounds. Whatever works for you guys:

Property	Docker Image	Docker Container
Status	`static`	`Dynamic/ Running`
Stored where?	On disk (registry or local)	In memory + writable layer
Mutable?	`Read-only`	`Read + Write`
Can you run it?	No - you run from it	Yes - it is running
Analogy	Blueprint/ Class	House/ Object
Created with	`docker build` or `docker pull`	`docker run`
How many from one?	Infinite containers	One instance per `run`

🎓 You're Now Officially Initiated

Here's the TL;DR, burn it into your brain forever:

Image = the frozen, static blueprint. Read-only. Lives on disk. Does nothing by itself.
Container = the live, running instance built from an image. Has state. Things are happening.
One image can produce many containers. Containers are born from images and then go live their own lives.

📊Next Level

Now that this is locked in, go explore docker ps (lists running containers), docker images (lists images), and docker stop (stops a container without touching the image).

Go Error Handling: Annoying or Awesome?

Ryan Kikayi — Mon, 25 May 2026 07:40:27 +0000

For weeks when I was completely new to coding,I would always keep wondering; "What did I get myself into?", barely understanding what I'm looking at whenever I come across code that looked like this:

file, err := os.Open("data.txt")
if err != nil {
    log.Fatal(err)
}

data, err := io.ReadAll(file)
if err != nil {
    log.Fatal(err)
}

var result MyStruct
err = json.Unmarshal(data, &result)
if err != nil {
    log.Fatal(err)
}

And for some reason it just did not make any sense to me at first; what do you mean we're using 9 lines of code just for error checking - has to be a joke?!
Over at YouTube, no tutorial was relatable. I mean there were tutorials on error checking for python, and javascript, but the concept wasn't just sticking.
Eventually, I ended up just copying chunks of code that I barely understood and pasted them into mine. Function returns two things, assign them to a variable and err. Basically pasting the if err != nil block was what I knew I was doing, the reason why? Not so much.
I wasn't reading the error half of the time, I was just calling log.Fatal(err) hoping it would never have to run.

Later on after getting comfortable with the language, I decided to work on a personal project - a CLI tool that reads config files, makes API calls, and writes its output to disk. Unfortunately, it broke in production, the problem;

data, _ := json.Marshal(payload)

I had used a blank identifier _ to ignore the error completely - a habit I discovered to avoid having to write the check. This caused an API call to fail silently because the marshal was sending an empty body, and the API was rejecting it. And there I was, trying to debug something a single error message would have told me immediately.
I realized, in Go errors are not exceptions, they're values - like regular data, a functions gives back to you. When you call a function that can fail, it returns two things; the result, and an error. Go hands you the error and trusts you to deal with it. So basically, writing if err != nil is like saying "Something could go wrong here. What do you want to do about it?" in Go. Once I finally understood that I started seeing them as decision points.

So how do you actually make peace with it?

Early on, I used to write my errors the same: log.Fatal(err). When something broke, I'd get a vague message like unexpected end of JSON input with zero context about where in my program it came from.
The fix was wrapping errors with context using fmt.Errorf :

data, err := io.ReadAll(file)
if err != nil {
    return fmt.Errorf("failed to read config file: %w", err)
}

The %w keeps the original error intact so you can still inspect it, but now every error message tells you what your program was trying to do when it failed. That one change made debugging significantly less painful.
The second thing that helped was setting up a snippet in my editor. In VS Code, typing ife and hitting Tab expands to:

if err != nil {
    return err
}

The official Go extension already includes this — check your snippet settings if you haven't already. It sounds like a small thing, but when you're writing the pattern twenty times a day, not having to type it from scratch every time genuinely reduces the friction.

So — annoying or awesome?

Honestly? Both. Annoying at first, awesome once you understand why it exists.
Go made a deliberate choice to make error handling visible and local, rather than something that silently bubbles up through your stack and crashes things in ways you didn't expect. Every if err != nil is a decision point baked directly into your code. You always know where an error came from. You always have to decide what to do with it.
For a first language, that turned out to be a surprisingly good environment to learn in. I couldn't ignore problems — Go wouldn't let me. And when things went wrong, the error was almost always exactly where Go said it was.
Would I have picked a different first language if someone had warned me about this pattern? Maybe. Am I glad I stuck with Go? Absolutely.

If you're learning Go right now, I'm curious — what part of the language caught you off guard the most? Drop it in the comments.

Vibe Coding is a Last Resort Mistake!!

Ryan Kikayi — Thu, 12 Feb 2026 09:31:38 +0000

We've all been there. You're deep into a project, making great progress, and then you hit a wall. Maybe the app is having trouble reading data from the API, or your code for handling mistakes feels messy and confusing.
Instead of reaching for the official docs, you reach for the AI—your "coding genius."
That was my first big mistake.
Ten minutes later, all my clean, manual progress was gone. The AI had:

Restructured my structs without asking.
Injected unnecessary pointers that made no sense.
Turned my logic into a "hallucinated" masterpiece that wouldn't even run.

I didn’t realize it then, but I had fallen into the trap. I barely understood what was happening in my own file. It became a frantic back-and-forth conversation with ChatGPT where all I was doing was prompting, copying error messages, and pasting code. We all know how the copy-paste game ends.

How I Saved the Project:

To save my work, I had to stop the cycle. I was the victim, and my project was the casualty. To get back on track from that AI-generated mess, I had to take these steps:

The Hard Reset I had to go back to my last working version. If you aren't using Git yet, let this be your wake-up call. Being able to "undo" a hallucination is the ultimate safety net. I opened my terminal and ran:

bash
# This command resets your file to the last saved version
git checkout -- weather_app.go

Just like that, the AI "slop" was gone, and my original logic was back.

Surgical Prompting I stopped giving the AI my entire file. I isolated one specific logic block and asked: "Why is this specific line throwing an error?"
Verification Once the AI suggested a solution, I verified it using outside resources like StackOverflow and the Official Go Docs. This helped me actually learn the why behind the fix.
The "No-Paste" Rule Instead of pasting the code directly, I forced myself to manually type the solution back into my editor. This rebuilt the mental connection between my brain and the screen.

The "S.P.E.C." Framework:

From this encounter, I’ve learned that AI should be your last resort, not your first move when you hit a dead end. To keep your code from turning into "Slop," follow this framework:

S - Scope: Give the AI only the snippet it needs. "Only edit the FetchWeather function."
P - Parameters: Explicitly tell it: "Use only standard libraries."
E - Edge Cases: Ask: "How should this handle a 404 or a timeout?"
C - Constraints: Be firm: "Do not change my existing struct definitions."

Final Thoughts:

In 2026, anyone can prompt, but not everyone can engineer.
Don't let AI be the lead architect of your learning journey. Use it as a pair programmer that requires strict instructions. The moment you stop understanding what you're doing or what is on your screen—stop.
Go back to your original code, follow the framework, and stay in control of your logic.