Skip to main content

Live App

spruce-backend.vercel.app

Repository

TrueGroupAgency/spruce

​
Overview

The Account App is the hosted checkout and member portal for the CelticLuck platform. It orchestrates payment flows, subscription management, and member experiences across multiple brands (Spruce Collective, Athera Sports, PetKind).

​
Core Functions

Unified Checkout System
Handles raffle entries, merchandise orders, and subscription checkouts through a single, PCI/DSS-compliant flow. Integrates with NomuPay for card payments, Apple Pay, and Google Pay. Automatically applies discount codes, upsells, and free-entry promotions based on campaign rules. Member Dashboard
Authenticated members can view their raffle entries, track order status, claim account-specific discounts, and manage subscription tiers (Bronze/Silver/Gold). Magic-link authentication eliminates passwords while maintaining security. Multi-Brand Orchestration
Detects brand context via URL parameters or site ID headers, then dynamically applies:
  • Brand-specific fonts, logos, and color schemes
  • Correct API endpoints and legal links
  • Tailored upsell offers and redemption rules
Analytics Pipeline
Tracks checkout funnels, conversion events, and revenue attribution via Triple Whale, Google Tag Manager, TriplePixel, and custom replay systems for failed transactions.

​
Tech Stack

  • Framework: Next.js 15 App Router with React 19
  • Language: TypeScript
  • Styling: Tailwind CSS, Radix UI primitives
  • Deployment: OpenNext targeting Cloudflare Workers

​
Project Structure

app/                # Routes, layouts, and pages (App Router)
components/         # Reusable UI, including components/ui primitives
lib/                # API client and shared utilities
devlink/            # Shared navbar/footer assets from Webflow
public/             # Static assets
styles/             # Tailwind layers and global styles
types/              # Shared TypeScript contracts

​
Key Modules

  • lib/api.ts: Centralized fetch wrapper with JWT handling and 401 recovery.
  • lib/utils.ts: Formatting helpers for currency, dates, countdowns, and base paths.
  • app/auth-gate.tsx: Auth bootstrap and magic-link confirmation flow.
  • components/quick-buy-modal.tsx: Checkout entry point that calls createRevolutOrder.

​
Getting Started

1

Install dependencies

Run the following command (Node 18+ or 20+ recommended):
pnpm install
2

Configure environment

Copy .env.example to .env.local and populate the variables.
3

Start development server

pnpm dev
Visit http://localhost:3000 to see the app.

​
Environment Variables

VariableDescriptionDefault
NEXT_PUBLIC_API_BASE_URLAPI originhttps://api.sprucecollective.co.uk/api
NEXT_PUBLIC_BASE_PATHBase path for routingMust match next.config.mjs
NEXT_PUBLIC_MARKETING_SITE_URLMarketing site base URLhttps://sprucecollective.co.uk
SITE_CONFIG_API_TOKENBearer token for admin site-config API-
Tokens are read from localStorage by lib/api.ts. 401 responses automatically clear tokens and redirect to login. Never commit real credential values.

​
Development Guidelines

​
Coding Standards

  • TypeScript + React: Use functional components and 2-space indentation.
  • Client Components: Start files with "use client" where necessary.
  • UI Primitives: Prefer existing components under components/ui/*.
  • API Calls: Route all network calls through lib/api.ts.

​
Testing

  • Run pnpm lint and pnpm build before opening a PR.
  • Add deterministic unit tests (*.test.tsx) alongside code.
  • Keep tests independent of remote services by mocking fetches.

​
Deployment

  • OpenNext: Configuration lives in open-next.config.ts.
  • Cloudflare: Worker settings are in wrangler.jsonc.
  • Preview: Generate a local preview with pnpm preview.