PRODUCT DESIGN + FULL-STACK ENGINEERING
Calm storefront.
Connected product path.
Mindful Tee Shirts is a live commerce system: a Next.js storefront connected to catalog data, Square checkout, customer sessions, fulfillment workflows and protected admin operations.
- FRAMEWORK
- Next.js 14.2.35 App Router · React 18 · TypeScript · Tailwind CSS
- DATA + PAYMENTS
- Turso/libSQL with SQLite fallback · Square active storefront checkout
- OPERATIONS
- Protected admin dashboard with signed HttpOnly sessions · customer magic links · R2 media · Brevo/SMTP email
01 / LIVE PRODUCT SURFACE
Real screens from a working storefront.
These captures show the customer-facing path as it exists on Mindful Tee Shirts: discovery, product choice, cart review and checkout.
02 / THE PRODUCT
Commerce has a customer side and a work-after-click side.
The public App Router surface covers the home experience, product listing and detail pages, custom orders, cart, checkout, account, support and policy pages. Product data is read from shared database services, while the cart uses Zustand with localStorage persistence.
API route handlers validate checkout input, reserve inventory, create orders, reconcile payment state and give operations the context needed to move an order through fulfillment.
03 / SYSTEM PATH
From product selection to fulfillment.
The path keeps customer intent, payment state and fulfillment context aligned.
- 01CatalogProducts, variants and images from libSQL
- 02CartZustand state persisted in the browser
- 03Checkout previewServer-side totals, shipping and validation
- 04PaymentSquare storefront checkout and payment lifecycle
- 05Webhook reconciliationSigned, deduplicated payment events
- 06Order lifecyclePaid → processing → shipped → delivered
- 07Fulfillment + supportAdmin tools, email and shipping records
04 / ENGINEERING DECISIONS
Keep the catalog authoritative.
Products, product variants, inventory counts, active/purchasable flags and product-request history live in the data layer instead of being trusted from the browser.
Make checkout replay-safe.
Checkout fingerprints, idempotency keys, payment audit logs and inventory reservations protect the boundary where an enthusiastic customer can otherwise create duplicate or inconsistent work.
Let payment events drive order state.
Signed Square webhooks are deduplicated, processed through a strict order/payment state machine and preserved in a dead-letter table when manual replay is needed.
Keep operations behind a real boundary.
The protected admin surface is guarded by middleware and signed HttpOnly sessions; customer account access uses expiring magic-link sessions rather than a public shortcut.
05 / VERIFIED SUPPORTING SYSTEMS
Several product surfaces, one operating model.
- DATABASE
- Turso/libSQL through `@libsql/client`, with a local SQLite fallback and startup migrations.
- MEDIA
- Cloudflare R2 through the AWS S3 client for admin-uploaded product and site media.
- Brevo handles transactional/newsletter paths; Nodemailer provides SMTP delivery and fallback service paths.
- ADDRESS
- Mapbox client-side autocomplete is paired with server-side address parsing.
- ANALYTICS
- Consent-aware Vercel Analytics and Speed Insights plus a persisted page-view route and admin dashboard metrics.
- FINANCING
- Affirm authorization/capture infrastructure remains in the codebase but is intentionally dormant and not presented as an active storefront payment method.
- DELIVERY
- Vercel configuration includes a scheduled abandoned-cart route; product pages use five-minute revalidation and mutations call `revalidatePath`.
06 / CURRENT STATE
A live storefront with a real operating system behind it.
The current codebase connects product discovery to payment, order state, inventory, customer access, email, media and admin fulfillment work. The live surface is quiet; the system underneath is deliberate.