bkend-guides

name	bkend-guides
classification	C
description	bkend.ai operational guides, troubleshooting, and platform comparison. Covers migration guides, performance optimization, testing strategy, common error solutions, and FAQ. Triggers: migration, troubleshoot, FAQ, performance, error handling, comparison, 마이그레이션, 문제해결, 자주 묻는 질문, 성능, 에러, マイグレーション, トラブルシューティング, FAQ, パフォーマンス, 迁移, 故障排除, 常见问题, 性能, 错误处理, migracion, solucion de problemas, preguntas frecuentes, rendimiento, migration, depannage, FAQ, performance, gestion des erreurs, Migration, Fehlerbehebung, FAQ, Leistung, Fehlerbehandlung, migrazione, risoluzione problemi, FAQ, prestazioni, gestione errori Do NOT use for: authentication implementation (use bkend-auth), database schema design (use bkend-data), security setup (use bkend-security)
user-invocable	true
argument-hint
allowed-tools	["read_file","write_file","replace","glob","grep_search","run_shell_command","web_fetch"]
imports	[]
agents	{"backend":"bkend-expert"}
context	session
memory	project
pdca-phase	all

bkend-guides

bkend.ai operational guides, troubleshooting, and platform comparison

1. Platform Comparison

Feature	bkend.ai	Firebase	Supabase
Database	MongoDB Atlas (NoSQL)	Firestore (NoSQL) / RTDB	PostgreSQL (SQL)
Auth	Built-in JWT + Social + MFA	Firebase Auth (full suite)	GoTrue (JWT + Social)
MCP Support	Native (first-class)	None	Community plugins
Real-time	Planned (WebSocket)	Built-in (Firestore listeners)	Built-in (Postgres changes)
File Storage	Integrated	Cloud Storage	S3-compatible
Edge Functions	Planned	Cloud Functions	Deno Edge Functions
Schema	Schemaless / flexible	Schemaless	Rigid SQL migrations
Pricing	Usage-based (API calls)	Spark (free) / Blaze (pay-as-you-go)	Free tier + Pro ($25/mo)
Open Source	No	No	Yes
AI Integration	Native MCP + prompt workflows	Vertex AI extensions	pgvector + AI plugins
Best For	AI-assisted rapid prototyping	Mobile-first apps, Google ecosystem	SQL-heavy apps, open source

When to Choose bkend.ai

• You want AI-assisted development with Gemini CLI, Claude Code, or Cursor via MCP
• You prefer schemaless / flexible data models without migration headaches
• You need rapid prototyping with minimal configuration
• Your team is comfortable with REST APIs and does not need GraphQL

When to Choose Alternatives

• Firebase: You need mature real-time capabilities, deep Google Cloud integration, or are building primarily for mobile within the Google ecosystem
• Supabase: You need SQL, full-text search, row-level security with PostgreSQL policies, or prefer an open-source solution

---

2. Migration Guides

2.1 From Firebase (Planned)

This migration guide is under development. Key considerations:

• Firestore to bkend.ai: Export Firestore collections as JSON, then import into bkend tables via the REST API or MCP tools
• Firebase Auth to bkend Auth: Re-register users with email/password or social providers; there is no automatic migration path for password hashes
• Cloud Functions to bkend: Rewrite triggers as webhook handlers (webhooks are planned)
• Cloud Storage to bkend Storage: Re-upload files using the bkend storage API

2.2 From Supabase (Planned)

This migration guide is under development. Key considerations:

• PostgreSQL to bkend.ai: Export tables as JSON; flatten relational data into document-style schemas
• Supabase Auth to bkend Auth: Re-register users; JWT tokens are not transferable
• Edge Functions to bkend: Rewrite as API route handlers in your frontend framework
• Supabase Storage to bkend Storage: Re-upload files using the bkend storage API
• RLS Policies: Translate PostgreSQL RLS policies to bkend RBAC rules (admin/user/self/guest)

---

3. Performance Optimization

3.1 Use Indexes on Frequently Queried Fields

Create indexes on fields that appear in filter and sort parameters. Common candidates:

• authorId -- for user-scoped queries
• status -- for filtering by state
• createdAt -- for chronological sorting
• email -- for user lookups

Use the bkend Console or MCP tool to create indexes:

> Create an index on the "posts" table for the "authorId" field
> Create a compound index on "posts" for "status" and "createdAt"

3.2 Limit Query Results

Always set a limit parameter. The maximum allowed value is 100 records per request.

GET /v1/data/posts?limit=20

If no limit is specified, the default is 20. Never rely on fetching all records at once.

3.3 Use Cursor Pagination (Not Offset)

Offset-based pagination (skip) degrades performance on large datasets because the database must scan and discard skipped records.

