DoomHelix uses ACP, the Agent Client Protocol behind Zed’s agent integrations, so the editor does not have to be tied to one model or backend. I mostly use it with Codex ACP right now, but the editor side is built around the protocol, so other compatible backends can fit into the same flow.

I recorded a short walkthrough showing installation and a few places where the agent is useful while editing.

Watch on YouTube

Installing DoomHelix

The installer builds from source when a prebuilt release is not available, installs the dhx launcher, installs the runtime files, and writes a small agent config if one does not already exist. The first run is mostly about getting the editor and the agent backend configured.

curl -fsSL https://raw.githubusercontent.com/borngraced/doom-helix/main/install.sh | sh

After installation:

dhx --health

If you are checking a specific language setup:

dhx --health go
dhx --health rust

The binary you run is:

dhx

DoomHelix still uses the normal Helix config and runtime locations, so I do not need to maintain a totally separate editor setup just because I am using the fork. Agent-specific config lives in:

~/.config/helix/agent.toml

A minimal Codex ACP config looks like this:

enable = true
name = "codex"
command = "codex-acp"
args = []
panel-position = "right"
panel-size = 30
auto-context-on-open = true
include-theme = true
include-command-history = true
include-visible-buffer = true
include-diagnostics = true

The installer does not try to own your full Helix config, which is important to me because I want DoomHelix to feel like Helix with an agent added, not a separate editor that forces me to rebuild all my habits from scratch. Your theme, keymaps, languages, and normal editor settings stay in ~/.config/helix/config.toml and ~/.config/helix/languages.toml.

Starting the Agent

Inside the editor, I keep the agent commands under Space a, so chat, explain, fix, refactor, panel focus, restart, status, and resizing all live in one place instead of being scattered across random commands.

Space a s   start agent
Space a S   status
Space a c   chat
Space a e   explain selection
Space a f   fix selection
Space a r   refactor selection
Space a E   edit
Space a P   show/focus panel
Space a +   grow agent panel
Space a -   shrink agent panel
Space a R   restart agent
Space a x   clear panel

The command form is also available when I want to type the action directly:

:agent start
:agent status
:agent chat
:agent explain
:agent fix
:agent refactor
:agent panel
:agent restart

The panel can be resized with the keyboard and moved between the sides of the editor, which matters more than it sounds because the right layout depends on the task. If I am reading a longer response, bottom panel feels better; if I am editing code and want the agent beside me, right panel is usually better.

:agent panel position right
:agent panel position bottom
:agent panel position left
:agent panel position top

The Important Part: Editor Context

The thing I care about most is context, because an agent in the editor should know what I am looking at without making me manually paste half my workspace into a chat box. If I select code and ask the agent to explain it, DoomHelix sends the selected code, active file path, language, cursor position, diagnostics, and other useful editor state, and the chat view also shows the selected block so I can see exactly what the agent received.

That matters because “review this” is useless if the agent does not know what “this” means. I want the editor to collect the obvious context for me, while still making it clear what was sent.

For example, I can select a Go handler and run:

Space a e

Then ask:

does this handler have any edge cases?

The agent sees the selection and responds in the DoomHelix panel, so I do not need to copy the file path, paste the code into a browser, or manually explain where I am in the project before asking the actual question.

Fixing and Refactoring Code

The second use case is asking the agent to change code. I can select a function and run:

Space a f

or:

Space a r

DoomHelix sends the editor context through ACP and lets the backend request tool permissions. That was the direction I wanted from the beginning: the editor should not just be a text box for prompts; it should understand enough about the current file, selection, and diagnostics to make the agent useful.

There is still a lot of work to do. Rendering, permission prompts, session restore, and support for multiple agents can all get better, but the basic loop already feels different from using a separate terminal. I can stay inside the editor, select code, ask for explanations, request edits, resize or move the panel when the response needs more room, and keep working without switching tools.

Why Fork Helix?

I like Helix because it is fast and pragmatic, with strong defaults, good LSP support, tree-sitter, multiple selections, and a clean modal editing model, so I did not want to build a new editor from scratch. I wanted to see what happens when agent-assisted coding is part of a serious modal editor instead of living beside it as another chat window.

DoomHelix is still early, but the direction is simple:

• Keep Helix as the foundation.
• Use ACP as the agent protocol.
• Keep context visible and inspectable.
• Make agent work feel like editing, not a separate chat window beside the editor.

That is the experiment.

Repo:

github.com/borngraced/doom-helix

The higher-level answer was already obvious to me before I wrote any code. A contiguous array exists for a reason. CPU caches exist for a reason. Filesystem storage layouts and in-memory array layouts are solving very different problems. But some ideas are worth implementing precisely because you know they are probably wrong. They force you to stop hand-waving and actually measure where the machine starts getting annoyed.

The Basic Idea

The shape I wanted was:

pub struct PagedSmallVec<
    T,
    const INLINE: usize,
    const DIRECT: usize,
    const CHUNK: usize,
> {
    direct: [Option<Box<[MaybeUninit<T>; CHUNK]>>; DIRECT],
    inline: [MaybeUninit<T>; INLINE],
    len: usize,
}

The plan was simple. Keep a small inline buffer for the first few elements, once that fills up, spill into fixed-size direct chunks instead of one large contiguous heap allocation. Later, if the experiment felt promising, I could extend it into double-indirect and triple-indirect tiers like an inode table.

At a conceptual level, it sounds reasonable: small data stays inline, growth past inline avoids large contiguous reallocations, and the design can scale to multiple indirection levels. It is exactly the kind of idea that sounds smarter in theory than it turns out to be on a CPU.

Stage One: Just Inline + Direct Chunks

I intentionally kept the first version simple. So there’s no double-indirect and triple-indirect. Just enough to see whether the first stage had any chance at all.

The hot indexing path after the inline region is basically:

let paged_index = index - INLINE;
let chunk_index = paged_index / CHUNK;
let offset = paged_index % CHUNK;

Then read from:

self.direct[chunk_index][offset]

So stage one is not conceptually complicated. It is just an inline array plus a direct chunk table. That means if performance is bad, it is not because the logic is too intellectually deep. It is because every extra indirection, branch, and lookup is costing something real.

The First Real Problem: Unsafe Code

The moment you back a container with MaybeUninit<T>, the project stops being “write a cute data structure” and becomes “maintain invariants without lying to yourself.”

The early versions had all the predictable issues:

pub fn push(&mut self, val: T) {
    self.write_slot(self.len, val);
    self.len += 1;
}

fn write_slot(&mut self, index: usize, val: T) {
    // ...
    self.len += 1; // bug
}

That kind of thing immediately corrupts logical state.

I also had the usual problems around:

fn take_slot(&mut self, index: usize) -> T {
    unsafe { self.inline[index].assume_init_read() }
}

That is only sound if index < len, the slot is initialized, and length tracking is correct.

And drop is another place where this gets real very quickly:

impl<T, const INLINE: usize, const DIRECT: usize, const CHUNK: usize> Drop
    for PagedSmallVec<T, INLINE, DIRECT, CHUNK>
{
    fn drop(&mut self) {
        for i in 0..self.len {
            // drop initialized slots only
        }
    }
}

Once I started fixing those bugs, it became obvious that the unsafe part of this project was not some tiny implementation detail. It was the foundation. If length tracking is wrong by even one slot, everything after that becomes suspect.

The Initial API Looked Like a Normal Vec

The first public API looked like exactly what you would expect:

impl<T, const INLINE: usize, const DIRECT: usize, const CHUNK: usize>
    PagedSmallVec<T, INLINE, DIRECT, CHUNK>
{
    pub fn push(&mut self, val: T) { /* ... */ }
    pub fn pop(&mut self) -> Option<T> { /* ... */ }
    pub fn get(&self, index: usize) -> Option<&T> { /* ... */ }
    pub fn remove(&mut self, index: usize) -> Option<T> { /* ... */ }
    pub fn swap_remove(&mut self, index: usize) -> Option<T> { /* ... */ }
}

That was fine for usability, but it hid the real issue: this structure is not naturally contiguous. So whenever I used it exactly like Vec, I was forcing it into an access pattern that favored the standard containers.

Benchmarks: Vec Usually Won, SmallVec Usually Came Second

I benchmarked the structure against Vec<T>, SmallVec<[T; N]>, and PagedSmallVec<T, INLINE, DIRECT, CHUNK> across append_only, append_pop, full_iteration, random_indexing, remove, and swap_remove, using u32, [u8; 64], and String as the test element types. The benchmark harnesses are in the repo too, mainly benches/compare.rs and benches/push_u32.rs.

The broad result was not subtle.

