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 |