🧵 091 — PixelStitch — AI-Powered Cross-Stitch Pattern Generator from Photos

Elevator Pitch

PixelStitch transforms any photo into a beautiful, ready-to-stitch cross-stitch pattern in seconds. Upload an image, customize stitch count and color palette, and download a print-ready PDF pattern grid with a DMC thread color key. It's the missing link between digital photos and handcrafted art — turning memories into stitchable masterpieces without the tedious manual charting process.

Problem

Cross-stitch is experiencing a massive renaissance (the #crossstitch hashtag has billions of views on TikTok, and the global embroidery market is projected to reach $3.2B by 2030). But the biggest pain point for modern stitchers is pattern creation:

1. Manual charting is agonizing — Converting a photo to a cross-stitch pattern traditionally requires tracing pixel-by-pixel in specialized desktop software (PCStitch, WinStitch) that costs $30–$80 and feels like it was built in 2003.
2. Color matching is a nightmare — Translating image colors to actual DMC/Anchor thread colors involves guesswork and expensive physical color cards.
3. No cloud or sharing — Existing tools are desktop-only with no cloud saving, sharing, or community features.
4. Steep learning curve — Beginners are overwhelmed by complex software with dozens of settings they don't understand.
5. Creators need quick turnarounds — Craft content creators who sell patterns on Etsy or share on social media need to generate patterns fast, not spend hours charting.

Solution

PixelStitch is a browser-based SaaS that converts any uploaded image into a professional cross-stitch pattern:

• AI Image Quantization — Smart color reduction that maps image pixels to the nearest DMC/Anchor thread colors, preserving detail while keeping the stitch count manageable.
• Visual Pattern Editor — Interactive grid where users can zoom, pan, edit individual stitches, and adjust colors post-generation.
• One-Click PDF Export — Download a clean, print-ready pattern PDF with color legend, stitch count, and fabric size calculations.
• Cloud Pattern Library — Save unlimited patterns to your account, organize into collections, and access from any device.
• Community Gallery — Share finished pieces, discover patterns from other stitchers, and get inspired.
• Stitch Calculator — Automatically estimates fabric dimensions, thread usage, and estimated completion time based on stitch count and stitcher speed.

Target User

Full Tech Stack

Frontend

• Framework: Next.js 15 (App Router) + React 19 + TypeScript 5.5
• Styling: Tailwind CSS v4 + shadcn/ui components
• State Management: Zustand 5.x for client state, React Query (TanStack Query v5) for server state
• Canvas/Image Processing: Canvas API (native browser) + WebGL via PixiJS 8 for high-performance pixel manipulation on large images
• PDF Generation: jsPDF 2.x + jspdf-autotable for pattern grid rendering
• Drag & Drop: @dnd-kit/core for pattern editor stitch manipulation
• Icons: Lucide React (lucide-icons)
• Animations: Framer Motion 11 for page transitions and micro-interactions
• Color Utilities: culori 4.x for perceptual color space conversions (OKLCH → DMC matching)
• Form Handling: React Hook Form 7 + Zod 3.x validation

Backend

• API Layer: Next.js Route Handlers + Server Actions (App Router)
• ORM: Drizzle ORM 0.30+ with PostgreSQL dialect
• Database: PostgreSQL 16 hosted on Supabase (free tier → Pro)
• Auth: Supabase Auth (email/password + Google OAuth + magic links)
• File Storage: Supabase Storage (user uploaded images + generated pattern thumbnails) in an images/ bucket with RLS policies
• Background Jobs: Inngest (serverless function orchestration) for async pattern generation on large images (>200x200 stitches)
• Email: Resend 3.x for transactional emails (welcome, pattern ready, export receipts)
• Payments: Stripe Checkout + Stripe Webhooks (subscription management)

Data Processing

• Color Quantization: Custom algorithm using median-cut quantization in a Web Worker, then OKLCH color-space nearest-neighbor matching against a bundled DMC 500-color database (JSON)
• Dithering: Floyd-Steinberg dithering option for smoother gradients in patterns
• Image Preprocessing: Sharp (via serverless function) for image resizing, cropping, and aspect ratio normalization before pattern generation
• DMC Color Database: Bundled JSON file mapping DMC thread numbers → floss name → hex color → OKLCH values (sourced from DMC's official catalog)

Infrastructure & DevOps

• Hosting: Vercel (Pro plan) — frontend + API routes
• Database Hosting: Supabase (Pro plan — PostgreSQL + Storage + Auth in one)
• CDN: Vercel Edge Network (automatic) + Supabase Storage CDN for image assets
• Domain: Vercel-managed custom domain with automatic SSL
• Monitoring: Sentry (sentry-nextjs SDK) for error tracking + PostHog for product analytics (feature usage, conversion funnels)
• Logging: Axiom.co (Vercel integration) for structured query logs
• CI/CD: GitHub Actions — lint (ESLint + Biome) → type-check → build → deploy on push to main
• Testing: Vitest 2.x for unit/integration tests, Playwright 1.x for E2E (pattern generation flow, PDF export, auth)

Environment Variables

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...

# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...

# Resend
RESEND_API_KEY=re_...

# Inngest
INNGEST_SIGNING_KEY=ise_...

# Sentry
SENTRY_DSN=https://...@sentry.io/...

# PostHog
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

# App
NEXT_PUBLIC_APP_URL=https://pixelstitch.app

UI Design Language

Design Philosophy

Soft Craft / Warm Minimal — PixelStitch should feel like stepping into a cozy craft studio: warm, inviting, with tactile textures and soft edges. Think Pinterest meets a modern craft app. The interface should make a technical process (pixel quantization) feel approachable and creative.

Base Framework

• Tailwind CSS v4 — utility-first with custom CSS variables for the design system
• shadcn/ui — base component primitives (buttons, dialogs, dropdowns, tabs, sliders) customized with the warm craft theme

Color Palette

Dark Mode: Shifted palette — --slate-950 background, --rose-400 accent, --stone-800 card surfaces. Toggled via class="dark" on <html> with system preference detection.

Typography

• Headings: "DM Serif Display" (Google Fonts) — 700 weight, gives an editorial/craft-magazine feel
• Body: "Inter" (Google Fonts) — 400/500/600 weights — clean readability for pattern data and settings
• Code/Data: "JetBrains Mono" (Google Fonts) — for stitch coordinates and technical readouts
• Scale: 14px base, modular scale 1.25 (14, 17.5, 21.8, 27.3, 34.1)

Spacing & Radius

• Philosophy: Soft and rounded — cross-stitch is all about rounded crosses
• Border radius: rounded-xl (12px) for cards, rounded-2xl (16px) for modals, rounded-full for avatars and badges
• Spacing: 4px base grid, Tailwind's default scale. Sections use py-16 px-6, cards p-6, inputs px-4 py-2.5
• Shadows: Warm-tinted — shadow-[0_2px_8px_rgba(244,63,94,0.08)] for subtle rose-tinted elevation

Component Library

• Base: shadcn/ui primitives (Dialog, Dropdown, Tabs, Slider, Tooltip, Toast)
• Custom Components:
  • PatternGrid — Canvas-based interactive grid component (the core product)
  • ColorSwatch — Thread-style color chip with DMC number overlay
  • StitchCounter — Animated number counter for stats
  • FabricPreview — Visual representation of the fabric with pattern overlay
  • UploadDropzone — Drag-and-drop with image preview thumbnail
• Icons: Lucide React — warm-toned (rose-500 for active, slate-400 for inactive)

Animation Library

• Framer Motion 11 — page transitions (fade + slide-up), upload animations, pattern generation progress
• CSS transitions — hover states, button interactions, toggle switches
• Generation animation: A "stitching" progress animation — an animated cross-stitch pattern that fills in progressively while the pattern generates

Layout Patterns

• Landing: Full-width hero with animated pattern preview, sticky topnav
• App: Sidebar navigation (Dashboard → New Pattern → My Patterns → Community → Settings)
• Pattern Editor: Full-width grid canvas with collapsible left panel (color palette/tools) and right panel (settings/details)
• Community Gallery: Masonry grid layout with hover-reveal pattern details
• Mobile: Bottom tab navigation, full-screen pattern grid with floating toolbar

Responsive Approach

• Mobile-first Tailwind breakpoints: sm:, md:, lg:, xl:
• Pattern grid renders at device-native resolution with pinch-to-zoom
• PDF export adapts to printable A4/Letter sizes regardless of screen

Full System Architecture

Architecture Pattern

Single Monorepo — Next.js 15 App Router monolith with serverless scaling. No need for microservices at this stage. All routes, API handlers, and server actions live in one Next.js app. The only external compute is Inngest (for async pattern generation on large images).

Repository Structure

pixelstitch/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (marketing)/       # Public pages (landing, pricing, about)
│   │   ├── (app)/              # Authenticated app (layout with sidebar)
│   │   │   ├── dashboard/     # Dashboard with recent patterns & stats
│   │   │   ├── patterns/       # Pattern editor & gallery
│   │   │   ├── community/      # Shared pattern gallery
│   │   │   ├── generate/      # Upload & configure new pattern
│   │   │   └── settings/      # Account, subscription, preferences
│   │   ├── api/                # Route handlers
│   │   │   ├── patterns/      # CRUD + generation
│   │   │   ├── stripe/         # Webhook receiver
│   │   │   ├── community/      # Gallery browse & search
│   │   │   └── export/         # PDF generation endpoint
│   │   └── auth/               # Supabase Auth helpers
│   ├── components/             # Shared UI components
│   │   ├── ui/                 # shadcn/ui primitives
│   │   ├── pattern/            # Pattern-specific (grid, palette, tools)
│   │   ├── marketing/          # Landing page sections
│   │   └── layout/             # Sidebar, nav, footer
│   ├── lib/                    # Core logic
│   │   ├── quantize/           # Color quantization + dithering
│   │   ├── dmc/                # DMC color database + matching
│   │   ├── pdf/                # PDF pattern generation
│   │   ├── canvas/             # Canvas rendering & interaction
│   │   └── utils/              # Shared utilities
│   ├── db/                     # Drizzle schema + queries
│   │   ├── schema.ts           # Table definitions
│   │   └── queries.ts          # Query functions
│   └── inngest/                # Background job functions
│       └── generate-pattern.ts  # Async pattern generation
├── public/                     # Static assets (DMC color JSON, etc.)
│   └── data/
│       └── dmc-colors.json     # 500 DMC thread colors with OKLCH values
├── tests/                      # Vitest + Playwright
├── drizzle.config.ts
├── next.config.ts
├── tailwind.config.ts
└── package.json

API Design

REST via Next.js Route Handlers + Server Actions for mutations:

• GET /api/patterns — List user's patterns (paginated, filtered by collection)
• POST /api/patterns/generate — Accept image upload + settings, returns job ID (Inngest)
• GET /api/patterns/[id] — Fetch pattern metadata + grid data
• PATCH /api/patterns/[id] — Update pattern (name, collection, edits)
• DELETE /api/patterns/[id] — Soft delete pattern
• POST /api/patterns/[id]/export — Generate and return PDF
• GET /api/community — Browse public community patterns (paginated, searchable)
• POST /api/community/[id]/like — Like/unlike a community pattern
• POST /api/stripe/webhook — Stripe Checkout session webhook handler

Server Actions (mutations):

• createPattern(formData) — Upload + trigger generation
• updatePatternSettings(id, settings) — Adjust stitch count, colors, dithering
• savePatternEdits(id, stitchEdits) — Save grid-level edits
• toggleCommunityShare(id, public) — Share/unshare to gallery

Database Schema Overview

-- Core tables
users            { id, email, name, avatar_url, stripe_customer_id, plan, created_at }
patterns         { id, user_id, name, description, image_url, settings_json, grid_data, thumbnail_url, stitch_count_w, stitch_count_h, color_count, fabric_size, status, is_community, likes_count, created_at, updated_at }
collections      { id, user_id, name, icon, sort_order, created_at }
pattern_collection { pattern_id, collection_id }

-- Settings JSON structure (stored in patterns.settings_json)
-- { stitchCount: 150, fabricType: "Aida14", dithering: "floyd-steinberg", colorPalette: "full", customColors: ["#F43F5E", ...], backgroundColor: "#FFFFFF" }

-- Community
community_likes  { user_id, pattern_id, created_at }

-- Stripe
subscriptions     { id, user_id, stripe_subscription_id, plan, status, current_period_end, created_at }

Auth Flow

• Supabase Auth with email/password + Google OAuth
• Session: Supabase JWT stored in httpOnly cookie (managed by Supabase middleware)
• Middleware: Next.js middleware checks for Supabase session on /app/* routes, redirects to /login if absent
• RLS (Row Level Security): All Supabase tables have RLS policies — users can only read/write their own patterns (except community patterns which are publicly readable)

File Storage Strategy

• Provider: Supabase Storage
• Buckets:
  • user-images/ — Raw uploaded images (user-images/{user_id}/{uuid}.webp)
  • pattern-thumbs/ — Generated pattern thumbnails (pattern-thumbs/{pattern_id}.webp)
  • exports/ — Temporary PDF exports, auto-deleted after 1 hour via Inngest scheduled job
• Image Pipeline: User uploads image → Sharp resizes to max 2000px → stored as WebP → quantization runs on server → thumbnail generated → original + thumbnail stored

Background Jobs (Inngest)

1. Pattern Generation — When stitch count > 200x200, the quantization runs as an Inngest step function:
   • Step 1: Resize image via Sharp
   • Step 2: Run color quantization (median-cut)
   • Step 3: Apply dithering (if enabled)
   • Step 4: Map colors to nearest DMC threads (OKLCH nearest-neighbor)
   • Step 5: Generate grid data + thumbnail
   • Step 6: Store in DB + update pattern status
2. Export Cleanup — Cron job (daily) deletes PDF exports older than 24 hours from storage
3. Thumbnail Regeneration — On-demand if thumbnail is missing or corrupted

Caching Strategy

• Server: React Query (TanStack Query v5) with staleTime: 5min for pattern lists, staleTime: 30min for DMC color database
• CDN: Vercel Edge caches marketing pages. Supabase Storage CDN serves images.
• Client: Service Worker (optional, v2) caches the DMC color JSON locally for offline pattern editing
• No Redis: Not needed at this scale. Supabase connection pooling handles the load.

Environment Structure

Deployment Topology

User Browser
    │
    ▼
Vercel Edge Network (CDN, routing)
    │
    ▼
Vercel Serverless Functions (Next.js Route Handlers + Server Actions)
    │
    ├──▶ Supabase PostgreSQL (data)
    ├──▶ Supabase Storage (images, PDFs)
    ├──▶ Inngest (async jobs)
    ├──▶ Stripe (payments)
    └──▶ Resend (emails)

Monitoring & Analytics

• Error Tracking: Sentry (@sentry/nextjs) — captures unhandled errors, server-side exceptions, client-side crashes
• Product Analytics: PostHog — track key events (pattern_generated, pattern_exported, community_share, plan_upgrade, signup → first_pattern conversion funnel)
• Performance: Vercel Analytics (Web Vitals) + custom pattern-generation timing tracked in PostHog
• Uptime: UptimeRobot (free tier) pinging /api/health

Data Flow: Pattern Generation

1. User uploads image via drag-drop on /generate page
2. Client-side: Show preview, user adjusts settings (stitch count, fabric type, dithering)
3. Client calls Server Action: createPattern(formData)
4. Server Action:
   a. Validates input (Zod schema)
   b. Uploads raw image to Supabase Storage (user-images/)
   c. Creates pattern record in DB with status="processing"
   d. Triggers Inngest function: generate-pattern
   e. Returns pattern ID to client
5. Client polls (React Query refetchInterval: 3s) or receives SSE for status updates
6. Inngest function:
   a. Downloads image from Storage
   b. Sharp resize to match stitch count
   c. Median-cut quantization (reduce to N colors)
   d. Floyd-Steinberg dithering (optional)
   e. OKLCH nearest-neighbor against DMC 500 colors
   f. Build grid data array [{x, y, dmcColor, symbol}]
   g. Generate thumbnail via Canvas
   h. Store grid data + thumbnail
   i. Update pattern status = "ready"
7. Client detects status="ready", navigates to pattern editor
8. User can edit individual stitches, export PDF, share to community

PRD

Functional Requirements

Non-Functional Requirements

Epics & User Stories

Epic 1: Foundation & Auth (Day 1 — Morning)

Goal: Project scaffolding, auth, and core layout.

Epic 2: Pattern Generation Core (Day 1 — Afternoon)

Goal: Image upload → pattern conversion pipeline.

Epic 3: Pattern Editor & Export (Day 2 — Morning)

Goal: Full editing experience and PDF export.

Epic 4: Dashboard & Pattern Library (Day 2 — Afternoon)

Goal: User's home base for managing patterns.

Epic 5: Community Gallery (Day 3 — Morning)

Goal: Social features — sharing and discovery.

Epic 6: Payments & Tier Enforcement (Day 3 — Afternoon)

Goal: Stripe integration and usage limits.

Pricing Model

Target: Free tier as generous trial, Pro for hobbyists (sweet spot at $9), Studio for Etsy sellers and content creators who need commercial rights and bulk tools.

Annual Option: Pro Annual at $79/year (save $29 — ~27% discount) to improve retention.

Go-to-Market Strategy

Pre-Launch (Week 1–2)

1. Craft community seeding: Post pattern examples on r/CrossStitch, r/Embroidery, and Facebook cross-stitch groups
2. TikTok content strategy: Film "photo → pattern → finished piece" transformation videos (highly satisfying visual content)
3. Product Hunt launch prep: Prepare teaser page, PH card, maker comment

Launch (Week 3)

1. Product Hunt launch: "PixelStitch — Turn any photo into a cross-stitch pattern in seconds" with demo video
2. Craft newsletter placements: CrossStitch.com newsletter, LoveCrafts blog feature
3. Influencer partnerships: Send Pro accounts to 5–10 craft YouTubers/Instagrammers for review

Post-Launch Growth (Week 4+)

1. SEO content: Blog posts targeting "cross stitch pattern from photo," "free cross stitch pattern generator," "DMC color converter"
2. Template library: Add 50+ pre-made patterns (free) to drive organic traffic and signups
3. Referral program: "Give a friend 1 free Pro pattern, get 1 free Pro pattern" (viral loop for craft communities)
4. Etsy seller program: Partner with top Etsy pattern sellers to use PixelStitch, co-branded "Made with PixelStitch" badges

Key Channels

• Organic: TikTok/Reels (craft transformations), Pinterest (pattern pins), SEO
• Paid: Meta ads targeting "cross stitch" interest groups ($5–$10 CPM)
• Partnership: LoveCrafts, DMC (official color data partnership)

Success Metrics

Risks & Mitigations

Competitors Analysis

Key Differentiator: PixelStitch is the only modern, web-based, cloud-native cross-stitch pattern generator with community features. Every existing tool is either a clunky desktop application or an abandonware web tool. PixelStitch combines the power of desktop software with the accessibility of a modern SaaS.

Appendix: DMC Color Matching Algorithm

The core IP of PixelStitch is the color quantization + DMC mapping pipeline:

1. Image Preprocessing: Sharp resizes the uploaded image to match the target stitch count dimensions.
2. Median-Cut Quantization: The image's pixel colors are reduced to N colors using median-cut algorithm (fast, predictable results).
3. Dithering (optional): Floyd-Steinberg dithering distributes quantization error to neighboring pixels, producing smoother gradients — critical for realistic portraits.
4. OKLCH Color Matching: Each quantized color is converted to OKLCH color space (perceptually uniform), then nearest-neighbor matched against the DMC 500-color database using Euclidean distance in OKLCH space. This produces visually accurate thread matches (unlike naive hex RGB matching which ignores human color perception).
5. Symbol Assignment: Each DMC color gets a unique symbol from a curated set (inspired by traditional cross-stitch chart conventions).
6. Grid Assembly: Final grid is a 2D array of {dmcId, symbol} per stitch position.

This algorithm runs client-side via a Web Worker for patterns ≤ 200×200 (instant feedback) and server-side via Inngest for larger patterns.

🔗 Brainstormer Review

Score: 7/15 (Feasibility=2, Market-Fit=4, Complexity=1) Verdict: ⏸️ Deferred

Rationale

5 hard-rule defer triggers from the Brainstormer rubric:

1. Background-job orchestration (Inngest) — pattern generation relies on async Inngest step functions for large images (>200x200). Background-job orchestration as a core dependency is a hard defer.
2. 3+ OAuth/integration flows — email/password + Google OAuth + magic links (Supabase Auth) + Stripe webhooks + Resend + Inngest. Six separate third-party integrations.
3. Billing + multi-tenant + customer-portal — Stripe Checkout + Webhooks + Customer Portal + 3-tier subscription (Free/Pro/Studio). Full SaaS payment infrastructure.
4. Drag-and-drop editor — pattern editor uses @dnd-kit for stitch manipulation and collection drag-and-drop.
5. Effort estimates > ~24h — 6 epics across 3 days with 22 functional requirements (10 P0) and 10 non-functional requirements. Realistic estimate is 2+ weeks minimum, not 2-3 days.

Market-Fit is strong (4/5) — cross-stitch is trending, competitors are all desktop-only/abandonware, and the one-click browser pitch is a genuine wedge. But the scope must be radically reduced.

Rescope Suggestion

Client-side-only MVP — no auth, no billing, no community, no database, no bg jobs.

• Browser Canvas/Web Worker handles image upload → color quantization → DMC OKLCH mapping → grid rendering — all client-side, zero server dependencies.
• Pattern editor is a simple HTML5 Canvas grid with zoom/pan (no drag-and-drop stitch editing for v1).
• PDF export via jsPDF client-side.
• Single-page tool with localStorage for saving a few patterns locally.
• No Supabase, no Stripe, no Inngest, no Resend, no Sentry, no PostHog — just a static Next.js app.

This eliminates all 5 hard-rule violations and fits the 2-3 day budget.