For normal vector-shaped workloads, Vec usually came first, SmallVec usually came second, and the paged structure usually came third. For cheap scalar types like u32, the gap was especially ugly. That was not surprising once I thought about it properly. A contiguous array is doing exactly what the CPU wants: predictable memory access, fewer pointer hops, fewer branches, fewer cache misses. My paged structure was paying for chunk math and chunk lookups just to reach data that Vec could reach by simple pointer arithmetic.

Focused u32 Microbenchmarks

To get a cleaner signal, I also split out the u32 append-path microbenchmarks into benches/push_u32.rs. These run at N = 4096 and only measure push, push + pop, and extend_from_slice.

That table makes the trade-off very explicit. Vec still wins the normal append-shaped paths comfortably, SmallVec still does very well, and the paged layouts are only competitive with each other, not with the contiguous ones. But the chunk size result is useful: 512 edges out 256 for batch append, while both are basically in the same class for the single-element microbenches.

Memory Profile

I also added a tiny memory probe at examples/memory_profile.rs and ran it on a one-shot build of 1,000,000 u32 values. The stack footprint numbers come from size_of::<...>(), and the peak memory numbers come from /usr/bin/time -l.

That result is interesting for the exact reason the throughput tables are bad: the paged layout pays a much larger structural footprint up front, but in this one-shot build it also avoids some of the peak memory growth that comes from contiguous reallocation. So the design is not free, but the cost is not one-dimensional either. You pay for it in raw access speed and container size, and you sometimes get something back in growth behavior.

Random Access Was Exactly As Bad As It Should Have Been

The indexed access path looked like this:

pub unsafe fn get_unchecked(&self, index: usize) -> &T {
    if index < INLINE {
        return self.inline.get_unchecked(index).assume_init_ref();
    }

    let paged_index = index - INLINE;
    let chunk_index = paged_index / CHUNK;
    let offset = paged_index % CHUNK;

    self.direct
        .get_unchecked(chunk_index)
        .as_ref()
        .unwrap_unchecked()
        .get_unchecked(offset)
        .assume_init_ref()
}

There is nothing shocking about why this loses to Vec on random indexing. Even the “simple” stage-one version still has an inline-vs-paged branch, subtraction, division, modulo, a chunk lookup, and a slot lookup. That is simply more work than contiguous memory.

Ordered Remove Did Not Magically Get Better

This was one place where I think it is easy to fool yourself.

You might look at paged storage and think, “maybe middle removal is cheaper because I am moving chunks, not a whole buffer.”

Not really.

If you want order-preserving remove, you still conceptually shift the whole tail:

pub fn remove(&mut self, index: usize) -> Option<T> {
    let removed = self.take_slot(index);

    for i in (index + 1)..self.len {
        let val = self.take_slot(i);
        self.write_slot(i - 1, val);
    }

    self.len -= 1;
    Some(removed)
}

That is still O(n), and in my case it was slower than Vec and SmallVec because the contiguous containers get to do their movement in a layout that is much friendlier to the CPU.

swap_remove was less terrible, but again the paged structure did not become some surprise winner. It just became less disadvantaged.

The First Thing That Actually Helped: Chunk-Native Iteration

The first genuinely good result came when I stopped traversing the structure through repeated get(i).

My original full iteration benchmark looked like this:

for i in 0..vec.len() {
    sum += vec.get(i).unwrap().score();
}

That was a bad fit for the layout. Sequential traversal through a paged structure should not pretend to be repeated random indexing.

So I added:

pub fn for_each_chunk(&self, mut f: impl FnMut(&[T])) {
    for chunk in self.chunks() {
        f(chunk);
    }
}

and:

pub fn for_each_ref(&self, mut f: impl FnMut(&T)) {
    self.for_each_chunk(|chunk| {
        for value in chunk {
            f(value);
        }
    });
}

That changed the picture a lot. Once full scans were expressed chunk-by-chunk, the structure became much more competitive for sequential traversal. That was the point where the design stopped feeling like “a bad Vec” and started feeling like “a different structure with a different natural API.”

I Added Chunk Iterators and Batch Append Too

Once chunk traversal proved useful, it made sense to expose it directly:

pub struct ChunkIter<'a, T, const INLINE: usize, const DIRECT: usize, const CHUNK: usize> {
    vec: &'a PagedSmallVec<T, INLINE, DIRECT, CHUNK>,
    remaining: usize,
    next_chunk_index: usize,
    yielded_inline: bool,
}

And for append-heavy work, I added:

pub fn extend_from_slice(&mut self, values: &[T])
where
    T: Clone,
{
    // fill inline first, then write chunk by chunk
}

This fit the layout better than repeating push() in a loop, even when it was not yet a dramatic performance win.

That was another important lesson: a good API does not need to beat the standard one immediately to still be the right API for the structure.

Then I Optimized the Hot Append Path

Append was an obvious place to focus next, so I added:

tail_chunk_index: usize,
tail_offset: usize,
current_chunk_ptr: *mut MaybeUninit<T>,

The idea was to cache the logical tail position, cache a raw pointer to the current chunk, only allocate the next chunk when entering it, and make steady-state append look like this:

unsafe { (*self.current_chunk_ptr.add(self.tail_offset)).write(val) };

That helped append-heavy paths. Not enough to beat Vec, but enough to remove some of the overhead from repeatedly going through more abstract chunk lookup logic on every write.

Chunk Size Was Not a One-Size-Fits-All Story

I also turned chunk size into a const generic and benchmarked 64, 128, 256, and 512.

What I found was not “bigger is always better.” For u32, bigger chunks often helped batch append and sometimes helped append-heavy workloads. In extend_micro/u32, for example, 256 reached about 576 Melem/s while 512 reached about 609 Melem/s. But for pure push and push+pop, 256 came out as the better compromise: in push_only_micro/u32, 256 was about 382 Melem/s while 512 was about 342 Melem/s, and in push_pop_micro/u32, 256 was about 326 Melem/s while 512 was about 314 Melem/s.

For [u8; 64], larger chunks did not help nearly as much, and for some paths they were worse. For String, the differences were smaller and more workload-dependent.

So I settled on 256 as the default chunk size because the current container is still more push/pop-shaped than purely bulk-append-shaped.

Where This Can Actually Beat Vec

The honest answer is: not in the generic “just use it like a normal vector” case. But there are real workloads where a chunked layout like this can outperform Vec, or at least make a much stronger trade.

The first is append-heavy systems where growth to large sizes is common and the cost of repeated contiguous reallocation actually matters. Think large in-memory logs, event buffers, tracing pipelines, or ingestion queues that mostly grow, occasionally flush, and rarely do random indexing in the middle. In those systems, avoiding a full-buffer move during growth can be more important than having the absolute cheapest indexed load.

The second is chunk-native processing. If your workload naturally operates in runs instead of individual elements, the layout starts to fit the problem much better. A good example is streaming analytics or batch transforms where you want to scan a buffer chunk by chunk, apply a transform, serialize a chunk, compress a chunk, or hand a chunk to another stage. That is exactly why for_each_chunk and chunk iterators ended up being much more natural APIs than trying to force everything through get(i).

The third is memory behavior under allocator pressure. Vec is excellent when it can keep getting larger contiguous regions cheaply, but that assumption gets weaker for very large or long-lived allocations. In fragmented heaps or systems with many growing buffers alive at once, allocating one more fixed-size chunk can be a better trade than asking the allocator for a much larger contiguous block and then copying everything into it.

The fourth is reference and chunk stability. If a system wants to hold onto chunk-local slices, process pages independently, or hand off partially filled chunks between stages, this structure is much friendlier than a Vec that may relocate its entire backing buffer on growth. In other words, once the unit of work becomes “chunk” instead of “element”, the design stops looking strange and starts looking deliberate.

So I would not sell this as “better than Vec.” I would sell it as “better than Vec for append-heavy, chunk-oriented workloads where contiguous reallocation is one of the real costs.”

The Real Lesson

At this point I think the biggest mistake would be judging the structure only by how well it mimics Vec.

Its natural APIs are not primarily get, remove, and random indexing. They are closer to for_each_chunk, chunk iterators, batch append, and chunk-wise transforms. That is where the layout starts making sense. Once I stopped forcing the structure through access patterns optimized for contiguous memory, the experiment became much more informative.

My Verdict

If your goal is to beat Vec, beat SmallVec, win scalar push and pop, or win random indexing, inode-style array storage in Rust is a bad idea.

If your goal is to understand low-level container invariants, see exactly where pointer-heavy layouts lose, experiment with chunk-native APIs, and learn where contiguous storage wins and why, then it is a very good experiment.

So my final verdict is this: judged as a traditional vector, it did not do well but judged as an experiment, it went very well, because it made the trade-offs impossible to ignore. And honestly, that is usually the most useful outcome from a bad idea that was worth building anyway.

If you want to read through the full implementation, here is the code on GitHub: borngraced/paged-small-vec.

Tweet

