Krafta platform architecture and data flow

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PloutusLab/krafta-web/llms.txt

Use this file to discover all available pages before exploring further.

​

Architectural layers

​

Storefront

​

Design Editor

​

API Layer

​

Middleware

export const config = {
  matcher: [
    "/admin/:path*",
    "/workshop/dashboard/:path*",
    "/creator/dashboard/:path*",
  ],
};

​

Database

​

Storage

• designs — customer-uploaded artwork files (PNG, JPG, SVG). Access is mediated via signed URLs generated on demand from server-side API routes; the fileUrl column in DesignUpload stores only the internal Supabase storage path, not a public URL.
• receipts — payment receipt images uploaded during the payment submission flow (PDF or image). Stored under the same private-bucket pattern.

​

Customer order data flow

1. Catalog browse — The customer visits /catalog, which calls GET /api/catalog to fetch active Product records with their ProductVariant children. Each variant carries the basePrice and available WorkshopOffer data needed to display prices.
2. Product detail — At /product/[id] the customer selects a variant and sees the commercial photo carousel from Product.images.
3. Design editor — Navigating to /product/[id]/customize (or /editor) loads the Fabric.js canvas. The customer uploads their artwork via POST /api/upload; the file is stored in the designs bucket (or locally) and a DesignUpload record is created. The canvas generates a preview data URL (previewUrl) when the customer is satisfied.
4. Cart and quote — Adding to cart triggers POST /api/quotes, which creates a Quote with frozen prices and the current USD/Bs exchange rate. Quotes have an expiry timestamp (expiresAt) to prevent stale pricing.
5. Checkout — At /checkout the customer retrieves active PaymentAccount records via GET /api/payments/accounts and selects a bank transfer or Pago Móvil account. They enter the payment reference and upload a receipt image.
6. Payment submission — POST /api/payments creates a PaymentSubmission with status: REPORTED. The order’s own PaymentStatus advances to REPORTED. The receipt file is stored in the receipts bucket.
7. Admin verification — An ADMIN user reviews the submission at /admin/payments. On confirmation, the PaymentSubmission status becomes CONFIRMED, the Order status advances to CONFIRMED, and a PaymentVerificationLog entry is written. On rejection, a rejectionReason is recorded and the customer is notified.
8. Workshop assignment — With payment confirmed, the admin assigns each OrderItem to an appropriate workshop via a ProductionAssignment record. The system matches workshops by their WorkshopOffer for the relevant ProductVariant and their WorkshopCoverage for the delivery state.
9. Production — The workshop operator sees the assignment in their dashboard at /workshop/dashboard. They advance the AssignmentStatus through ACCEPTED → IN_PRODUCTION → READY → HANDED_TO_DELIVERY.
10. Delivery — Once the assignment reaches COMPLETED, the Order is closed. If a CreatorDesignListing was involved, a CreatorEarning record is created and queued for payout.

​

Role enforcement

• Edge middleware (src/middleware.js) — fast JWT verification in the Edge Runtime that blocks unauthenticated or under-privileged requests before they reach any Route Handler. Covers /admin, /workshop/dashboard, and /creator/dashboard.
• API route guards — individual Route Handlers call a requireRole() helper (from src/lib/api-auth.js) that re-verifies the JWT from the krafta-token cookie and checks the role against the endpoint’s requirements. This double-check ensures that even direct API calls without a browser cookie are rejected correctly.