Tales of BOSTales of BOS

Overview

Tales of BOS is a Christian fashion label, the 'BOS' standing for Believers of Shaddai. The clothes are meant to carry a story and still look good, and every collection has one attached to it. The founder was not willing to flatten that into a generic shop template. So the storefront is entirely hand-built: the collection pages, the product pages, the cart, the checkout. None of it came out of a box. Underneath it sits a proven commerce engine handling the parts where mistakes cost money, the stock counts, the orders and the refunds. That split is the whole design: build the brand, buy the machinery. The store is live and selling currently.

My role

Solo fullstack developer: the architecture and the decisions behind it, the entire hand-built storefront, the commerce backend and the security around it, the shared design system, the checkout and the money handling, search, email, SEO and analytics, and getting it running in production across two different environments. The design is mine as well. There was no separate designer on this one. The founder directly contracted me to build it, and I am now a fulltime IT director for the company, responsible for the platform and all other IT functions.

The problem

The brand needed a shop no template builder could express. Editorial, mobile-first, with each collection carrying its own faith story, plus gifting, personalisation and appointments. That pulls in two directions at once, and the tension is the interesting part. Building an entire shop by hand gets you the brand, but hand-built commerce is exactly where money and stock go wrong: two customers buying the last item, a refund returning slightly the wrong amount, a price that drifts when converted. Those bugs are quiet and expensive. Buying an off-the-shelf store gets you correctness, but not a brand anyone would remember. There was a third constraint too. The brand was launching lean in Nigeria, selling in naira, but expected to sell into the UK, Europe and the US later. Pricing across currencies is where online shops leak money without noticing, and it is very hard to retrofit.

The solution

The store was split in two. A proven commerce engine owns everything that must be correct: the cart, stock counts and reservations, orders, per-currency prices, tax and refunds. None of that was rewritten, because there is nothing to gain from rediscovering those bugs. Everything the customer actually sees was built from scratch on top of it. The collection pages with their stories, the product pages, the cart and a two-step checkout: all hand-built, none of it the engine's default interface. The brand's own ideas were added without altering the underlying system, by attaching information to things it already understood: the faith stories live on collections, gift curation on product tags, gift wrap and messages on the line item itself. That restraint is why upgrades stay possible. And money runs through one piece of code, storing amounts in whole kobo rather than as decimals, handling prices ending in .99 per currency, splitting refunds so the parts add back to exactly the whole, and never converting currency at the moment of paying.

Key features

• Browse collections that each tell their own story, on pages designed for the brand rather than assembled from a template.
• Choose a size and colour without being allowed to pick a combination that does not exist, then check out in two steps.
• Pay by card in naira, with VAT applied correctly, on a page where the card details never touch this server. If something fails after the money is taken, the order enters a holding state rather than risking a second charge.
• Create an account with an email address or a Google login, keep an address book, and look back over past orders, with an order only ever visible to the person who placed it.
• Filter the catalogue by department, collection, colour, size, price and availability, with the counts beside each option updating live, plus a search box that suggests as you type.
• Buy something as a gift: browse curated for-her and for-him edits, add gift wrap and a message, and have that message carry through to the order, the confirmation email and the packing instructions.
• Save things to a wishlist before signing in, and have it follow you into your account when you do.
• Read it comfortably in dark mode, which came from one change to the design system rather than being retrofitted screen by screen.

Architecture & engineering

A two-runtime headless topology. The storefront runs on Vercel (RSC + ISR/generateStaticParams, tag revalidation, an unstable_cache catalogue layer that degrades to empty instead of crashing when the backend is down), talking to a Medusa v2 backend self-hosted on a Hostinger VPS (Node 22 via nvm, pm2 running the compiled server, nginx reverse-proxy + certbot TLS at api.talesofbos.com). Data plane: Supabase Postgres via the IPv4 session pooler; Upstash Redis for cache + admin sessions only, with the event bus and workflow engine deliberately left in-memory after serverless Redis stalled Medusa's BullMQ modules on boot (documented as single-instance-correct). A Turborepo monorepo keeps the React-19 web workspace isolated from the React-18 Medusa workspace (separate lockfiles) to avoid dependency conflicts. A shared Money value object (integer minor units, banker's rounding, deterministic largest-remainder allocation for correct partial refunds) is the single money primitive; custom Medusa middleware adds order-ownership enforcement, metadata-tamper protection, and per-IP rate limiting.

The hardest problem

Every Paystack payment was failing in test: 7.5% VAT applied to .99 charm prices produced sub-kobo minor-unit totals (e.g. ₦196,187.4785) and Paystack rejects non-integer amounts. It was fixed durably with a pinned pnpm patch adding Math.round to the community provider, which then silently regressed in production because the standalone build drops patched dependencies, so the deploy script had to be taught to re-propagate patches before install. Separately, Medusa v2 OOM'd on 512MB tiers (it needs ~1-2GB), forcing a migration off the PaaS to a 7.8GB VPS with pm2 + nginx.

Results

Live and selling, with real customers placing real paid orders. The full checkout, from card payment through VAT to a branded confirmation email, runs end to end across multiple collections and products covering numerous variants, alongside Google sign-in. Built over about six weeks, with 23 architecture decisions written down as they were made, so the reasoning behind the unusual choices survives the person who made them. The build is delivered, and the work continues as the company grows its inventory and services and begins selling into more regions. That is the payoff for handling pricing and currency properly at the start rather than retrofitting it later.

Key learnings

Buying the commerce engine rather than building it bought correctness in exactly the places that matter, but the cost did not disappear. It moved into integration and operations: two systems to run instead of one, secrets and permissions to keep in step across both, and a payment provider written by the community rather than the vendor, which had to be proven in a sandbox before it could be trusted. Deciding early that all money would flow through one piece of code paid for itself. It caught a VAT calculation producing fractions of a kobo, and a scenario where a customer could be charged twice if the order failed after payment succeeded. Both would have shipped under ordinary decimal arithmetic and a trusting redirect. And building the design system around tokens rather than components turned dark mode into a single change to a set of variables, instead of a pass over roughly 43 components.