So I said why not write on why developers shouldn’t stop at scalar types. Imagine a function takes a string, returns a number, and we call it “typed.” But this is a shallow form of type safety, one that gives us a false sense of security while letting entire categories of bugs slip through unnoticed.

Let me walk you through why scalar types fail us, and what I believe a truly typed codebase should look like.

The Positional Parameter Problem

Say I have a function that processes a seller payout after an order is delivered. It takes a shop ID, a customer ID, an order ID, the gross amount, platform fee, transaction fee, and net amount.

JavaScript:

function processOrderPayout(shopId, customerId, orderId, amount, platformFee, txFee, netAmount) {
  // ...
}

Go:

func ProcessOrderPayout(shopID string, customerID string, orderID string, amount int64, platformFee int64, txFee int64, netAmount int64) error {
    // ...
}

Rust:

fn process_order_payout(shop_id: String, customer_id: String, order_id: String, amount: i64, platform_fee: i64, tx_fee: i64, net_amount: i64) {
    // ...
}

Seven parameters. Three IDs that are all strings. Four money values that are all integers. Now imagine somewhere in my codebase, a caller writes this:

process_order_payout(customer_id, shop_id, order_id, net_amount, tx_fee, platform_fee, amount);

The customer ID went in place of the shop ID. The net amount went in place of the gross amount. The fees are swapped. The compiler doesn’t complain. Tests probably pass too. The application runs, pays out the wrong entity, credits the wrong amount, and nobody notices until a seller asks why they received ₦350 instead of ₦54,000.

This is what bit me. The compiler checks the shape of the data, not the meaning. A String is a String is a String, and an i64 is an i64 is an i64. The type system has no way to tell a shop ID apart from a customer ID, or a gross amount from a net amount, when they share the same underlying type.

“Just Use a Struct.” Better, But Not Enough

The natural next step is grouping parameters into a struct or object.

JavaScript:

function processOrderPayout({ shopId, customerId, orderId, amount, platformFee, txFee, netAmount }) {
  // ...
}

Go:

type OrderPayoutParams struct {
    ShopID      string
    CustomerID  string
    OrderID     string
    Amount      int64
    PlatformFee int64
    TxFee       int64
    NetAmount   int64
}

func ProcessOrderPayout(params OrderPayoutParams) error {
    // ...
}

Rust:

struct OrderPayoutParams {
    shop_id: String,
    customer_id: String,
    order_id: String,
    amount: i64,
    platform_fee: i64,
    tx_fee: i64,
    net_amount: i64,
}

fn process_order_payout(params: OrderPayoutParams) {
    // ...
}

This is better. Named fields eliminate positional confusion. You can’t accidentally swap shop_id and customer_id when you’re explicitly naming them at the call site.

But we’ve only solved one problem. Look at what the struct doesn’t prevent:

let params = OrderPayoutParams {
    shop_id: customer_id,       // oops, customer ID assigned to shop field
    customer_id: shop_id,       // oops, shop ID assigned to customer field
    order_id: order_id,
    amount: net_amount,         // oops, net amount assigned to gross amount field
    platform_fee: tx_fee,       // oops, fees are swapped
    tx_fee: platform_fee,
    net_amount: amount,         // oops, gross amount assigned to net field
};

The compiler is perfectly happy. Every string field got a String. Every integer field got an i64. The fact that customer_id contains a customer identifier and not a shop identifier? Invisible to the type system.

This might seem contrived, but it happens all the time in real codebases. Variables get renamed. Data flows through multiple layers. A function receives values from a database row and passes them into a struct, and nobody remembers which column mapped to which field. Someone refactors and swaps two fields, and the compiler catches zero of the call sites that now pass data into the wrong slots.

The struct gave us named assignment, but not semantic correctness. The types are still lying. They say “this field accepts a string” when what we actually mean is “this field accepts a shop identifier.” They say “this field accepts an integer” when what we actually mean is “this field accepts a platform fee in kobo.”

The Deeper Problem: Primitives Erase Meaning

This goes way beyond my payout example. Scalar types like string, int, float, and bool are building blocks, but they carry no domain meaning. When your codebase passes around raw primitives everywhere, you lose the ability to reason about what data actually means at the type level.

Here are bugs I’ve either hit or seen others hit that scalar types will never catch:

Passing a user ID where an order ID is expected. Both are int or string. Both represent identifiers. But mixing them up means you’re querying the wrong table, charging the wrong customer, or deleting the wrong record.

Mixing up units. A distance in meters passed to a function expecting kilometers. A price in cents passed to a function expecting dollars. A duration in seconds stored in a field labeled “minutes.” All the same type, f64 or int, and the compiler won’t say a word.

Confusing sanitized and unsanitized input. A raw user-provided string passed directly into a SQL query or HTML template. The type system sees String. It doesn’t know “this string hasn’t been escaped yet.” This is how injection vulnerabilities happen.

Swapping latitude and longitude. Both f64. Both coordinates. Swap them and your map renders on the wrong continent.

All of these compile. All of them might pass tests. All of them have caused real production incidents. And all of them are preventable.

The Solution: Make Invalid States Unrepresentable

The fix is simpler than you’d think. Stop using scalar types for domain concepts. Wrap every meaningful value in its own type.

Rust:

struct ShopId(String);
struct CustomerId(String);
struct OrderId(String);
struct Amount(i64);
struct PlatformFee(i64);
struct TxFee(i64);
struct NetAmount(i64);

struct OrderPayoutParams {
    shop_id: ShopId,
    customer_id: CustomerId,
    order_id: OrderId,
    amount: Amount,
    platform_fee: PlatformFee,
    tx_fee: TxFee,
    net_amount: NetAmount,
}

fn process_order_payout(params: OrderPayoutParams) {
    // ...
}

Now try to swap them:

let params = OrderPayoutParams {
    shop_id: customer_id,       // ERROR: expected `ShopId`, found `CustomerId`
    customer_id: shop_id,       // ERROR: expected `CustomerId`, found `ShopId`
    order_id: order_id,
    amount: net_amount,         // ERROR: expected `Amount`, found `NetAmount`
    platform_fee: tx_fee,       // ERROR: expected `PlatformFee`, found `TxFee`
    tx_fee: platform_fee,       // ERROR: expected `TxFee`, found `PlatformFee`
    net_amount: amount,         // ERROR: expected `NetAmount`, found `Amount`
};

The compiler refuses. Not because the data is shaped wrong, but because the meaning is wrong. CustomerId is not ShopId, even though both wrap a String underneath. NetAmount is not Amount, even though both wrap an i64.

Go:

type ShopID string
type CustomerID string
type OrderID string
type Amount int64
type PlatformFee int64
type TxFee int64
type NetAmount int64

type OrderPayoutParams struct {
    ShopID      ShopID
    CustomerID  CustomerID
    OrderID     OrderID
    Amount      Amount
    PlatformFee PlatformFee
    TxFee       TxFee
    NetAmount   NetAmount
}

func ProcessOrderPayout(params OrderPayoutParams) error {
    // ...
}

Go’s type definitions are not aliases. ShopID and CustomerID are distinct types. Passing one where the other is expected is a compile-time error. Same for Amount vs NetAmount vs PlatformFee.

TypeScript:

type ShopId = string & { readonly __brand: "ShopId" };
type CustomerId = string & { readonly __brand: "CustomerId" };
type OrderId = string & { readonly __brand: "OrderId" };
type Amount = number & { readonly __brand: "Amount" };
type PlatformFee = number & { readonly __brand: "PlatformFee" };
type TxFee = number & { readonly __brand: "TxFee" };
type NetAmount = number & { readonly __brand: "NetAmount" };

interface OrderPayoutParams {
  shopId: ShopId;
  customerId: CustomerId;
  orderId: OrderId;
  amount: Amount;
  platformFee: PlatformFee;
  txFee: TxFee;
  netAmount: NetAmount;
}

function processOrderPayout(params: OrderPayoutParams) {
  // ...
}

TypeScript doesn’t have native newtype wrappers, so we use branded types. It’s a well-established pattern that adds a phantom property to prevent accidental interchange. A small amount of ceremony that pays for itself immediately.

Living With Newtypes

The first thing people ask when they see this is “okay but now I can’t do anything with my data.” That’s fair. A ShopId(String) doesn’t have .len() or .contains() or any of the methods you’re used to calling on String. You’d have to write shop_id.0.len() everywhere, and that’s ugly.

This is where Deref comes in. In Rust, you can implement Deref to let your newtype transparently expose the inner type’s methods:

use std::ops::Deref;

struct ShopId(String);

impl Deref for ShopId {
    type Target = String;

    fn deref(&self) -> &String {
        &self.0
    }
}

let shop = ShopId("shop_abc123".to_string());
println!("{}", shop.len());        // works, delegates to String::len()
println!("{}", shop.to_uppercase()); // works too