Avoid (offset pagination):

GET /v1/data/posts?skip=1000&limit=20

Prefer (cursor pagination):

GET /v1/data/posts?cursor=<last-record-id>&limit=20

Cursor pagination is O(1) regardless of page depth.

3.4 Cache with TanStack Query

Configure appropriate staleTime and gcTime for your data:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,    // 5 minutes before refetch
      gcTime: 30 * 60 * 1000,      // 30 minutes in cache
      retry: 2,                     // Retry failed requests twice
      refetchOnWindowFocus: false,  // Disable auto-refetch on focus
    },
  },
});

For frequently changing data (like feeds), use shorter staleTime:

useQuery({
  queryKey: ["feed"],
  queryFn: fetchFeed,
  staleTime: 30 * 1000, // 30 seconds
});

3.5 Denormalize Frequently Joined Data

bkend.ai uses MongoDB (NoSQL), so joins are not native. Instead of querying multiple tables:

Avoid:

// 1. Fetch post
// 2. Fetch author by post.authorId
// 3. Fetch comments by post._id
// 4. Fetch each comment's author

Prefer: Embed frequently accessed data at write time:

{
  "title": "My Post",
  "content": "...",
  "author": {
    "id": "user_123",
    "name": "Alice",
    "avatar": "https://..."
  },
  "commentsCount": 5,
  "likesCount": 12
}

Update embedded data when the source changes (e.g., when a user updates their name).

---

4. Testing Strategy

4.1 Unit Tests: Business Logic with Mock bkendFetch

Test business logic in isolation by mocking the API client.

// __tests__/services/order-state-machine.test.ts
import { canTransition } from "@/application/services/order-state-machine";

describe("Order State Machine", () => {
  it("allows draft -> pending", () => {
    expect(canTransition("draft", "pending")).toBe(true);
  });

  it("blocks draft -> shipped", () => {
    expect(canTransition("draft", "shipped")).toBe(false);
  });

  it("allows paid -> cancelled", () => {
    expect(canTransition("paid", "cancelled")).toBe(true);
  });

  it("blocks completed -> any", () => {
    expect(canTransition("completed", "pending")).toBe(false);
    expect(canTransition("completed", "cancelled")).toBe(false);
  });
});

4.2 Integration Tests: API Calls with Dev Environment

Test actual API interactions against the dev environment.

// __tests__/integration/posts-api.test.ts
import { bkendFetch } from "@/infrastructure/api/client";

describe("Posts API", () => {
  let postId: string;

  it("creates a post", async () => {
    const res = await bkendFetch("/v1/data/posts", {
      method: "POST",
      body: JSON.stringify({
        title: "Test Post",
        content: "Integration test content",
        authorId: "test_user_id",
        status: "draft",
      }),
    });
    expect(res.success).toBe(true);
    postId = res.data._id;
  });

  it("reads the created post", async () => {
    const res = await bkendFetch(`/v1/data/posts/${postId}`);
    expect(res.data.title).toBe("Test Post");
  });

  afterAll(async () => {
    if (postId) {
      await bkendFetch(`/v1/data/posts/${postId}`, { method: "DELETE" });
    }
  });
});

4.3 E2E Tests: Full Flow with Test Data

Test complete user flows from login to feature completion.

// e2e/blog-post-flow.spec.ts (Playwright)
import { test, expect } from "@playwright/test";

test("create and publish a blog post", async ({ page }) => {
  // Login
  await page.goto("/login");
  await page.fill('[name="email"]', "[e-mail]");
  await page.fill('[name="password"]', "testpassword123");
  await page.click('button[type="submit"]');
  await expect(page).toHaveURL("/dashboard");

  // Create post
  await page.click('a[href="/posts/new"]');
  await page.fill('[name="title"]', "E2E Test Post");
  await page.fill('[name="content"]', "This is an E2E test.");
  await page.click('button:has-text("Publish")');

  // Verify post appears in list
  await page.goto("/posts");
  await expect(page.locator("text=E2E Test Post")).toBeVisible();
});

---

5. Webhooks (Planned)

Webhooks are under development for a future bkend.ai release.

5.1 Table Change Notifications (Planned)

Receive HTTP callbacks when records are created, updated, or deleted in a table.

{
  "event": "table.record.created",
  "table": "orders",
  "record": { "_id": "order_123", "status": "pending", "..." : "..." },
  "timestamp": "2026-01-15T10:30:00Z",
  "projectId": "proj_abc123",
  "environment": "prod"
}

5.2 Auth Event Webhooks (Planned)

Receive callbacks for authentication events.

