Skip to main content

Complete WIKI Summary for ChatGPT

COPY-PASTE READY FORMAT FOR AI

Project Overview​

Project: Nekomata - Multi-brand photo printing service Core Product: 89mm square high-quality photo prints Target: Cat photos, Japanese art prints, future dog photos Architecture: Next.js + Cloudflare Workers + Shopify + Firebase

Business Requirements​

  • Multi-brand isolation: neko (cats), tokinoe (Japanese art), dog (future)
  • Print specifications: 89mm × 89mm square, 1051×1051px @ 300DPI, glossy photo paper
  • PII policy: All personal data stored in Shopify only, D1 database has zero PII
  • Factory app: Temporary data fetch from Shopify API only (no storage)
  • Performance targets: 100ms page load, 2s order processing (Queue), 99.9% uptime, 1000 concurrent users, 0% 429 errors

Technical Architecture​

Frontend​

  • Web: Next.js with React
  • Mobile: React Native (Expo)
  • Admin: Electron app for factory operations

Backend & Infrastructure​

  • API: Cloudflare Workers (BFF pattern)
  • Queue System: 🎉 Cloudflare Queues + Workers (IMPLEMENTED) - Solves Shopify API rate limits
  • Database: Cloudflare D1 (SQLite) - NO PII
  • Storage: Cloudflare R2 for images
  • CDN: Cloudflare global edge network
  • Authentication: Firebase Auth
  • E-commerce: Shopify (Headless) - ALL PII HERE

API Constraints → 🎉 SOLVED by Queue System​

  • Shopify REST API: 40 requests/minute → ✅ Queue System eliminates 429 errors
  • Shopify GraphQL: 1000 cost/minute → ✅ Queue-based processing within limits
  • Order Processing: ✅ Under 2 seconds response (immediate queuing + background processing)
  • Cloudflare Workers: 50ms CPU time, 128MB memory
  • Firebase Auth: 50,000 MAU free tier

Database Design (D1 - PII-Free)​

-- Brand isolation with brand column in all tables
CREATE TABLE photos (id, brand, firebase_uid, shopify_customer_id, image_url, status, metadata);
CREATE TABLE orders (id, brand, firebase_uid, shopify_order_id, photo_ids, print_settings, status);
CREATE TABLE print_jobs (id, brand, order_id, factory_id, status, print_data, timestamps);

Security Implementation​

  • Data isolation: Complete brand separation via brand column
  • Authentication flow: Firebase Auth → JWT validation → Shopify Customer ID mapping
  • PII compliance: Zero personal data in D1, all PII in Shopify
  • Factory access: Temporary API calls only, no data persistence
  • Rate limiting: Queue system for API constraints

Domain & Infrastructure​

Operations & Testing​

5-Phase Testing Strategy​

  1. Phase 1: Infrastructure tests (Cloudflare D1, R2, Workers, Pages, DNS)
  2. Phase 2: Authentication & security (Cloudflare Access, Firebase Auth, App Check)
  3. Phase 3: Core features (Image processing, brand management)
  4. Phase 4: External integrations (Shopify API, email systems)
  5. Phase 5: End-to-end user journeys

Monitoring & Quality​

  • Performance monitoring: Real-time metrics, alerting thresholds
  • Quality standards: under 5% duplicate content, 100% link validity, 2-minute information discovery
  • Documentation: AI-optimized structure with machine-readable rules
  • Deployment: Automated via npm run deploy:cloudflare

Brand Management​

  • Multi-tenant architecture: Single codebase, brand-specific configurations
  • UI customization: Brand colors, logos, messaging per subdomain
  • Email templates: Shopify Liquid templates with brand detection via order metafields
  • Print specifications: Consistent 89mm square across all brands

Development Workflow​

  • Repository: Git-based with comprehensive WIKI documentation
  • Deployment: Cloudflare Pages with automatic builds
  • Testing: Phase-based validation with automated monitoring
  • Documentation: AI-readable format with YAML machine rules
  • Quality: Quantitative metrics, no subjective assessments

Key Constraints & Solutions​

  • Shopify API limits: ✅ SOLVED - Cloudflare Queues + Workers implementation eliminates all 429 errors
  • Order processing: ✅ OPTIMIZED - Immediate response (≤ 2s) + background processing (30s)
  • PII compliance: Strict Shopify-only policy with D1 validation
  • Performance: Edge computing, aggressive caching, CDN optimization
  • Scalability: Auto-scaling infrastructure, global edge deployment
  • Brand isolation: Database-level separation with consistent brand column
  • Reliability: ✅ ENHANCED - Auto-retry + Dead Letter Queue + Idempotency

Success Metrics​

  • Monthly orders: 1000 orders by month 6
  • Customer satisfaction: 4.5/5 rating
  • Repeat rate: 30%+
  • Technical performance: All targets met consistently
  • Operational efficiency: 30min/week maintenance time

Implementation Status​

  • DNS & Infrastructure: Complete and operational
  • Queue System: ✅ Cloudflare Queues + Workers IMPLEMENTED - API rate limiting solved
  • Documentation: AI-optimized structure implemented
  • Testing Framework: 5-phase strategy defined
  • Quality Standards: Quantitative metrics established
  • API Reliability: ✅ 429 errors eliminated, ≤ 2s order response achieved
  • Next Steps: Core application development and deployment