You get full access to all String methods without unwrapping. But the type system still prevents you from passing a ShopId where a CustomerId is expected. Best of both worlds.

You’ll also want Display and From so your types play nicely with the rest of your code:

use std::fmt;

impl fmt::Display for ShopId {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl From<String> for ShopId {
    fn from(s: String) -> Self {
        ShopId(s)
    }
}

// Now you can do:
let shop: ShopId = "shop_abc123".to_string().into();
println!("Processing payout for {shop}");

And here’s where it gets really powerful. You can add validation directly in the constructor, so invalid data can never become a ShopId in the first place:

impl ShopId {
    pub fn new(id: String) -> Result<Self, String> {
        if id.is_empty() {
            return Err("Shop ID cannot be empty".into());
        }
        if !id.starts_with("shop_") {
            return Err("Shop ID must start with 'shop_'".into());
        }
        Ok(ShopId(id))
    }
}

Once a ShopId exists in your system, you know it’s valid. Every function that receives a ShopId can skip validation entirely. The constructor already did the work.

In Go, defined types start with an empty method set, but built-in operations like len() still work and you can add your own methods:

type ShopID string

id := ShopID("shop_abc123")
fmt.Println(len(id)) // works, len() is a built-in function

// Add your own methods
func (id ShopID) Validate() error {
    if id == "" {
        return errors.New("shop ID cannot be empty")
    }
    return nil
}

In TypeScript, branded types are just structural, so all string or number operations work without any extra code. The brand only exists at compile time.

What You Actually Gain

This isn’t just about catching swapped arguments. It changes how you think about your code.

Self-documenting code. When a function takes ShopId instead of String, you don’t need a doc comment explaining what that parameter is. The type is the documentation.

Refactoring confidence. When you rename a field or change a data flow, the compiler traces every usage of that type across your entire codebase. Nothing slips through.

Validation at the boundary. When you construct a ShopId, you can enforce invariants: must be a valid ObjectID format, can’t be empty, must exist in the database. Every ShopId in your system is guaranteed valid. Not because every function checks, but because the constructor checked once and the type system carries that guarantee forward.

Grep-ability. Searching for ShopId in your codebase shows you every place a shop identifier is created, passed, stored, or transformed. Searching for String shows you everything.

Security. A RawUserInput type that must be explicitly converted to SanitizedHtml before rendering? That’s injection prevention enforced by the compiler, not by code review discipline.

The Cost Is Lower Than You Think

The most common objection is ceremony. “I don’t want to wrap every string in a newtype.” But think about the alternative: you’re trusting that every developer on your team, across every PR, in every late-night hotfix, will correctly match unnamed strings to their intended purpose. That’s not engineering. That’s hope.

The wrapper types are typically two to five lines each. You write them once. The compiler enforces them forever.

Scalar types describe what data looks like. A sequence of characters, a 64-bit integer, a boolean flag. Domain types describe what data means. A title, a price in USD, a sanitized HTML fragment, a user ID.

The gap between these two is where bugs live. I learned that the hard way. Wrap your primitives. Make your types mean something. Let the compiler do the work that code review and testing never will.

—Samuel

If you want a very different kind of type-and-layout experiment, I also wrote about building an inode-style vector in Rust and benchmarking where it loses to Vec.

Edits:

• 2026-04-15: Corrected Go section on defined types and method sets based on readers feedback.

On Khoomi, a single cart can contain items from different sellers. At checkout, that becomes one payment but multiple fulfillment flows. Shop A might ship tomorrow while Shop B takes a week. The order system needs to handle this gracefully.

The Parent-Child Model

An order has embedded shop orders. One document, multiple fulfillment units:

type Order struct {
    ID            primitive.ObjectID `bson:"_id"`
    OrderNumber   string             `bson:"order_number"`
    CustomerID    primitive.ObjectID `bson:"customer_id"`
    CustomerEmail string             `bson:"customer_email"`

    ShopOrders []ShopOrder `bson:"shop_orders"` // Embedded

    Pricing         OrderPricing       `bson:"pricing"`
    ShippingAddress UserAddressExcerpt `bson:"shipping_address"`

    Status        OrderStatus `bson:"status"`        // Overall
    PaymentStatus string      `bson:"payment_status"`

    CreatedAt   time.Time  `bson:"created_at"`
    PaidAt      *time.Time `bson:"paid_at,omitempty"`
    CancelledAt *time.Time `bson:"cancelled_at,omitempty"`
}

type ShopOrder struct {
    OrderID         primitive.ObjectID `bson:"order_id"`
    ShopID          primitive.ObjectID `bson:"shop_id"`
    ShopName        string             `bson:"shop_name"`
    Items           []OrderItem        `bson:"items"`

    Subtotal     int64 `bson:"subtotal"`      // in kobo
    ShippingCost int64 `bson:"shipping_cost"` // in kobo
    ShopTotal    int64 `bson:"shop_total"`    // in kobo

    ShopOrderStatus OrderStatus `bson:"shop_order_status"` // Independent
    TrackingNumber  string      `bson:"tracking_number,omitempty"`

    SellerPayout SellerPayout      `bson:"seller_payout"`
    Refund       *ShopOrderRefund  `bson:"refund,omitempty"` // Created on cancellation
}

The parent Order tracks payment. Each ShopOrder tracks its own fulfillment. For an example, Shop A marking their portion as shipped doesn’t affect Shop B's status(stays as “processing.”, “paid” or whatever status it is)

Why embed instead of separate collections? Atomic reads. Fetching an order for display is one query, not a join. The customer sees everything at once: their items, each shop’s status, the overall payment state.

The trade-off? Updating a single shop’s status requires updating the entire order document. MongoDB’s positional operator ($[elem]) handles this efficiently, but it’s still a larger write than updating a separate document.

Atomic Checkout

Creating an order touches multiple collections. Inventory must be reserved. The cart must be cleared. The order must be inserted. All or nothing:

func (s *orderService) CreateOrderFromCart(ctx context.Context, userID ObjectID, req CreateOrderRequest) (*Order, error) {
    // Build order from cart items (grouping by shop)
    order := buildOrderFromCart(...)

    callback := func(sessCtx mongo.SessionContext) (any, error) {
        // Reserve inventory for each item
        for _, shop := range order.ShopOrders {
            for _, item := range shop.Items {
                filter := bson.M{
                    "_id":                item.ListingID,
                    "inventory.quantity": bson.M{"$gte": item.Quantity},
                }
                update := bson.M{
                    "$inc": bson.M{"inventory.quantity": -item.Quantity},
                }

                result, err := listingColl.UpdateOne(sessCtx, filter, update)
                if err != nil {
                    return nil, err
                }
                if result.ModifiedCount == 0 {
                    return nil, fmt.Errorf("insufficient inventory for '%s'", item.Title)
                }
            }
        }

        _, err := orderColl.InsertOne(sessCtx, order)
        if err != nil {
            return nil, err
        }

        _, err = s.cart.ClearCartItems(sessCtx, userID)
        if err != nil {
            return nil, err
        }

        return order, nil
    }

    result, err := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
    if err != nil {
        return nil, err
    }

    return result.(*Order), nil
}

The filter "inventory.quantity": bson.M{"$gte": item.Quantity} is critical. It ensures stock exists before decrementing. If two customers checkout simultaneously and only one item remains, exactly one succeeds. The other gets a clear error.

Why reserve at checkout instead of cart add? I covered this decision in Week 1. The short version: carts are abandoned constantly, and reserving at checkout avoids expiry logic and hold timers.

Independent Fulfillment

Each shop order has its own lifecycle:

PENDING → PAID → PROCESSING → SHIPPED → DELIVERED
                                ↓
                            CANCELLED

When a shop updates their status, only the order belonging to their shop gets updated:

func (s *orderService) UpdateShopOrderStatus(ctx context.Context, params UpdateShopOrderParams) error {
    filter := bson.M{
        "_id":                 params.OrderID,
        "shop_orders.shop_id": params.ShopID,
    }

    update := bson.M{
        "$set": bson.M{
            "shop_orders.$.shop_order_status": params.Status,
            "updated_at":                      time.Now(),
        },
    }

    if params.Status == OrderStatusShipped {
        update["$set"].(bson.M)["shop_orders.$.shipped_at"] = time.Now()
    }

    callback := func(sessCtx mongo.SessionContext) (any, error) {
        _, err := s.db.Coll.Orders.FindOneAndUpdate(sessCtx, filter, update).Decode(&order)
        if err != nil {
            return nil, err
        }

        // On delivery, release earnings to seller
        if params.Status == OrderStatusDelivered {
            err := s.wallet.ReleaseEarnings(sessCtx, params.ShopID, params.OrderID)
            if err != nil {
                return nil, err
            }
        }

        return nil, nil
    }

    _, err := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
    return err
}

The shop_orders.$ positional operator updates only the matching shop order within the parent document.

Why not separate order documents per shop? The customer paid once. They expect one order number, one receipt, one tracking page. If I split orders into separate documents per shop, I’d need to reassemble them for every customer-facing view. Extra queries, extra complexity.

Escrow via Wallet

Sellers don’t get paid immediately. The money sits in escrow until delivery:

// Package wallet manages seller earnings on Khoomi.
//
// The wallet has two balances:
//   - Pending: from orders not yet delivered (cannot withdraw)
//   - Available: from delivered orders (can withdraw)
//
// Money Flow:
//  1. CreditPending: Payment received -> +pending, +total_earnings
//  2. ReleaseEarnings: Order delivered -> -pending, +available
//  3. ProcessWithdrawal: Seller withdraws -> -available, +total_withdrawn

When payment succeeds, the seller’s pending balance increases:

func (s *walletService) CreditPendingBalance(ctx context.Context, shopID, orderID ObjectID, amount int64) error {
    callback := func(sessCtx mongo.SessionContext) (any, error) {
        // Check idempotency - already credited for this order?
        count, _ := s.db.Coll.WalletTransactions.CountDocuments(sessCtx, bson.M{
            "shop_id":  shopID,
            "order_id": orderID,
            "type":     TxTypeOrderEarning,
        })
        if count > 0 {
             // Already credited
            return nil, nil
        }

        tx := WalletTransaction{
            ShopID:  shopID,
            Type:    TxTypeOrderEarning,
            Amount:  amount,
            OrderID: &orderID,
            // ...
        }
        _, err := s.db.Coll.WalletTransactions.InsertOne(sessCtx, tx)
        if err != nil {
            return nil, err
        }

        update := bson.M{
            "$inc": bson.M{
                "pending_balance": amount,
                "total_earnings":  amount,
            },
        }
        _, err = s.db.Coll.Wallets.UpdateOne(sessCtx, bson.M{"shop_id": shopID}, update)
        return nil, err
    }

    _, err := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
    return err
}

When the order is delivered, pending becomes available:

func (s *walletService) ReleaseEarnings(ctx context.Context, shopID, orderID ObjectID) error {
    callback := func(sessCtx mongo.SessionContext) (any, error) {
        // Find the pending transaction
        var pendingTx WalletTransaction
        err := s.db.Coll.WalletTransactions.FindOne(sessCtx, bson.M{
            "shop_id":  shopID,
            "order_id": orderID,
            "type":     TxTypeOrderEarning,
        }).Decode(&pendingTx)
        if err != nil {
            return nil, ErrPendingEarningsNotFound
        }

        amount := pendingTx.Amount

        releaseTx := WalletTransaction{
            ShopID:      shopID,
            Type:        TxTypeEarningReleased,
            Amount:      amount,
            OrderID:     &orderID,
            Description: "Earnings released - order delivered",
        }
        _, err = s.db.Coll.WalletTransactions.InsertOne(sessCtx, releaseTx)
        if err != nil {
            return nil, err
        }

        // Move from pending to available
        walletUpdate := bson.M{
            "$inc": bson.M{
                "pending_balance":   -amount,
                "available_balance": amount,
            },
        }
        _, err = s.db.Coll.Wallets.UpdateOne(sessCtx, bson.M{"shop_id": shopID}, walletUpdate)
        return nil, err
    }

    _, err := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
    return err
}

Why escrow? Buyer protection. If a seller never ships or order status is “paid”, the money can be refunded. If the item arrives damaged, there’s a dispute window before the seller can withdraw.

The trade-off? Sellers wait for their money. Cash flow suffers. But for a marketplace with unknown sellers, trust requires holding funds until delivery is confirmed.

Partial Cancellation

One shop can cancel their order without affecting others:

func (s *orderService) CancelOrderByShop(ctx context.Context, orderID, shopID ObjectID, reason string) error {
    order, _ := s.GetOrderByID(ctx, orderID)

    // Find this shop's order
    var shopOrder *ShopOrder
    for i := range order.ShopOrders {
        if order.ShopOrders[i].ShopID == shopID {
            shopOrder = &order.ShopOrders[i]
            break
        }
    }

    needsRefund := order.Status == OrderStatusPaid || order.Status == OrderStatusProcessing

    callback := func(sessCtx mongo.SessionContext) (any, error) {
        updateFields := bson.M{
            "shop_orders.$[elem].shop_order_status": OrderStatusCancelled,
            "shop_orders.$[elem].updated_at":        time.Now(),
        }

        // Create refund record if order was paid
        if needsRefund {
            refund := ShopOrderRefund{
                Status:      RefundStatusPending,
                Amount:      shopOrder.ShopTotal,
                InitiatedBy: RefundByShop,
                Reason:      reason,
                RequestedAt: time.Now(),
                RetryCount:  0,
            }
            updateFields["shop_orders.$[elem].refund"] = refund
        }

        update := bson.M{"$set": updateFields}
        arrayFilters := options.Update().SetArrayFilters(options.ArrayFilters{
            Filters: []any{bson.M{"elem.shop_id": shopID}},
        })

        _, err := s.db.Coll.Orders.UpdateOne(sessCtx, bson.M{"_id": orderID}, update, arrayFilters)
        if err != nil {
            return nil, err
        }

        // Restore inventory
        for _, item := range shopOrder.Items {
            inventoryUpdate := bson.M{
                "$inc": bson.M{"inventory.quantity": item.Quantity},
            }
            _, _ = s.db.Coll.Listings.UpdateOne(sessCtx, bson.M{"_id": item.ListingID}, inventoryUpdate)
        }

        // Check if ALL shops are now cancelled
        updatedOrder, _ := s.GetOrderByID(sessCtx, orderID)
        allCancelled := true
        for _, so := range updatedOrder.ShopOrders {
            if so.ShopOrderStatus != OrderStatusCancelled {
                allCancelled = false
                break
            }
        }

        // If all cancelled, cancel the whole order
        if allCancelled {
            mainUpdate := bson.M{
                "$set": bson.M{
                    "status":         OrderStatusCancelled,
                    "payment_status": "refund_pending",
                    "cancelled_at":   time.Now(),
                },
            }
            _, err = s.db.Coll.Orders.UpdateOne(sessCtx, bson.M{"_id": orderID}, mainUpdate)
        }

        return nil, err
    }

    _, err := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
    return err
}

The $[elem] array filter lets me target a specific shop order by its shop_id. If Shop A cancels but Shop B is still fulfilling, the parent order stays active. Only Shop A’s portion shows as cancelled.

Why allow partial cancellation? Stock issues happen. A seller might realize they can’t fulfill an item after accepting the order. Cancelling the entire order (including items from other shops that are ready to ship) would punish buyers and other sellers for one shop’s mistake.

When a paid order is cancelled, it also creates a refund record:

type ShopOrderRefund struct {
    Status        RefundStatus    `bson:"status"`         // pending/processing/completed/failed
    Amount        int64           `bson:"amount"`         // in kobo
    InitiatedBy   RefundInitiator `bson:"initiated_by"`   // customer/shop/system
    Reason        string          `bson:"reason,omitempty"`
    RequestedAt   time.Time       `bson:"requested_at"`
    ProcessedAt   *time.Time      `bson:"processed_at,omitempty"`
    CompletedAt   *time.Time      `bson:"completed_at,omitempty"`
    Reference     string          `bson:"reference,omitempty"`
    FailureReason string          `bson:"failure_reason,omitempty"`
    RetryCount    int             `bson:"retry_count"`
    LastRetryAt   *time.Time      `bson:"last_retry_at,omitempty"`
}

The refund starts as pending. A background job picks it up.

Automated Refund Processing

Refunds run on a scheduler, not inline with cancellation:

func (j *RefundsJob) Run(ctx context.Context) {
    orders, _ := j.orderService.GetPendingRefunds(ctx)

    for _, order := range orders {
        for _, shopOrder := range order.ShopOrders {
            if shopOrder.Refund == nil || shopOrder.Refund.Status != RefundStatusPending {
                continue
            }

            // Max 5 retries before marking as failed
            if shopOrder.Refund.RetryCount >= MaxRefundRetries {
                j.orderService.MarkRefundAsFailed(ctx, order.ID, shopOrder.ShopID,
                    "Maximum retry attempts exceeded")
                continue
            }

            j.orderService.ProcessShopOrderRefund(ctx, order.ID, shopOrder.ShopID)
        }
    }
}

Why async? Payment provider APIs fail. Network timeouts happen. If I processed refunds inline with cancellation, a Paystack outage would block the entire cancellation flow. With a scheduler, the cancellation succeeds immediately. The customer sees “cancelled” right away, and the actual money movement retries in the background until it works.

Processing a refund deducts from the seller’s pending balance:

func (s *orderService) ProcessShopOrderRefund(ctx context.Context, orderID, shopID ObjectID) error {
    // Mark as processing (with retry count increment)
    updateProcessing := bson.M{
        "$set": bson.M{
            "shop_orders.$.refund.status":       RefundStatusProcessing,
            "shop_orders.$.refund.processed_at": time.Now(),
        },
        "$inc": bson.M{
            "shop_orders.$.refund.retry_count": 1,
        },
    }
    s.db.Coll.Orders.UpdateOne(ctx, filter, updateProcessing)

    // Deduct from seller wallet
    err := s.wallet.DeductForRefund(ctx, shopID, orderID, shopOrder.Refund.Amount)
    if err != nil {
        // Revert to pending for retry
        revertUpdate := bson.M{
            "$set": bson.M{
                "shop_orders.$.refund.status":         RefundStatusPending,
                "shop_orders.$.refund.failure_reason": fmt.Sprintf("Wallet deduction failed: %v", err),
            },
        }
        s.db.Coll.Orders.UpdateOne(ctx, ...)
        return err
    }

    completeUpdate := bson.M{
        "$set": bson.M{
            "shop_orders.$.refund.status":       RefundStatusCompleted,
            "shop_orders.$.refund.completed_at": time.Now(),
        },
    }
    s.db.Coll.Orders.UpdateOne(ctx, ...)
    return nil
}

The wallet deduction reverses the original credit:

func (s *walletService) DeductForRefund(ctx context.Context, shopID, orderID ObjectID, amount int64) error {
    callback := func(sessCtx mongo.SessionContext) (any, error) {
        // Idempotency check
        count, _ := s.db.Coll.WalletTransactions.CountDocuments(sessCtx, bson.M{
            "shop_id":  shopID,
            "order_id": orderID,
            "type":     TxTypeRefundDeduction,
        })
        if count > 0 {
            return nil, ErrRefundAlreadyProcessed
        }

        // Verify sufficient pending balance
        var w SellerWallet
        s.db.Coll.Wallets.FindOne(sessCtx, bson.M{"shop_id": shopID}).Decode(&w)
        if w.PendingBalance < amount {
            return nil, ErrInsufficientPendingBalance
        }

        tx := WalletTransaction{
            ShopID:      shopID,
            Type:        TxTypeRefundDeduction,
            Amount:      amount,
            OrderID:     &orderID,
            Description: "Refund deduction for cancelled order",
        }
        s.db.Coll.WalletTransactions.InsertOne(sessCtx, tx)

        // Deduct from pending and total earnings
        walletUpdate := bson.M{
            "$inc": bson.M{
                "pending_balance": -amount,
                "total_earnings":  -amount,
            },
        }
        s.db.Coll.Wallets.UpdateOne(sessCtx, bson.M{"shop_id": shopID}, walletUpdate)
        return nil, nil
    }

    _, err := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
    return err
}

The refund deducts from both pending_balance and total_earnings. The seller never actually earned this money. It’s going back to the customer.

The trade-off? If the seller somehow withdrew before delivery (which shouldn’t happen, since pending balance can’t be withdrawn), the deduction fails. After 5 retries, the refund is marked as failed, and I get an alert to handle it manually.

Cleanup Expired Orders

Pending orders that never get paid should release their inventory:

func (s *orderService) CleanupExpiredPendingOrders(ctx context.Context, expirationHours int) (int64, error) {
    expiredTime := time.Now().Add(-time.Duration(expirationHours) * time.Hour)

    filter := bson.M{
        "status":     OrderStatusPending,
        "created_at": bson.M{"$lt": expiredTime},
    }

    cursor, _ := s.db.Coll.Orders.Find(ctx, filter)
    var expiredOrders []Order
    cursor.All(ctx, &expiredOrders)

    var cleanedCount int64
    for _, order := range expiredOrders {
        callback := func(sessCtx mongo.SessionContext) (any, error) {
            // Cancel the order
            update := bson.M{
                "$set": bson.M{
                    "status":                            OrderStatusCancelled,
                    "payment_status":                    "expired",
                    "internal_note":                     fmt.Sprintf("Auto-cancelled: Payment not received within %d hours", expirationHours),
                    "shop_orders.$[].shop_order_status": OrderStatusCancelled,
                },
            }
            result, err := s.db.Coll.Orders.UpdateOne(sessCtx,
                bson.M{"_id": order.ID, "status": OrderStatusPending}, update)
            if result.ModifiedCount == 0 {
                // Already processed
                return nil, nil 
            }

            // Restore all inventory
            for _, shop := range order.ShopOrders {
                for _, item := range shop.Items {
                    inventoryUpdate := bson.M{
                        "$inc": bson.M{"inventory.quantity": item.Quantity},
                    }
                    _, _ = s.db.Coll.Listings.UpdateOne(sessCtx, bson.M{"_id": item.ListingID}, inventoryUpdate)
                }
            }

            return result.ModifiedCount, nil
        }

        result, _ := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
        if count, ok := result.(int64); ok {
            cleanedCount += count
        }
    }

    return cleanedCount, nil
}

This runs as a background job every 24 hours. That window gives customers enough time to complete bank transfers (which can take hours in Nigeria), but not long enough to hold inventory hostage indefinitely.

The double-check filter "status": OrderStatusPending in the update ensures idempotency. If payment came through between the find and update, the order won’t be cancelled. The filter simply won’t match.

Seller Payout Calculation

Each shop order tracks exactly what the seller receives:

type SellerPayout struct {
    Amount         int64 `bson:"amount"`          // Customer paid (kobo)
    PlatformFee    int64 `bson:"platform_fee"`    // Khoomi's cut (kobo)
    TransactionFee int64 `bson:"transaction_fee"` // Payment processor (kobo)
    NetAmount      int64 `bson:"net_amount"`      // Seller receives (kobo)
    PayoutStatus   string `bson:"payout_status"`
}

Calculated at checkout:

shopTotal := shopSubtotal + shippingCost + handlingFee - shopDiscount

platformFee := shopTotal * PLATFORM_FEE_RATE / PERCENT_DIVISOR / 100
transactionFee := shopTotal * TRANSACTION_FEE_RATE / PERCENT_DIVISOR / 100
netAmount := shopTotal - platformFee - transactionFee

shopOrder.SellerPayout = SellerPayout{
    Amount:         shopTotal,
    PlatformFee:    platformFee,
    TransactionFee: transactionFee,
    NetAmount:      netAmount,
    PayoutStatus:   "pending",
}

Why calculate at checkout instead of delivery? Transparency. When a seller views an incoming order, they see exactly what they’ll receive. No surprises when withdrawal time comes. “You’ll get ₦54,000 from this ₦60,000 order” is clear.

The trade-off? Fee changes don’t apply retroactively. If I lower the platform fee tomorrow, orders placed today still use today’s rate. For accounting consistency, that’s actually what I want.

What I’d Do Differently

The parent order status. Currently Order.Status is supposed to be the “overall” status, but what does “processing” mean when Shop A is shipped and Shop B is still packing? I should probably derive it from shop order statuses instead of storing it separately. Or at least define clearer rules for when the parent status changes.

Refund status visibility. Refund status lives inside ShopOrder.Refund. That’s fine for displaying a single order, but when customer support asks “show me all failed refunds this week,” I have to scan every order document. A separate refunds collection with proper indexing would make those queries instant.

The Pattern

Same as previous weeks: optimize for the common case.

• Most orders have 1-2 shops → embed, don’t normalize
• Most checkouts succeed → reserve at checkout, not cart add
• Most shops fulfill successfully → escrow by default, release on delivery
• Most cancellations are partial → per-shop status, not all-or-nothing
• Most refunds succeed on first try → async processing with retry, not inline

The multi-vendor order system handles the 90% case elegantly. The 10% (complex disputes, multi-shop returns, refunds that fail after 5 retries) requires me to step in manually. At Khoomi’s current scale, that’s maybe one or two cases a week. Acceptable.

Next week: Wallets and seller withdrawals.

—Samuel

On Khoomi, a shop is a seller’s storefront—distinct from the user account that handles authentication. This separation lets the same person buy (via their user account) and sell (via their shop) while keeping concerns cleanly separated.

One User, One Shop

Every user can own exactly one shop. This constraint is intentional:

type Shop struct {
    ID                 primitive.ObjectID `bson:"_id"`
    UserID             primitive.ObjectID `bson:"user_id"`  // Owner
    Name               string             `bson:"name"`
    Username           string             `bson:"username"` // Unique handle
    Status             ShopStatus         `bson:"status"`
    ListingActiveCount int64              `bson:"listing_active_count"`
    FollowerCount      int                `bson:"follower_count"`
    Rating             Rating             `bson:"rating"`
    // ...
}

Why one-to-one? Earnings are unambiguously credited. Tax reporting is straightforward. Sellers focus on building a single strong brand rather than fragmenting their efforts across multiple storefronts.

The trade-off? Users who genuinely need multiple shops (say, one for jewelry and one for clothing) must create separate accounts. For Khoomi’s target market—individual artisans—this rarely comes up. Large multi-brand sellers would need a different architecture.

Atomic Shop Creation

Creating a shop touches four collections in one transaction:

func (s *ShopServiceImpl) CreateShop(ctx context.Context, req CreateShopRequest, ownerID ObjectID) (ObjectID, error) {
    shopID := primitive.NewObjectID()

    callback := func(ctx mongo.SessionContext) (any, error) {
        // 1. Insert the shop
        _, err := s.db.Coll.Shops.InsertOne(ctx, shop)
        if err != nil {
            return primitive.NilObjectID, err
        }

        // 2. Update user to seller status
        _, err = s.db.Coll.Users.UpdateOne(ctx,
            bson.M{"_id": ownerID},
            bson.M{"$set": bson.M{
                "is_seller":              true,
                "seller_onboarding_level": OnboardingLevelCreatedShop,
                "shop_id":                shopID,
            }})
        if err != nil {
            return primitive.NilObjectID, err
        }

        // 3. Create notification settings
        _, err = s.CreateShopNotificationSettings(ctx, shopID)
        if err != nil {
            return primitive.NilObjectID, err
        }

        // 4. Create wallet for earnings
        _, err = s.wallet.CreateWallet(ctx, shopID, ownerID)
        if err != nil {
            return primitive.NilObjectID, err
        }

        return shopID, nil
    }

    _, err := database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
    return shopID, err
}

Four operations, one transaction. If the wallet creation fails, the user update rolls back. If the notification settings fail, the shop insert rolls back. No half-created sellers.

Why a transaction instead of eventual consistency? A user with is_seller: true but no shop would break the dashboard. A shop without a wallet can’t receive payments. These invariants must hold at all times.

The trade-off? MongoDB transactions require replica sets. Single-node development setups need extra configuration. And transactions are slower than individual writes. For shop creation (once per seller, ever), the latency is acceptable.

Shop Status Lifecycle

Shops progress through statuses that control visibility and capabilities:

const (
    ShopStatusInactive      = "inactive"      // Just created, not visible
    ShopStatusActive        = "active"        // Fully operational
    ShopStatusPendingReview = "pendingreview" // Flagged for moderation
    ShopStatusWarning       = "warning"       // Minor violation confirmed
    ShopStatusSuspended     = "suspended"     // Temporarily disabled
    ShopStatusBanned        = "banned"        // Permanently removed
)

The state machine:

INACTIVE → ACTIVE → PENDING_REVIEW → WARNING → BANNED
                 \→ SUSPENDED

Most shops stay active forever. inactive gives sellers time to configure branding before going live. pendingreview lets moderation investigate without immediately punishing. suspended is reversible; banned is terminal.

Why not just active and banned? Nuance. A shop selling knockoffs needs immediate suspension. A shop with unclear product descriptions needs a warning, not a ban. The intermediate states let us match response to severity.

Embedded Followers (Bounded)

The shop document embeds the 5 most recent followers:

type Shop struct {
    // ...
    Followers     []ShopFollower `bson:"followers"`     // Embedded (max 5)
    FollowerCount int            `bson:"follower_count"`
}

When someone follows a shop:

func (s *ShopServiceImpl) FollowShop(ctx context.Context, userID, shopID ObjectID) (ObjectID, error) {
    callback := func(ctx mongo.SessionContext) (any, error) {
        // Insert into followers collection (full list)
        _, err := s.db.Coll.ShopFollowers.InsertOne(ctx, followerData)
        if err != nil {
            if mongo.IsDuplicateKeyError(err) {
                return nil, errors.New("already following this shop")
            }
            return nil, err
        }

        // Update shop with bounded embedded array
        update := bson.M{
            "$push": bson.M{
                "followers": bson.M{
                    "$each":     bson.A{followerExcerpt},
                    "$sort":     bson.M{"joined_at": -1},
                    "$slice":    5,        // Keep only 5
                    "$position": 0,        // Prepend (newest first)
                },
            },
            "$inc": bson.M{"follower_count": 1},
        }
        _, err = s.db.Coll.Shops.UpdateOne(ctx, bson.M{"_id": shopID}, update)
        return followerID, err
    }

    return database.ExecuteTransaction(ctx, s.db.MongoClient, callback)
}

The $slice: 5 operator caps the embedded array. The full follower list lives in shop_followers collection for pagination.

Why embed at all? The shop profile page shows “recent followers” without a join. One document fetch, one render. For a shop with 10,000 followers, loading the full list would be wasteful when we only display 5.

The trade-off? Two writes per follow (collection + embedded). The embedded data can drift if updates fail partially—though the transaction prevents this. And we’re duplicating data. For 5 followers × ~100 bytes each, the duplication is negligible.

Shipping Profiles

Each shop can have multiple shipping profiles:

type ShopShippingProfile struct {
    ID              ObjectID `bson:"_id"`
    ShopID          ObjectID `bson:"shop_id"`
    Title           string   `bson:"title"`           // "Standard Shipping"
    OriginState     string   `bson:"origin_state"`    // "Lagos"
    PrimaryPrice    int64    `bson:"primary_price"`   // Same zone (kobo)
    SecondaryPrice  int64    `bson:"secondary_price"` // Different zone (kobo)
    MinDeliveryDays int      `bson:"min_delivery_days"`
    MaxDeliveryDays int      `bson:"max_delivery_days"`
    IsDefault       bool     `bson:"is_default"`
    AcceptReturns   bool     `bson:"accept_returns"`
    ReturnPeriod    int      `bson:"return_period"`   // Days
}

The dual pricing (PrimaryPrice vs SecondaryPrice) reflects Nigerian geography. Shipping within Lagos is cheaper than shipping from Lagos to Benue. Rather than model all 36 states individually, I use two tiers: same zone vs different zone.

Why not per-state pricing? Complexity. Most sellers ship from one location. Two tiers cover 90% of cases. A jewelry maker in Lagos charges ₦1,500 for Lagos delivery, ₦3,000 everywhere else. Good enough.

The trade-off? Sellers shipping to specific states (say, only Southwest Nigeria) need workarounds. The Destinations field exists for this, but most sellers just use “everywhere.”

Dashboard Notification Counts

The seller dashboard needs multiple counts: unread messages, new orders, pending refunds, low stock items. Six queries total. Running them sequentially would be slow.

Instead, parallel goroutines with channels:

func (s *ShopServiceImpl) GetShopNotificationCount(ctx context.Context, shopID ObjectID) (*ShopNotificationCount, error) {
    result := &ShopNotificationCount{}
    resultChan := make(chan countResult, 6)

    // 1. Unread messages
    go func() {
        count := s.countUnreadMessages(ctx, shopID)
        resultChan <- countResult{"unread_messages", count, nil}
    }()

    // 2. New orders (pending or paid)
    go func() {
        count := s.countNewOrders(ctx, shopID)
        resultChan <- countResult{"new_orders", count, nil}
    }()

    // 3. Pending refunds
    go func() {
        count, _ := s.db.Coll.RefundRequests.CountDocuments(ctx,
            bson.M{"shop_id": shopID, "status": "pending"})
        resultChan <- countResult{"pending_refunds", count, nil}
    }()

    // 4. Low stock items (inventory <= 5)
    go func() {
        count, _ := s.db.Coll.Listings.CountDocuments(ctx, bson.M{
            "shop_id":            shopID,
            "state.state":        ListingStateActive,
            "inventory.quantity": bson.M{"$lte": 5, "$gt": 0},
        })
        resultChan <- countResult{"low_stock_items", count, nil}
    }()

    // 5. Expiring listings (within 7 days)
    go func() {
        sevenDaysFromNow := time.Now().AddDate(0, 0, 7)
        count, _ := s.db.Coll.Listings.CountDocuments(ctx, bson.M{
            "shop_id":     shopID,
            "state.state": ListingStateActive,
            "expires_at":  bson.M{"$lte": sevenDaysFromNow},
        })
        resultChan <- countResult{"expiring_listings", count, nil}
    }()

    // 6. Unread notifications
    go func() {
        count, _ := s.db.Coll.ShopNotifications.CountDocuments(ctx,
            bson.M{"recipient_id": shopID, "is_read": false})
        resultChan <- countResult{"unread_notifications", count, nil}
    }()

    // Collect results
    for i := 0; i < 6; i++ {
        r := <-resultChan
        switch r.field {
        case "unread_messages":
            result.UnreadMessages = r.count
        case "new_orders":
            result.NewOrders = r.count
        // ... etc
        }
    }

    return result, nil
}

Six queries run concurrently. Total latency is the slowest query, not the sum of all queries. On my test data, this drops dashboard load from ~600ms to ~150ms.

Why not cache these counts? They change constantly. An order comes in, the count increments. A message arrives, unread count changes. Caching would show stale data. For a seller checking their dashboard, accuracy matters more than the 150ms saved by caching.

Vacation Mode

Sellers can pause their shop without deleting anything:

type Shop struct {
    // ...
    IsVacation      bool   `bson:"is_vacation"`
    VacationMessage string `bson:"vacation_message"`
}

When IsVacation is true:

• Shop is hidden from search results
• Shop page shows the vacation message
• Existing orders continue processing
• Listings remain intact

Why a flag instead of a status? Vacation is orthogonal to status. An active shop can go on vacation. A shop under warning can also go on vacation. Mixing these into one field would create a combinatorial explosion: active_vacation, warning_vacation, etc.

The trade-off? Two fields to check instead of one. Queries for “visible shops” need status: active AND is_vacation: false. Minor complexity.

Shop Announcements

Sellers can post announcements that appear at the top of their shop page:

type Shop struct {
    // ...
    Announcement           string    `bson:"announcement"`
    AnnouncementModifiedAt time.Time `bson:"announcement_modified_at"`
}

Announcements are capped at 500 characters—enough for a sale notice or shipping delay warning, not enough for a newsletter. The AnnouncementModifiedAt timestamp lets the frontend show “Updated 2 days ago” without a separate query.

Why not a separate announcements collection with history? Overkill. Sellers update announcements infrequently. When they do, the old one doesn’t matter. A single field with a timestamp covers the use case.

What I’d Do Differently

The 5-follower embedding. It works, but it’s a magic number. If the design team wants to show 10 followers on the profile page, I need a migration. A configurable limit or a separate “recent followers” query might be more flexible.

The notification count queries. Six parallel queries is fast, but it’s still six round trips to MongoDB. A dedicated “shop stats” document updated via change streams would be faster. I’d pay for it with eventual consistency, but dashboard counts don’t need to be real-time accurate.

The Pattern

Same philosophy as listings: optimize for the common case.

• Most users own one shop → enforce 1:1, don’t build multi-shop support
• Most shop pages show few followers → embed 5, paginate the rest
• Most sellers ship two tiers → primary/secondary pricing, not per-state
• Most dashboard loads need all counts → parallelize, don’t waterfall

The shop architecture is stable. New features—analytics dashboards, promotional tools, bulk listing management—attach cleanly to the existing model.

Next: Week 3 - Multi-Vendor Order Architecture

—Samuel

I’ve been building Khoomi for 3.5 years now, a marketplace for Nigerian artisans and creatives. Nigeria’s e-commerce landscape has unique constraints: local payment rails, unreliable logistics, and infrastructure gaps that global platforms ignore. Along the way, I’ve made thousands of technical decisions, some smart, some I’m still fixing.

This series is where I share what I’ve learned: the actual code, the trade-offs, and what I’d do differently with hindsight.

Each week, I’ll cover one piece of the system: listings, wallets, shipping, payments, all of it. If you’re building something similar, or just curious how a marketplace actually works under the hood, this is for you.

Every marketplace lives or dies by how it handles listings. After 3.5 years developing Khoomi (MVP coming soon), I’ve made dozens of decisions about how listings work. Some were obvious. Most weren’t.

Here’s what I learned.

The Core Model

A listing in Khoomi is a single MongoDB document. One document = one product. This sounds obvious until you consider the alternatives.

type Listing struct {
    ID          primitive.ObjectID
    Code        string              // "ABCD-1234"
    Slug        string              // URL-friendly
    ShopID      primitive.ObjectID
    Title       string
    Description string
    Inventory   Inventory
    Variations  []Variation
    Details     ListingDetails      // Category-specific data
    State       ListingState
    Rating      Rating
    // ...
}

I chose embedded documents over references. A listing with 10 color variations stores all 10 in a single variations array, not in a separate variations collection.

Why? Atomic updates. When a customer buys “Large / Red”, I decrement that variation’s quantity in one database operation. No distributed transactions. No race conditions between collections.

The trade-off? MongoDB’s 16MB document limit caps me at roughly 5,000 variations per listing. For handmade goods, that’s never a problem.

Two Prices, Not One

Every variation can override the base price:

type Variation struct {
    ID       string
    Name     string   // "Size"
    Value    string   // "Large"
    Quantity int
    Price    *int64   // nil = use base price, 0 = free
}

The Price field is a pointer. If nil, inherit from inventory.price. If set, use the override.

This lets a seller price a leather bag at ₦15,000 for small and ₦18,000 for large without duplicating the entire listing. Simple idea, but the pointer-vs-value distinction matters. An explicit zero means free. A nil means “same as base.”

Stock Reservation: Later, Not Sooner

When should you reserve inventory? Two options:

1. Reserve on cart add — Item is “held” while in cart
2. Reserve on checkout — Item remains available until payment

I chose option 2.

Why? Carts are abandoned constantly. Reserving on cart add means expiry logic: “Release after 15 minutes of inactivity.” That creates edge cases. What if someone’s mid-checkout when the hold expires? What if they have unreliable internet?

Instead, multiple customers can cart the same item. At checkout, I verify and reserve atomically:

func (s *CheckoutService) ReserveStock(ctx context.Context, item CartItem) error {
    result, err := s.listings.UpdateOne(ctx,
        bson.M{
            "_id": item.ListingID,
            "variations": bson.M{
                "$elemMatch": bson.M{
                    "id":       item.VariationID,
                    "quantity": bson.M{"$gte": item.Quantity},
                },
            },
        },
        bson.M{
            "$inc": bson.M{
                "variations.$.quantity": -item.Quantity,
            },
        },
    )
    if result.MatchedCount == 0 {
        return ErrInsufficientStock
    }
    return err
}

The query filter ensures stock exists before decrementing. If someone else bought it first, the update matches nothing and checkout fails with a clear message.

The trade-off? Worse UX when items sell out while browsing. But that’s better than the alternative: customers whose “held” items vanish mid-checkout.

Expiration via Background Job

Listings expire after 30 days. I could check this on every read:

// Option A: Check on read
if listing.ExpiresAt.Before(time.Now()) {
    return ErrListingExpired
}

Instead, I run a daily job that bulk-updates expired listings:

// Option B: Background job
func (s *ListingService) MarkExpiredListings(ctx context.Context) error {
    _, err := s.collection.UpdateMany(ctx,
        bson.M{
            "state":      "active",
            "expires_at": bson.M{"$lt": time.Now()},
        },
        bson.M{"$set": bson.M{"state": "expired"}},
    )
    return err
}

Why? Reads are frequent. Writes are rare. Pushing expiration logic into reads adds latency to every listing view. A background job handles it once, in bulk, off the critical path.

The trade-off? A listing might display as “active” for up to 24 hours past its expiration.

For a marketplace selling handmade goods, that’s acceptable. For concert tickets, it wouldn’t be.

Polymorphic Category Data

Clothing needs size charts. Furniture needs dimensions. Jewelry needs materials. How do you model this?

I use a typed dynamic field:

type ListingDetails struct {
    Category      Category
    DynamicType   string                 // "clothing", "furniture"
    Dynamic       map[string]interface{} // Raw data
    ClothingData  *Clothing              // Typed struct
    FurnitureData *Furniture             // Typed struct
    // ...
}

The Dynamic map stores whatever the frontend sends. The typed struct (ClothingData, FurnitureData) is populated by parsing that map at runtime.

Why not separate collections per category? Because listings change categories. A seller might realize their “home decor” item belongs under “art”. With embedded polymorphic data, that’s a field update. With separate collections, it’s a migration.

The trade-off? I can’t index inside the dynamic fields. Searching “all listings with cotton fabric” requires application-level filtering, not a database index. For Khoomi’s scale, that’s fine. For Jumia, it wouldn’t be.

What I’d Do Differently

Slugs. I generate URL slugs from titles. When titles change, slugs don’t update automatically—to preserve existing links. This creates stale URLs over time. I should have made slugs immutable from day one, or built a redirect system earlier.

Analytics denormalization. I store views and favorers_count directly on the listing document for fast reads. But updating these counters on every view creates write contention. I’m now migrating to a separate analytics collection with periodic sync back to listings.

The Pattern

Most of these decisions follow a pattern: optimize for the common case, accept trade-offs for edge cases.

• Most listings have <20 variations → embed them
• Most carts are abandoned → don’t reserve stock early
• Most reads don’t need millisecond-accurate expiration → use background jobs
• Most category changes are rare → use polymorphic embedding

The key is knowing your domain. Khoomi sells handmade goods. Low volume per listing. High variety across listings. Patient buyers. These constraints shaped every decision.

Your marketplace might be different. That’s the point.

Next: Week 2 - Shop Architecture

—Samuel