The Challenge
Independent merchants face a tough choice: pay premium SaaS fees (Shopify at $39–399/month), deal with rigid templates, or invest heavily in custom development. Small and medium businesses need the flexibility of a custom solution at the cost of a shared platform. Kinetia Store aims to be that platform — a multi-tenant e-commerce system where any merchant can launch a fully-featured store without writing a single line of code.
Our Approach
We built Kinetia Store as a modular monolith using Turborepo:
- 3 Applications — Express 5 REST API, Next.js 15 SSR Storefront (customer-facing), and Next.js 15 Admin Dashboard (merchant-facing)
- 4 Shared Packages — Database schemas + migrations, ESLint config, TypeScript config, and Tailwind config
- Service Layer Pattern — Routes handle HTTP + Zod validation, Services contain business logic, keeping concerns cleanly separated
- Multi-Tenant by Design — Every entity references
storeId, all queries are tenant-scoped, with row-level locking for concurrent tenant creation
Rules-Based Promotion Engine
The promotion system is a 4-stage pipeline: fetch → evaluate conditions → apply actions → stacking rules.
| Type | Description |
|---|---|
| Percentage | 10% off entire order |
| Fixed Amount | $5 off orders over $50 |
| Buy X Get Y | Buy 2, get 1 free |
| Bundle | Discount when buying specific items together |
| Mix & Match | Combine items from different categories |
| Tiered | Increasing discounts at quantity thresholds |
| Free Shipping | Waive shipping on qualifying orders |
| BOGO | Buy one, get one at 50% off |
Conditions support AND/OR grouping with 11 comparison operators and 9 target types (products, categories, collections, cart total, and more). Bulk loading in parallel prevents N+1 queries. Merchants configure promotions visually from the admin dashboard — no code needed.
Technical Highlights
- Multi-Tenant Isolation — Logical isolation via
storeIdon a single PostgreSQL instance; dual ownership (admin + merchant) with polymorphic FKs; slug→UUID resolution viares.localsto survive Express 5 Router boundaries - Guest Cart System — Session-based carts with 30-day expiration; IDOR protection via session header validation; seamless merge when guests register
- JWT Authentication — Short-lived access tokens (15min) with refresh token rotation (7d); secure cookie transport
- Internationalization — next-intl with 3 languages (Spanish, English, Portuguese) on both Storefront and Admin
- Type Safety End-to-End — Drizzle ORM for type-safe SQL, Zod validation on all API inputs and env vars, shared TypeScript configs
- Race Condition Prevention — Row-level locking with transactions for concurrent tenant creation
Architecture
kinetia-store/
├── apps/
│ ├── api/ # Express 5 REST API (Node.js 24)
│ ├── storefront/ # Next.js 15 SSR (customer-facing)
│ └── admin/ # Next.js 15 (merchant dashboard)
├── packages/
│ ├── database/ # Drizzle schemas + 23 tables
│ ├── eslint-config/
│ ├── typescript-config/
│ └── tailwind-config/Current Status
Kinetia Store is in active development with a 14-phase roadmap:
- Phases 0–4 — Complete (foundation, auth, orders, promotions, storefront)
- Phase 5 — Admin Dashboard (in progress)
- Upcoming — Stripe payments, account management, transactional emails, inventory, advanced search, production readiness (CI/CD, monitoring)
Codebase metrics: 291 commits, ~80 merged PRs, 10 test files, 104 planned tasks (38 completed).