Tech Stack

Full technology stack used in the NexusCommerce platform, with version details and rationale.

Overview

NexusCommerce is built on a modern, TypeScript-first stack with a Python AI worker fleet. Every technology choice was made to balance developer velocity, operational simplicity, and production scale.

Key Concepts

Monorepo — All code (frontend, backend, packages, services) lives in a single pnpm workspace managed by Turborepo. This enables shared TypeScript types, coordinated versioning, and unified CI/CD.

TypeScript First — The entire application layer (Next.js, NestJS, packages) is written in TypeScript. This catches integration bugs between services at compile time.

Getting Started

To understand how to work with the stack, read:

Installation — How to run the full stack locally
Architecture — How the layers interact

Features

Frontend

Technology	Version	Purpose
Next.js	15	React framework with App Router, Server Components
React	19	UI component library
Tailwind CSS	v4	Utility-first CSS with design token system
shadcn/ui	Latest	Accessible component primitives
TypeScript	5.x	Type safety
pnpm	9.x	Package manager
Turborepo	2.x	Monorepo build system

Design System — The packages/ui package exports the shared component library with custom design tokens:

bg-0, bg-1, bg-2 — Background hierarchy tokens
text-0, text-1, text-2 — Text hierarchy tokens
border-0, border-1 — Border tokens
accent copper — #C8956C — Primary accent color

The frontend uses a dark-only "Luxury Instrument Panel" theme. Light mode is not supported.

Key Libraries:

@tanstack/react-query — Server state management
recharts — Charts for analytics dashboard
@dnd-kit/core — Drag-and-drop for FlowForge canvas
zod — Form validation schemas

Backend API

Technology	Version	Purpose
NestJS	11	Node.js API framework
TypeScript	5.x	Type safety
Supabase JS	2.x	Database client
BullMQ	5.x	Job queue (backed by Redis)
`@nestjs/schedule`	4.x	Cron-based adapter scheduling
Zod	3.x	Input validation

Module Structure — The NestJS API follows the Module + Service + Controller triplet pattern. Each domain has its own module registered in app.module.ts.

Domain modules:

CatalogModule — Products, listings, images
FulfillmentModule — Orders, shipments
InventoryModule — Warehouses, stock levels, adjustments
IntelligenceModule — Pricing rules, recommendations, Buy Box
AnalyticsModule — ClickHouse queries, custom reports
AdsModule — Ad campaigns and performance
ReviewsModule — Review import and sentiment
ConnectionsModule — Marketplace connection management
WorkersModule — AI job dispatch and monitoring
BillingModule — Stripe subscription management
AuthModule — JWT validation, API key management

Database

Technology	Version	Purpose
Supabase	Cloud / self-hosted	Primary database + auth + storage + realtime
PostgreSQL	15	Relational data store
Row Level Security	—	Multi-tenant data isolation

Supabase provides:

PostgreSQL with 25+ tables and RLS policies
Supabase Auth for user authentication and JWT issuance
Supabase Storage for product images and CSV exports
Supabase Realtime for live dashboard updates

Analytics

Technology	Version	Purpose
ClickHouse	24.x	Columnar analytics database
ClickHouse HTTP interface	—	Used by NestJS for query execution

ClickHouse hosts the analytics tables (orders, pricing events, inventory events) and materialized views for sub-second dashboard queries. Data is ETL'd from Supabase via the NestJS ETL service.

AI Workers

Technology	Version	Purpose
Python	3.12	Worker runtime
FastAPI	0.111	Worker API framework
OpenAI Python SDK	1.x	LLM API access
httpx	0.27	Async HTTP client for marketplace APIs

Workers receive job parameters via HTTP from the NestJS API (which picks jobs from the BullMQ queue), execute the AI task, and write results back to Supabase via the Supabase Python client.

Infrastructure

Technology	Purpose
Docker / Docker Compose	Containerized development and production deployment
Caddy	Production reverse proxy with automatic Let's Encrypt TLS
Redis 7	BullMQ job queue backing store
Kubernetes / Helm	Cluster deployment with HPA autoscaling
GitHub Actions	CI/CD — image builds, VPS deploy, K8s deploy
GitHub Container Registry	Docker image storage (`ghcr.io`)
Grafana	Monitoring dashboards (ClickHouse + Redis datasources)

See Deployment for production setup details.

Configuration

Key package.json scripts across the monorepo:

# Root
pnpm build        # Build all packages and apps
pnpm dev          # Start all services in development mode
pnpm lint         # Lint all packages
pnpm typecheck    # Run TypeScript compiler checks

# apps/web
pnpm dev          # Next.js dev server on port 3000
pnpm build        # Production build

# apps/api
pnpm dev          # NestJS dev server on port 4000
pnpm build        # Compile TypeScript to dist/

# services/workers
uvicorn main:app --reload --port 8000

On this page