craft2prints/README.md

Craft2Prints — Ink it. Print it. Love it.

A complete self-hosted e-commerce platform for personalized products (apparel, drinkware, phone cases) with an in-browser design tool, integrated accounting system, and real Stripe payments.

Features

Customer Experience

• Design Tool — In-browser tool to customize templates with text and images
• Product Catalog — Browse and filter by category, color, size, and price
• Shopping Cart — Persistent cart stored in IndexedDB
• Customer Accounts — Optional sign-up for order history and faster checkout
• Dark Mode — Full dark mode support with system preference detection
• Mobile Responsive — Works seamlessly on all devices

Order Management

• Real Payments — Stripe integration for production-ready checkout
• Order Tracking — Customers see order history, status, and print files
• Design Approvals — Upload custom designs for customer review with built-in chat
• Photo Requests — Customers submit photos; you design them into products
• Auto-Archiving — Paid/failed orders auto-archive after 30 days

Admin Dashboard

• Product Management — Add/edit/delete products with photos, colors, sizes
• Category Management — Organize products by customer-facing categories
• Financial System — Complete self-hosted accounting:
  • 📊 Reports & Analysis — KPIs, profit trends, income breakdown, tax year summaries
  • 🏦 Bank Reconciliation — Upload CSV statements, auto-match transactions, verify accuracy
  • 📋 Audit Trail — Track all changes with IP addresses, timestamps, and reasons
  • 📈 Tax Compliance — UK tax year (April-April) calculations and HMRC export
• Admin Login Activity — Track who logged in, when, from where
• Customer Login Activity — Monitor customer account access
• Order Management — View, approve, archive orders
• Inbox — Chat with customers about design changes
• Promotions — Create sales with per-product or site-wide discounts

Security & Compliance

• Admin Authentication — Session-based login with automatic logout on page close
• Customer Authentication — Separate customer account system (optional)
• Rate Limiting — DB-backed rate limiting on login/checkout
• CAPTCHA — Cloudflare Turnstile on public forms
• Audit Logging — Full financial audit trail for compliance
• Session Expiry — Auto-logout when browser closes

Technical Stack

• Frontend — Next.js 16 (App Router, Turbopack), React, Tailwind CSS
• Backend — Next.js server actions, API routes
• Database — PostgreSQL with Prisma ORM
• File storage — Uploaded images/documents are compressed with sharp and saved as files on disk (public/uploads/), not as base64 in the database — see Image & File Storage below
• Payments — Stripe (production-ready)
• Email — SMTP (Gmail, Outlook, SendGrid, etc.)
• Design — Fabric.js/Konva canvas for the design tool, SVG-based product mockups

Quick Start

1. Install Node.js 18+ — Check with node -v

2. Install dependencies

   npm install
   

3. Set up environment

   cp .env.example .env
   # Edit .env with your configuration (see SETUP_AND_BUILD.md for details)
   

4. Create database and load starter products

   npm run db:push
   npm run db:seed
   

5. Start dev server

   npm run dev
   

   Open http://localhost:3000 — you'll see the homepage and catalog.

Configuration

Essential (.env):

• DATABASE_URL — PostgreSQL connection string
• ADMIN_USER / ADMIN_PASSWORD — Admin login credentials (⚠️ change before deployment)
• STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET — Stripe payment keys

Optional:

• SMTP_* — Email configuration for order confirmations and password resets
• NEXT_PUBLIC_TURNSTILE_SITE_KEY / TURNSTILE_SECRET_KEY — CAPTCHA on forms
• NEXT_PUBLIC_FACEBOOK_APP_ID — Messenger sharing (WhatsApp always works)

See .env.example and SETUP_AND_BUILD.md for complete reference.

Key Concepts

Product Catalogs

• Personalised Catalog (/made-to-order) — Full design tool, customers customize templates
• Products Catalog (/products) — Buy as-is with color/size picker, no design tool

A product can appear on both catalogs simultaneously.

Currency

Prices stored in GBP pence internally. Customer-facing header currency selector (£/$/€) changes display only — no actual conversion happens until checkout is configured for it.

Cart Storage

Cart persists to IndexedDB, not localStorage, since it comfortably holds the design tool's cart items without the ~5-10MB ceiling localStorage imposes.

Color Names

Colors display as friendly names to customers (Navy, Red, Forest Green) instead of hex codes. Admin still sees hex for reference.

Image & File Storage

Every uploaded image or document (product photos, gallery photos, custom-request photos, design-approval previews, purchase invoices, expense receipts, images added inside the design tool) is saved as a real file on disk under public/uploads/<category>/<yyyy>/<mm>/<uuid>.<ext>, compressed and resized on the way in with sharp. Database columns only ever hold the resulting short URL (e.g. /uploads/gallery/2026/07/<uuid>.jpeg) — never a base64 data URL. PDFs (invoices/receipts) pass through untouched.

This matters operationally: public/uploads/ is gitignored but lives permanently on the server's disk, so backups must cover it alongside the database (see SETUP_AND_BUILD.md). No web server config is needed to serve these files — Next.js serves everything under public/ automatically.

See src/lib/storage.ts for the upload/compression helper and its per-category presets.

Accounting Features

Financial Reports

• KPI Dashboard — Year-to-date metrics, income source breakdown, growth rates
• 12-Month Trends — Visual profit trends with best/worst month analysis
• Income Breakdown — Website sales vs manual sales comparison
• Revenue vs Expenses — Side-by-side trend analysis
• Tax Year Summary — UK April-April year calculations
• HMRC Report — Tax compliance format for self-assessment filing

Bank Reconciliation

• Upload CSV bank statements from any UK bank
• Auto-matches transactions based on amount and date (95%+ accuracy)
• Manual matching for edge cases (transfers, fees, refunds)
• Discrepancy detection (amount mismatches flagged in orange)
• Reconciliation status tracking (PENDING → RECONCILED → ARCHIVED)
• Export reconciliation reports

Audit Trail

• Logs all financial changes (create/update/delete)
• Tracks IP address, timestamp, and reason for each change
• Stores before/after values for data integrity
• Separate login activity logging (admin and customer)

Deployment

See SETUP_AND_BUILD.md for detailed deployment instructions including:

• Production build process
• Environment setup
• Stripe live keys configuration
• Reverse proxy setup (nginx)
• Process management (pm2)
• Database backups
• Security hardening

Support

• Issues — Check the GitHub issues for known problems
• Docs — See SETUP_AND_BUILD.md for comprehensive setup and deployment guide
• Examples — .env.example shows all available configuration options

License

Built with ❤️ for small businesses and makers.