bkend-guides

# 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: ```typescript 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`: ```typescript 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:** ```json { "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. ```typescript // __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. ```typescript // __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. ```typescript // 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"]', "test@example.com"); 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. ```json { "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. ```json { "event": "auth.user.registered", "user": { "_id": "user_456", "email": "new@example.com" }, "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. ```typescript // 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: ```json { "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 |