DEV Community: Carlosmgs111

How I used DDD and hexagonal architecture to build klay+ — a flexible, provider-agnostic RAG infrastructure you can plug into any project.

Carlosmgs111 — Fri, 27 Mar 2026 18:21:26 +0000

The Problem Everyone's Having "My chunking strategy is hardcoded everywhere. I want to experiment with different approaches but changing it means touching 15 files."

RAG is everywhere right now. But most implementations share the same problem — they're built as scripts, not as infrastructure. They work for the demo, they work for the first provider, and then they break the moment something needs to change.
I kept seeing this pattern and thought: what if you could build RAG infrastructure the way you'd build any serious backend system? With clear boundaries, swappable providers, and an architecture that actually survives evolving requirements?
That's what klay+ is — a RAG infrastructure toolkit built with DDD and hexagonal architecture in TypeScript. You integrate it into your project, pick your providers, define your processing strategies, and the architecture handles the rest.
This article is about how it's structured and why.

Why DDD for RAG Infrastructure?

At first glance, DDD seems like overkill for a RAG pipeline. Ingest documents, chunk them, embed them, search. Four steps, right?
But look closer. A RAG system that's actually useful in production has to deal with:

Multiple input formats (PDF, markdown, plain text) with different extraction logic
Configurable chunking (recursive, sentence-based, fixed-size) that you need to experiment with
Pluggable embedding providers that you might swap mid-project
Knowledge versioning so you can track why search results changed
Multiple runtimes if you want offline/browser support

These aren't steps in a pipeline. They're independent domains with their own rules, their own lifecycles, and their own reasons to change. That's literally the use case for bounded contexts.

The 4 Bounded Contexts

After a few iterations (and a few wrong turns), I ended up with four contexts. Each one owns a piece of the RAG pipeline and communicates through service facades.

1. Source Ingestion
Handles everything related to content acquisition and source-level knowledge management. A consumer of klay+ feeds it a PDF, text, or markdown — this context validates input, creates a Source aggregate, kicks off an ExtractionJob, and manages the SourceKnowledge hub that bridges raw content with its semantic projections.

const source = Source.create({
  name: "research-paper.pdf",
  type: SourceType.PDF,
  metadata: { pages: 42, author: "..." }
});

const job = ExtractionJob.create({
  sourceId: source.id,
  strategy: ExtractionStrategy.PDF
});

ExtractionJob is a separate aggregate because extraction can fail, retry, and run async — it has its own lifecycle. And SourceKnowledge lives here too because one source can produce multiple projections over time (different chunking, different embedding model), so tracking that history is part of managing the source itself.

2. Context Management
Groups knowledge sources into queryable collections and tracks lineage. The KnowledgeLineage aggregate records every transformation applied to content.

const lineage = KnowledgeLineage.create({
  contextId: context.id,
  sourceId: source.id,
  transformations: [
    { type: "chunking", strategy: "recursive", chunkSize: 512 },
    { type: "embedding", provider: "openai", model: "text-embedding-3-small" }
  ]
});

This is the answer to "I changed my chunking strategy and now results are worse — what happened?" Without lineage, you're guessing. With it, you can diff configurations and roll back.

3. Semantic Processing
Orchestrates the chunking → embedding pipeline. Owns SemanticProjection and ProcessingProfile.

const profile = ProcessingProfile.create({
  chunkingStrategy: "recursive",
  chunkSize: 512,
  overlap: 50,
  embeddingProvider: "openai",
  embeddingModel: "text-embedding-3-small"
});

The ProviderRegistry pattern is what makes the multi-provider promise real. A factory resolves the correct implementation based on config. Your project uses OpenAI today? Cool. Need to switch to a local model tomorrow? Implement one interface. The domain doesn't care.

4. Knowledge Retrieval
The simplest context, intentionally. Read-only. Takes a query, computes its embedding, ranks passages by cosine similarity.

const queryEmbedding = await embeddingProvider.embed(query);
const results = await vectorStore.findSimilar(queryEmbedding, {
  threshold: 0.7,
  limit: 10,
  contextId: activeContext.id
});

Separate context because retrieval is read-heavy and latency-sensitive — totally different scaling profile from processing. You don't want optimizing one to break the other.

The Shared Kernel

All contexts build on the same foundational abstractions. This is the only code that crosses boundaries.
Entity & AggregateRoot

abstract class Entity<Id> {
  protected readonly _id: Id;
  equals(other: Entity<Id>): boolean {
    return this._id === other._id;
  }
}

abstract class AggregateRoot<Id> extends Entity<Id> {
  private _events: DomainEvent[] = [];

  protected record(event: DomainEvent): void {
    this._events.push(event);
  }

  clearEvents(): DomainEvent[] {
    const events = [...this._events];
    this._events = [];
    return events;
  }
}

ValueObject — Immutable by Default

abstract class ValueObject<T> {
  protected readonly props: Readonly<T>;

  constructor(props: T) {
    this.props = Object.freeze(props);
  }

  equals(other: ValueObject<T>): boolean {
    return JSON.stringify(this.props) === JSON.stringify(other.props);
  }
}

Result — Because Try-Catch Isn't a Strategy

Every domain operation returns a Result. No exceptions for expected failures, no null propagating silently through three layers.

class Result<E, T> {
  static ok<T>(value: T): Result<never, T>;
  static fail<E>(error: E): Result<E, never>;

