Hiya

Hiya is a single-store e-commerce platform — storefront, admin panel, and API — built for a general-goods shop in Tunisia selling in TND with cash on delivery.

Context and problem. The hard part of this project was never the catalogue; it was inventory. A mixed general-goods store sells items with colour and size, items with colour only, and items with no variants at all, so a schema built around fashion-style colour/size pairs breaks on the first book. Worse, stock has a race condition at its core: between a customer placing an order and the store confirming it, that item must not be sellable to someone else — but it must not be permanently gone either, because abandoned orders would silently drain the catalogue to zero.

Solution. Both variant axes are optional, and products without variants still get one hidden auto-created "Default" colour holding price, stock, and images — so there is a single uniform data model and one code path everywhere instead of branching on variant shape. Responsibility is split by level: price lives on the colour, since colours can be priced independently, and stock lives on the size, the inventory leaf. The buyable unit is therefore the triple (product, colour, size), and images belong to the colour so the gallery swaps when a customer picks one. Stock uses a soft-reserve engine where available = stock − reserved: placing an order reserves, cancelling or expiring releases, confirming deducts stock and clears the reservation, and cancelling a confirmed order restores. Every reservation is all-or-nothing inside the caller's MongoDB transaction — if any line of an order cannot be satisfied, the whole thing rolls back. A background sweeper runs every ten minutes to release holds from pending orders past their 24-hour window. Categories are an unlimited nested tree, images go through Cloudinary, and invoices are generated as PDFs with pdfkit.

Engineering and quality focus. The "Default" variant is the kind of decision that pays for itself across the codebase: by refusing to special-case variant-less products at the schema level, every downstream query, cart operation, and stock mutation stays on one path. The inventory engine documents its own state machine in the source and runs all four operations inside the caller's transaction session rather than opening its own, so ordering logic composes correctly instead of committing partial writes. The sweeper explicitly notes its own limitation — it runs in-process, and a multi-instance deployment needs it moved to a single worker or external scheduler — which is the sort of known-boundary documentation that keeps a correct system correct after it scales. Design decisions themselves are version-controlled in DECISIONS.md, capturing what was locked with the store owner and where it overrides the original requirements.