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

# Convex Backend

> A real-time database and serverless functions, built into every project.

By default, every Botflow project comes with [Convex](https://convex.dev) as its backend (you can also create a frontend-only project with no backend). Convex gives your app a typed database, reactive queries, serverless functions, scheduled jobs, and file storage — all defined in TypeScript alongside your frontend code.

## What Convex gives you

* **Real-time database** — a document store where data changes stream to connected clients the moment they happen. No polling, no manual cache invalidation.
* **Typed queries and mutations** — reads and writes are TypeScript functions (`query`, `mutation`). Call them from React with `useQuery` and `useMutation`.
* **Actions** — async server-side functions that can call external APIs, send emails, or do anything you can't do in a pure query.
* **HTTP endpoints** — expose individual functions as REST endpoints for webhooks and third-party integrations.
* **Scheduled jobs** — run a function on a recurring cron schedule or delay it to a specific time.
* **File storage** — upload, store, and serve files through the same TypeScript API.

## Projects without a backend

Not every app needs a database. When you create a project you can choose **No Backend** — a frontend-only app (a landing page, a marketing site, a calculator, a client-side tool) with no Convex deployment at all.

In a frontend-only project:

* There's **no `convex/` folder** and **no Database tab**.
* Features that depend on the backend — [Authentication](/docs/features/auth), [Payments](/docs/features/payments), and the data tools above — aren't available.
* The agent won't pull in Convex packages, so the app stays lean and purely client-side.

Choose it when you know you only need a static or client-side app. If you later need user accounts, saved data, or payments, start a project with a Convex backend.

## Accessing the database in the workspace

Click the **Database** tab at the top of the workspace to open the embedded Convex dashboard.

From here you can:

* **Browse tables** — see all documents in every table, paginated
* **Run queries** — call any query or mutation function with custom arguments
* **Inspect logs** — view real-time function execution logs
* **Manage scheduled jobs** — see pending and past cron jobs
* **View the schema** — inspect the current `schema.ts` definition

<Note>
  The Database tab shows the real Convex dashboard embedded in an iframe. Any changes you make here are immediately reflected in your live app.
</Note>

## How Convex is wired up per plan

| Plan     | What you get                                                                                                                                               |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Free** | Bring your own Convex account. Connect it in [Settings → Connections](/docs/features/settings#connections) and Botflow injects `VITE_CONVEX_URL` automatically. |
| **Pro**  | A platform-managed Convex deployment per project. No setup needed — just build.                                                                            |
| **Max**  | Same as Pro, with higher function limits and priority support.                                                                                             |

## Connecting your own Convex (Free plan)

1. Go to [dashboard.convex.dev](https://dashboard.convex.dev) and create a free Convex account.
2. Create a new deployment in the Convex dashboard.
3. In Botflow, go to **Settings → Connections** and click **Connect Convex**.
4. Paste your Convex deployment URL.

Botflow will inject the URL as an environment variable (`VITE_CONVEX_URL`). The AI agent automatically uses this variable when generating Convex client code.

<Note>
  After connecting Convex, the **Database** tab becomes available in your workspace. See [Workspace → Database](/docs/features/workspace#right-panel--database) for details on using the Convex dashboard.
</Note>

## Editing data through the agent

Beyond writing functions, the AI agent can work with your database **directly** — handy for seeding sample data, debugging, or one-off fixes without building a UI for them. Just ask:

```
Seed the products table with 5 realistic example rows
```

```
Show me the 10 most recent orders
```

```
Delete the test user with email demo@example.com
```

Under the hood the agent can list your tables, read documents (with pagination), and insert, update, or delete rows. It also reads your **function execution logs**, so you can ask it to "check why the createOrder mutation is failing" and it will look at the real error output.

<Warning>
  Direct writes change live data immediately. The agent will confirm before destructive changes, but treat it like running SQL by hand — double-check before seeding or deleting against data you care about.
</Warning>

## Writing Convex code

Convex schema, queries, mutations, and actions live in the `convex/` directory of your project. The AI agent writes and edits these files like any other source file.

A typical Convex file structure:

```
convex/
  schema.ts       # Table definitions with validators
  tasks.ts        # Queries and mutations for the tasks table
  auth.config.ts  # Auth configuration (if you've added authentication)
  _generated/     # Auto-generated API types (don't edit)
```

Example `convex/tasks.ts`:

```typescript theme={null}
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tasks").order("desc").collect();
  },
});

export const create = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", { text: args.text, completed: false });
  },
});
```

Call these from your React component:

```tsx theme={null}
import { useQuery, useMutation } from "convex/react";
import { api } from "../convex/_generated/api";

export function TaskList() {
  const tasks = useQuery(api.tasks.list);
  const create = useMutation(api.tasks.create);
  // ...
}
```

## Prompting the AI to use Convex

The agent understands Convex and will use it automatically in any project with a Convex backend. You can be explicit:

```
Add a Convex mutation that marks a task as complete. Update the task list component to call it when the checkbox is clicked.
```

```
Add a scheduled job that sends a daily digest email via Resend at 9am UTC
```

```
Create a Convex HTTP endpoint at /api/webhook/stripe that processes payment events
```