  isOk(): boolean;
  isFail(): boolean;
  map<U>(fn: (value: T) => U): Result<E, U>;
  flatMap<U>(fn: (value: T) => Result<E, U>): Result<E, U>;
  match<U>(handlers: { ok: (v: T) => U; fail: (e: E) => U }): U;
}

Repository — Three Methods

interface Repository<T, Id> {
  save(entity: T): Promise<Result<PersistenceError, void>>;
  findById(id: Id): Promise<Result<PersistenceError, T | null>>;
  delete(id: Id): Promise<Result<PersistenceError, void>>;
}

Each context defines its own repositories. Infrastructure implements them. The domain doesn't know if it's talking to NeDB, IndexedDB, or a potato.

The 6 Principles (Enforced by Tests)

Not guidelines. Invariants. Break one and CI breaks.

1. Dependency Rule — Inward only. Adapters → Application → Contexts → Shared Kernel.
2. Tell, Don't Ask — You don't inspect aggregate state. You tell it what to do and get a Result.
3. Port Isolation — Each context defines its own interfaces. Semantic Processing doesn't know NeDB exists.
4. Composition over Inheritance — Only DDD building blocks inherit. Everything else composes.
5. Result-Based Errors — Domain failures are values, not exceptions.
6. Illegal States Are Unrepresentable — A ChunkSize of -1? Can't construct it.

What This Enables for Your Project

The whole point of klay+ being infrastructure (not a product) is that it adapts to your context:

Swap providers without rewriting pipeline code — implement one interface
Experiment with chunking strategies by changing a config, not refactoring files
Track why search results changed through immutable lineage
Run server-side or browser-side — same logic, pick your runtime *13 tests ensuring the architecture holds as you extend it

No vendor lock-in. No "works for the demo but breaks in production." Just a solid foundation for RAG that you plug into your stack.

Check It Out

klay+ is open source: github.com/Carlosmgs111/klay-plus
If you've ever wished your RAG pipeline had real architecture instead of glue code, take a look. Star it, fork it, open an issue, tell me what you'd change.
And if you've built RAG infrastructure yourself — what worked? What would you do differently? The comments are open.

Part 1 of the klay+ Architecture Series. Next: Hexagonal Architecture with Astro + TypeScript — how your framework and your domain can coexist without pain.

Why every RAG project I've built ends up fighting the pipeline — and what I'm doing about it

Carlosmgs111 — Mon, 16 Mar 2026 06:54:35 +0000

The pattern that keeps repeating

If you've built a RAG application, this probably sounds familiar:

You pick an embedding model
You set up a vector store
You write chunking logic
You wire everything together
You realize the chunking doesn't work for your use case
You rewrite half the pipeline

The models are the easy part. The pipeline glue is where projects slow down — and where most teams burn weeks they didn't plan for.

A support chatbot needs sentence-level chunks. A legal search tool needs paragraph-level with overlap. An internal knowledge base needs something in between. But every time you change one component, you're rewiring the whole thing.

The actual problem

It's not that building a RAG pipeline is hard. It's that iterating on one is painful.

You pick a chunking strategy, embed a few thousand documents, and your retrieval quality is... okay. Not great. So you want to try a different approach. But that means:

Re-processing all your documents
Re-generating all your embeddings
Hoping the new strategy is actually better
Doing all of this without breaking what's already working

Most teams don't experiment. They ship the first thing that "kind of works" and move on. Retrieval quality suffers, but the cost of iteration is too high.

What I'm building

I started working on klay+ — a composable RAG infrastructure layer where every component is independently swappable.

The core idea: your application code shouldn't change when you change your RAG strategy.

Here's what that looks like in practice:

Ingestion

Feed in PDFs, Markdown, HTML, or plain text. The content gets normalized automatically — no format-specific parsing logic in your app.

Chunking

Choose your strategy per use case:

Recursive — split by structure (headings, paragraphs, sentences)
Sentence-aware — keep semantic units intact
Fixed-size — predictable token counts for context windows
Custom — bring your own logic

The key: switching from recursive to sentence-aware chunking doesn't require touching your application code or your retrieval logic.

Embedding

Plug in the provider that fits your stage:

Hash-based — zero API cost, great for local development
OpenAI / Cohere — production-grade quality
Local models via WebLLM — self-hosted, no data leaves your infra

Swap providers without re-architecting. Your retrieval layer doesn't know or care which embedder generated the vectors.

Retrieval

Query by meaning, not keywords. Results come back ranked by relevance scores. Your application gets a clean interface regardless of what's happening underneath.

The part I'm most excited about: parallel projections

This is the feature that solves the iteration problem. You can generate a new projection — different chunking, different embedding, different strategy — side by side with your production index.

Compare retrieval quality before committing to a migration. No downtime, no risk.

Technical decisions

A few choices worth mentioning:

Self-hostable — your documents don't leave your infrastructure if you don't want them to
No vendor lock-in — every component has multiple provider options
Static configuration — strategies are defined declaratively, not buried in application code

Where it stands

klay+ is in early development. I'm collecting feedback from developers who are building with RAG to understand which pain points matter most.

If you've fought with RAG pipelines before, I'd genuinely love to hear:

What part of the pipeline costs you the most time?
How do you handle iteration on retrieval quality?
What's your current stack and what would you swap if you could?

The landing page is here if you want to follow along: klay-plus-landing.vercel.app