{
  "event": "auth.user.registered",
  "user": { "_id": "user_456", "email": "[e-mail]" },
  "timestamp": "2026-01-15T10:30:00Z",
  "projectId": "proj_abc123",
  "environment": "prod"
}

Planned auth events: auth.user.registered, auth.user.login, auth.user.logout, auth.user.deleted, auth.token.refreshed.

---

6. Realtime (Planned)

Real-time subscriptions are under development for a future bkend.ai release.

6.1 WebSocket Subscriptions (Planned)

Subscribe to live data changes via WebSocket connections.

// Planned API (not yet available)
// import { bkendRealtime } from "@/infrastructure/realtime/client";
//
// const channel = bkendRealtime.subscribe("posts", {
//   filter: { status: "published" },
//   events: ["insert", "update", "delete"],
// });
//
// channel.on("insert", (record) => {
//   console.log("New post:", record);
// });
//
// channel.on("update", (record) => {
//   console.log("Updated post:", record);
// });
//
// // Unsubscribe when done
// channel.unsubscribe();

---

7. Error Handling Guide

7.1 Error Response Format

All bkend.ai API errors follow a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

7.2 Common Errors

Error Code	HTTP Status	Description	Resolution
VALIDATION_ERROR	400	Request body failed schema validation	Check required fields and data types
DUPLICATE_KEY	400	A record with the same unique field already exists	Use a different value for the unique field
INVALID_CREDENTIALS	401	Email or password is incorrect	Verify login credentials
TOKEN_EXPIRED	401	Access token has expired	Refresh the token using /v1/auth/token/refresh
PERMISSION_DENIED	403	User does not have access to this resource	Check RBAC role (admin/user/self/guest)
TABLE_NOT_FOUND	404	The specified table does not exist	Verify table name and environment
RATE_LIMIT_EXCEEDED	429	Too many requests in a short period	Wait and retry with exponential backoff

7.3 Error Handling Pattern

// infrastructure/api/error-handler.ts

export class BkendError extends Error {
  code: string;
  status: number;
  details: any[];

  constructor(response: any, status: number) {
    super(response.error?.message || "Unknown bkend error");
    this.code = response.error?.code || "UNKNOWN_ERROR";
    this.status = status;
    this.details = response.error?.details || [];
  }
}

export async function handleBkendResponse<T>(res: Response): Promise<T> {
  const body = await res.json();

  if (!res.ok) {
    throw new BkendError(body, res.status);
  }

  return body;
}

// Usage in components:
// try {
//   await createPost(data);
// } catch (error) {
//   if (error instanceof BkendError) {
//     if (error.code === "VALIDATION_ERROR") {
//       showValidationErrors(error.details);
//     } else if (error.code === "TOKEN_EXPIRED") {
//       await refreshToken();
//       await createPost(data); // retry
//     }
//   }
// }

---

8. Connection Troubleshooting

If you cannot connect to the bkend.ai API, follow these five steps:

Step 1: Check X-Project-Id Header

Ensure the X-Project-Id header is set to a valid project ID.

curl -v https://api-client.bkend.ai/v1/data/posts \
  -H "X-Project-Id: proj_abc123" \
  -H "X-Environment: dev" \
  -H "X-API-Key: <your-api-key>"

If you receive PROJECT_NOT_FOUND, verify the project ID in the bkend Console under Project Settings.

Step 2: Check X-Environment Header

The X-Environment value must be one of: dev, staging, or prod. A missing or invalid environment header results in a 400 Bad Request.

Step 3: Check API Key

API keys are scoped per environment. An API key created for dev will not work for prod.

• Verify the key is active in Console > Project > Settings > API Keys
• Check that the key matches the target environment
• Ensure the key has not been revoked

Step 4: Check CORS Configuration

If making requests from a browser, ensure your domain is allowed in the CORS settings.

