Veloura — Intimate Atelier

System Architecture

Full-stack headless e-commerce platform for luxury lingerie

Next.js 16 Medusa v2 TypeScript PostgreSQL 16 Redis 7 Stripe Docker Caddy Sentry
Frontend
Backend API
Data Layer
External Services
Infrastructure
Monitoring
High-Level Request Flow
👤
Client Browser
Desktop & Mobile
  • Guest browsing — no auth required
  • ES / EN locale detection
  • Cart persisted in localStorage
HTTPS
⚡
Next.js 16 — Storefront
App Router · React Server Components · Vercel
  • SSR pages with 5s/300s revalidation
  • Zustand stores (cart, filters)
  • TanStack Query (60s stale)
  • API routes → /api/*
REST API
🔷
Medusa v2 — Commerce Engine
Node.js · TypeScript · Port 9000
  • Store API + Admin API
  • Workflow orchestration engine
  • Event-driven subscribers
  • JWT auth (7d expiry)
TCP
🗄️
Data Layer
PostgreSQL 16 · Redis 7
  • Products, orders, inventory
  • Redis event bus & cache
  • Workflow state persistence
  • Session storage
Frontend Architecture
📄
Pages & Routes
App Router · SSR
  • / — Hero + featured
  • /category/[slug]
  • /product/[slug]
  • /cart
  • /checkout
🧠
State Management
Zustand · React Query
  • Cart store → localStorage
  • Filter store → URL sync
  • Checkout → sessionStorage
  • Server state → React Query
🎨
UI System
shadcn/ui · Tailwind v4
  • Dark theme by default
  • Amber accent palette
  • Lucide icons
  • Responsive (mobile-first)
🔗
API Layer
Axios · Medusa Client
  • Client: Axios → /api/*
  • Server: fetch → Medusa
  • Publishable API key auth
  • 4s timeout · 1 retry
Checkout State Machine
Shipping
Address & contact info
Payment
Stripe Elements
Review
Order summary
Complete
Confirmation
Backend Architecture
🌐
API Layer
REST · Middleware · CORS
  • Store API — public storefront
  • Admin API — dashboard CRUD
  • Request ID tracking
  • CORS per origin type
  • Custom admin widgets & routes
📦
Commerce Modules
Medusa Core Modules
  • Products & Categories
  • Orders & Cart / Checkout
  • Inventory & Stock Locations
  • Fulfillment (3 shipping tiers)
  • Multi-currency (USD/EUR/GBP/MXN)
⚡
Event & Workflow Engine
Redis Pub/Sub · Subscribers
  • Event bus (Redis-backed)
  • order.placed subscriber
  • Workflow orchestration engine
  • Background jobs (scheduled)
  • Distributed cache layer
Data Flow — Product Request
Browser
User visits /category/bridal
React Server Component renders on server
SSR
Next.js Server
Server Component
Calls Medusa client with publishable key
FETCH
Medusa API
/store/products
Validates API key, resolves region & currency
SQL
PostgreSQL
Products + variants
Returns products with pricing, inventory & images
CACHED
Redis
Cache layer
Caches query results, events queued here too
Payment Flow
Checkout UI
Stripe Elements
POST
/api/stripe
Next.js Route Handler
Zod validates payload, computes trusted totals server-side
SDK
Stripe API
PaymentIntent
Creates PaymentIntent, returns clientSecret
SECRET
Confirm Payment
stripe.confirmPayment()
WEBHOOK
Medusa
order.placed event
Stripe webhook triggers order creation in Medusa
External Services & Integrations
💳
Stripe
Payment Processing
  • PaymentIntent API
  • Card, Link, Bank Transfer
  • Webhook validation
  • Rate limited (10/60s)
🐛
Sentry
Error Monitoring
  • Server + Client + Edge
  • Tunnel route (/monitoring)
  • Source maps upload
  • Production only
🌍
Vercel
Frontend Hosting
  • Edge functions
  • Automatic HTTPS
  • Image optimization CDN
  • Preview deployments
🔒
Caddy
Reverse Proxy
  • Auto TLS certificates
  • api.veloura.com routing
  • Security headers (HSTS, CSP)
  • Gzip compression
Production Infrastructure
🔀
Caddy
Reverse proxy
Ports 80 / 443
Auto TLS
🔷
Medusa
Commerce API
Port 9000
CPU & mem limits
🐘
PostgreSQL 16
Primary database
Health checks
Persistent volume
⚡
Redis 7
Cache + Events
Workflow engine
Health checks
Commerce Domain Model
👗
Product Catalog
12 SKUs · 4 Categories
  • Balconette — Signature bras
  • Bodysuits — Full-body pieces
  • Bridal — Wedding collection
  • Lounge — Comfort wear
  • Sizes: XS → XL per variant
  • Multi-currency: USD / EUR / GBP / MXN
🚚
Fulfillment & Regions
3 Regions · Miami Warehouse
  • North America — USD
  • Europe — EUR
  • United Kingdom — GBP
  • Standard shipping (5-7 days)
  • Express shipping (2-3 days)
  • Complimentary (orders $150+)
Testing & CI/CD Pipeline
✅
Testing
Vitest · Playwright · Testing Library
  • Unit tests (Vitest) — 80% threshold
  • E2E tests (Playwright)
  • Accessibility (@axe-core)
  • Component testing (RTL)
🔄
CI/CD
GitHub Actions · Husky
  • Pre-commit hooks (lint-staged)
  • GitHub Actions workflows
  • Semantic versioning
  • CHANGELOG generation
🛡️
Security
Headers · Validation · Rate Limiting
  • CSP + HSTS + X-Frame-Options
  • Zod payload validation
  • Server-side price calculation
  • Stripe rate limiting (10/60s)
Internationalization
Request
Incoming URL
Middleware
Locale detection
Cookie → Accept-Language → default (ES)
/es/* or /en/*
URL rewrite
LanguageProvider
React Context
Broadcasts locale to all components via context
🇪🇸 ES / 🇺🇸 EN
Rendered page

Veloura System Architecture — Generated March 2026