> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Welcome to the Twigz Backend API Documentation

# Welcome to Twigz Backend API

The Twigz Backend API is a comprehensive platform for building marketplace applications with stores, customers, orders, payments, and more. Built on **Convex** for real-time functionality and scalability.

## 🚀 What is Twigz?

Twigz is a modern marketplace platform that connects customers with local stores. Our API provides everything you need to build:

* **🏪 Store Management**: Registration, products, inventory, reviews
* **👥 Customer Experience**: Shopping carts, orders, payments, social features
* **💳 Payment Processing**: Stripe integration with marketplace fees
* **📱 Real-time Features**: Live notifications, order tracking
* **🛡️ Admin Tools**: Platform management, payouts, moderation

## ⚡ Key Features

<CardGroup cols={2}>
  <Card title="Real-time Everything" icon="bolt" href="/essentials/real-time">
    Built on Convex for instant updates across all clients
  </Card>

  <Card title="Stripe Marketplace" icon="credit-card" href="/api-reference/customers/payments">
    Complete payment processing with automatic commission handling
  </Card>

  <Card title="FCM/APNs Notifications" icon="bell" href="/api-reference/shared/notifications">
    Native push notifications without Expo dependency
  </Card>

  <Card title="Advanced Search" icon="magnifying-glass" href="/api-reference/shared/search">
    Comprehensive search across stores, products, and customers
  </Card>
</CardGroup>

## 🏗️ Architecture Overview

```mermaid theme={null}
graph TB
    A[Mobile Apps] --> B[Convex Backend]
    C[Web Dashboard] --> B
    B --> D[Database]
    B --> E[Stripe API]
    B --> F[FCM/APNs]
    B --> G[File Storage]
    
    subgraph "Core Services"
        H[Authentication]
        I[Real-time Sync]
        J[Payment Processing]
        K[Notifications]
    end
    
    B --> H
    B --> I
    B --> J
    B --> K
```

## 📊 API Statistics

<div className="grid grid-cols-2 md:grid-cols-4 gap-4 my-6">
  <div className="text-center p-4 border rounded-lg">
    <div className="text-2xl font-bold text-primary">150+</div>
    <div className="text-sm text-gray-600">API Functions</div>
  </div>

  <div className="text-center p-4 border rounded-lg">
    <div className="text-2xl font-bold text-primary">8</div>
    <div className="text-sm text-gray-600">Core Modules</div>
  </div>

  <div className="text-center p-4 border rounded-lg">
    <div className="text-2xl font-bold text-primary">99.9%</div>
    <div className="text-sm text-gray-600">Uptime</div>
  </div>

  <div className="text-center p-4 border rounded-lg">
    <div className="text-2xl font-bold text-primary">\< 100ms</div>
    <div className="text-sm text-gray-600">Avg Response</div>
  </div>
</div>

## 🎯 Getting Started

<Steps>
  <Step title="Authentication Setup">
    Configure Clerk authentication for your application
  </Step>

  <Step title="Install SDK">
    Install the Convex client in your application
  </Step>

  <Step title="Make Your First Call">
    Test the API with a simple query
  </Step>

  <Step title="Explore Features">
    Dive into stores, products, and customer management
  </Step>
</Steps>

## 💡 Quick Example

Here's how easy it is to get started:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ConvexReactClient } from "convex/react";
  import { api } from "./convex/_generated/api";

  const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

  // Get all stores
  const stores = await convex.query(api.customers.explore.getStoresWithPagination, {
    paginationOpts: { numItems: 20, cursor: null }
  });

  console.log(`Found ${stores.page.length} stores`);
  ```

  ```javascript JavaScript theme={null}
  import { ConvexHttpClient } from "convex/browser";

  const convex = new ConvexHttpClient(process.env.CONVEX_URL);

  // Create a product
  const productId = await convex.mutation("shared.products.createProduct", {
    name: "Pizza Margherita",
    description: "Classic Italian pizza",
    category: "food-category-id",
    price: 15.99,
    isActive: true,
    primaryImage: "image-storage-id"
  });
  ```

  ```python Python theme={null}
  import requests

  # Using HTTP API
  response = requests.post(
      f"{CONVEX_URL}/api/query",
      json={
          "path": "shared.categories.getParents",
          "args": {}
      },
      headers={"Authorization": f"Bearer {token}"}
  )

  categories = response.json()
  ```

  ```curl cURL theme={null}
  curl -X POST "https://your-convex-url.convex.cloud/api/query" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -d '{
      "path": "shared.categories.getParents",
      "args": {}
    }'
  ```
</CodeGroup>

## 🔗 Useful Links

<CardGroup cols={2}>
  <Card title="Convex Documentation" icon="book" href="https://docs.convex.dev">
    Learn more about the Convex platform
  </Card>

  <Card title="Stripe Documentation" icon="stripe" href="https://stripe.com/docs">
    Payment processing documentation
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/your-org/twigz-backend">
    View the source code and contribute
  </Card>

  <Card title="Community Support" icon="discord" href="https://discord.gg/twigz">
    Join our developer community
  </Card>
</CardGroup>

## 📞 Support

Need help? We're here for you:

* **📧 Email**: [support@twigz.app](mailto:support@twigz.app)
* **💬 Discord**: [Join our community](https://discord.gg/twigz)
* **📖 Docs**: Browse this documentation
* **🐛 Issues**: [Report on GitHub](https://github.com/your-org/twigz-backend/issues)

***

<Note>
  This API is currently in **beta**. While we maintain high stability, some endpoints may change. We'll provide migration guides for any breaking changes.
</Note>

<Note>
  **Search Note**: Search functionality is available in production deployments. In local preview mode, search may show as "not available" - this is normal and will work when deployed.
</Note>