• Navigate to Console > Project > Settings > CORS
• Add your frontend domain (e.g., http://localhost:3000 for development)
• For production, add your actual domain (e.g., https://myapp.com)

Common CORS error symptoms:

• Browser console shows Access-Control-Allow-Origin errors
• Requests work in Postman or curl but fail in the browser
• Preflight (OPTIONS) requests are rejected

Step 5: Check Network

• Verify your internet connection is active
• Check if api-client.bkend.ai is reachable: curl -I https://api-client.bkend.ai/health
• If behind a corporate firewall or VPN, ensure api-client.bkend.ai and api.bkend.ai are not blocked
• Check the bkend.ai status page for any ongoing incidents

---

9. Auth Troubleshooting

Step 1: Token Expired

Symptom: API returns 401 with code TOKEN_EXPIRED.

Solution: Refresh the access token using the refresh token endpoint.

curl -X POST https://api-client.bkend.ai/v1/auth/token/refresh \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: proj_abc123" \
  -H "X-Environment: dev" \
  -d '{"refreshToken": "<your-refresh-token>"}'

Access tokens expire after 1 hour. Implement auto-refresh in your HTTP client interceptor (see bkend-quickstart for middleware examples).

Step 2: Invalid Token Format

Symptom: API returns 401 with code INVALID_TOKEN.

Solution: Verify the Authorization header format:

• Correct: Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
• Wrong: Authorization: eyJhbGciOiJIUzI1NiIs... (missing Bearer prefix)
• Wrong: Authorization: Bearer undefined (token variable is undefined)

Check that your token storage and retrieval logic is working correctly.

Step 3: MFA Required

Symptom: Login returns 403 with code MFA_REQUIRED and a mfaToken in the response.

Solution: Complete the MFA verification step:

curl -X POST https://api-client.bkend.ai/v1/auth/mfa/verify \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: proj_abc123" \
  -H "X-Environment: dev" \
  -d '{"mfaToken": "<mfa-token-from-login>", "code": "123456"}'

The MFA code is a 6-digit TOTP code from the user's authenticator app.

Step 4: Account Locked

Symptom: Login returns 403 with code ACCOUNT_LOCKED.

Solution: The account has been locked due to too many failed login attempts. Options:

• Wait for the lockout period to expire (default: 30 minutes)
• Reset the password via the forgot password flow
• Contact the project administrator to unlock the account via the Console

---

10. FAQ

Q: Can I use GraphQL with bkend.ai?

A: No. bkend.ai provides a REST API only. There is no GraphQL endpoint. Use the filter, sort, select, and limit query parameters to shape your queries. For complex data needs, make multiple REST calls and combine the results on the client side.

Q: What database does bkend.ai use?

A: bkend.ai uses MongoDB Atlas as its underlying database. All data is encrypted at rest with AES-256 encryption. You do not manage the database directly; all access is through the bkend REST API or MCP tools.

Q: Can I create tables via the REST API?

A: No. Tables can only be created through the bkend Console (web UI) or via MCP tools (Gemini CLI, Claude Code, Cursor). The REST API is for data operations (CRUD) on existing tables only.

Q: What is the maximum query limit?

A: The maximum limit parameter value is 100 records per request. The default limit is 20. To retrieve more records, use cursor-based pagination to fetch subsequent pages.

Q: How long are refresh tokens valid?

A: Refresh tokens are valid for 30 days from the time of issuance. After 30 days, the user must log in again to obtain a new refresh token. Access tokens expire after 1 hour.

Q: Is there an official SDK for bkend.ai?

A: No. There is no official SDK at this time. Instead, use the bkendFetch REST API wrapper pattern documented in the bkend-quickstart and bkend-cookbook skills. This lightweight approach works with any language or framework that supports HTTP requests.

Q: What column types are supported?

A: bkend.ai supports 7 column types:

Type	Description	Example
string	Text data	"Hello World"
int	Integer numbers	42
double	Floating-point numbers	3.14
bool	Boolean values	true / false
date	ISO 8601 date strings	"2026-01-15T10:30:00Z"
object	Nested JSON objects	{"street": "123 Main St"}
array	JSON arrays	["tag1", "tag2"]

Important: There is no generic number type. Use int for whole numbers and double for decimal values.

Q: Can I use bkend.ai with frameworks other than Next.js and Flutter?

A: Yes. Since bkend.ai is a REST API, it works with any framework or language. The cookbook examples use Next.js and Flutter, but the same API calls work with React Native, Vue.js, Svelte, Angular, iOS (Swift), Android (Kotlin), Python, Go, or any HTTP-capable environment. Adapt the bkendFetch pattern to your language's HTTP client.

Q: How do I handle file uploads?

A: Use the bkend storage API endpoint:

curl -X POST https://api-client.bkend.ai/v1/storage/upload \
  -H "X-Project-Id: proj_abc123" \
  -H "X-Environment: dev" \
  -H "X-API-Key: <your-api-key>" \
  -F "file=@/path/to/image.jpg"

The response includes a url field with the publicly accessible file URL. For detailed storage patterns, use the /bkend-storage skill.

Q: What is the rate limit?

A: Rate limits depend on your plan. When exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. Implement exponential backoff in your retry logic:

async function fetchWithRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

---

11. Next Steps

Skill	When to Use
/bkend-quickstart	First-time setup, core concepts, MCP configuration
/bkend-auth	Authentication flows, JWT, social login, MFA
/bkend-data	Advanced queries, filtering, pagination, relations
/bkend-security	RLS policies, rate limiting, CORS, audit logs
/bkend-mcp	MCP server tools reference and advanced usage
/bkend-cookbook	Full project tutorials with step-by-step implementation