Cartde Technical Documentation

Complete internal documentation for the Cartde AI-powered e-commerce assistant platform. Built on Cloudflare Workers with D1 database.

System Architecture

Cartde is built as a serverless platform leveraging Cloudflare's edge infrastructure for global performance and scalability.

Tech Stack

Deployment URLs

Services Overview

The platform is organized into logical service modules, each handling specific functionality.

API Route Modules

Database Overview

Cartde uses Cloudflare D1, a distributed SQLite database. The schema is organized across 6 development phases with 47 tables total.

Schema Phases

Core Database Tables

users

Stores user accounts and authentication data.

workspaces

Multi-tenant workspace containers for stores/businesses.

products

Product catalog with full e-commerce attributes.

conversations

Chat conversation sessions between customers and AI/agents.

messages

Individual messages within conversations.

Analytics & Metrics Tables

analytics_events

Real-time event tracking for user actions.

analytics_daily

Pre-aggregated daily metrics for dashboards.

Marketing & Automation Tables

carts

Shopping cart tracking for abandonment recovery.

leads

Lead capture from chat and forms.

webhooks

Outgoing webhook configurations.

Authentication API

User authentication using JWT tokens. Tokens expire after 7 days by default.

{
  "email": "user@example.com",
  "password": "min8chars",
  "name": "John Doe"
}

{
  "success": true,
  "data": {
    "user": { "id": "abc123", "email": "user@example.com", "name": "John Doe" },
    "token": "eyJhbGciOiJIUzI1NiJ9..."
  }
}

{
  "email": "user@example.com",
  "password": "yourpassword"
}

Authorization: Bearer <jwt_token>

Workspaces API

Manage workspaces (stores/businesses). All workspace routes require authentication.

{
  "name": "My Store",
  "settings": {
    "timezone": "UTC",
    "currency": "USD",
    "locale": "en-US"
  }
}

{
  "success": true,
  "data": {
    "id": "wsp_abc123",
    "name": "My Store",
    "slug": "my-store",
    "apiKey": "ck_xxxxxxxxxxxxxxxxxxxx",  // Only shown once!
    "settings": { ... }
  }
}

Products API

Manage product catalog for AI context.

{
  "name": "Product Name",
  "description": "Full product description",
  "shortDescription": "Brief description",
  "price": 9999,           // Price in cents ($99.99)
  "sku": "SKU-001",
  "stockStatus": "in_stock",
  "categories": ["Electronics"],
  "tags": ["sale", "featured"]
}

Chat & Widget API

Widget chat endpoints use API key authentication via the X-API-Key header.

X-API-Key: ck_your_api_key_here
Content-Type: application/json

{
  "sessionId": "visitor-uuid",
  "message": "What products do you have?",
  "conversationId": null,  // null for new conversation
  "metadata": {
    "pageUrl": "https://example.com/shop",
    "userAgent": "Mozilla/5.0..."
  }
}

{
  "success": true,
  "data": {
    "conversationId": "conv_abc123",
    "message": {
      "id": "msg_xyz789",
      "content": "We have several products available...",
      "role": "assistant",
      "products": [
        { "id": "prod_1", "name": "Widget", "price": 9999, "currency": "USD" }
      ]
    },
    "intent": "product_search"
  }
}

Analytics API

Dashboard analytics and metrics.

{
  "success": true,
  "data": {
    "totals": {
      "conversations": 150,
      "messages": 1200,
      "products": 45,
      "faqs": 20
    },
    "trends": {
      "conversationsThisWeek": 25,
      "conversationChange": 15.5
    }
  }
}

Integrations API

Connect external e-commerce platforms to sync products.

{
  "storeUrl": "https://yourstore.com",
  "consumerKey": "ck_woocommerce_key",
  "consumerSecret": "cs_woocommerce_secret"
}

{
  "products": [
    { "name": "Product 1", "description": "...", "price": 9999, "sku": "SKU-001" },
    { "name": "Product 2", "description": "...", "price": 14999, "sku": "SKU-002" }
  ]
}

Cloudflare Infrastructure

Account Details

Bindings

# wrangler.toml
name = "cartde-api"
main = "src/index.ts"
compatibility_date = "2024-11-01"
account_id = "643cab4b2d055eed7c5e8c813ca4c6cd"

[[d1_databases]]
binding = "DB"
database_name = "cartde-db"
database_id = "67fe7ff6-84c6-4d5f-89d9-5773e771f7e2"

[ai]
binding = "AI"

Environment Variables

Deployment Commands

Deploy API

cd apps/api
CLOUDFLARE_ACCOUNT_ID=643cab4b2d055eed7c5e8c813ca4c6cd npx wrangler deploy

Deploy Widget SDK

cd packages/widget-sdk
npm run build
CLOUDFLARE_ACCOUNT_ID=643cab4b2d055eed7c5e8c813ca4c6cd npx wrangler pages deploy dist --project-name=cartde-widget

Deploy Dashboard

cd apps/web
NEXT_PUBLIC_API_URL=https://cartde-api.cartde.workers.dev npm run build
CLOUDFLARE_ACCOUNT_ID=643cab4b2d055eed7c5e8c813ca4c6cd npx wrangler pages deploy out --project-name=cartde-web

Database Migrations

# Run a migration file
CLOUDFLARE_ACCOUNT_ID=643cab4b2d055eed7c5e8c813ca4c6cd \
  npx wrangler d1 execute cartde-db --remote --file=migrations/0001_initial.sql

# Execute SQL directly
CLOUDFLARE_ACCOUNT_ID=643cab4b2d055eed7c5e8c813ca4c6cd \
  npx wrangler d1 execute cartde-db --remote --command="SELECT * FROM users LIMIT 5"

Set Secrets

CLOUDFLARE_ACCOUNT_ID=643cab4b2d055eed7c5e8c813ca4c6cd \
  npx wrangler secret put JWT_SECRET