init (Project Initialization)

Create Next.js + Tailwind project structure
Configure bkend.ai MCP (.mcp.json)
Create CLAUDE.md (Level: Dynamic specified)
Create docs/ folder structure
src/lib/bkend.ts client template
Initialize the pipeline store — writeBkitMemory() in lib/pdca/status.js, which writes .bkit/state/memory.json (the migrated path of .bkit-memory.json). This holds the project level and the 9-phase pipelineStatus, read by the pipeline Stop hooks for phases 5, 6 and 9. It is NOT where the PDCA phase lives — that is .bkit/state/pdca-status.json.

guide (Development Guide)

bkend.ai auth/data configuration guide
Phase 1-9 full Pipeline guide
API integration patterns

help (BaaS Help)

Explain bkend.ai basic concepts
Auth, database, file storage usage
MCP integration methods

Target Audience

Frontend developers
Solo entrepreneurs
Those who want to build fullstack services quickly

Tech Stack

Frontend:
- React / Next.js 14+
- TypeScript
- Tailwind CSS
- TanStack Query (data fetching)
- Zustand (state management)

Backend (BaaS):
- bkend.ai
  - Auto REST API
  - MongoDB database
  - Built-in authentication (JWT)
  - Real-time features (WebSocket)

Deployment:
- Vercel (frontend)
- bkend.ai (backend)

Language Tier Guidance (v1.3.0)

Recommended: Tier 1-2 languages

Dynamic level supports full-stack development with strong AI compatibility.

Tier	Allowed	Reason
Tier 1	✅ Primary	Full AI support
Tier 2	✅ Yes	Mobile (Flutter/RN), Modern web (Vue, Astro)
Tier 3	⚠️ Limited	Platform-specific needs only
Tier 4	❌ No	Migration recommended

Mobile Development:

React Native (Tier 1 via TypeScript) - Recommended
Flutter (Tier 2 via Dart) - Supported

Project Structure

project/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── (auth)/            # Auth-related routes
│   │   │   ├── login/
│   │   │   └── register/
│   │   ├── (main)/            # Main routes
│   │   │   ├── dashboard/
│   │   │   └── settings/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   │
│   ├── components/             # UI components
│   │   ├── ui/                # Basic UI (Button, Input...)
│   │   └── features/          # Feature-specific components
│   │
│   ├── hooks/                  # Custom hooks
│   │   ├── useAuth.ts
│   │   └── useQuery.ts
│   │
│   ├── lib/                    # Utilities
│   │   ├── bkend.ts           # bkend.ai client
│   │   └── utils.ts
│   │
│   ├── stores/                 # State management (Zustand)
│   │   └── auth-store.ts
│   │
│   └── types/                  # TypeScript types
│       └── index.ts
│
├── docs/                       # PDCA documents
│   ├── 01-plan/
│   ├── 02-design/
│   │   ├── data-model.md      # Data model
│   │   └── api-spec.md        # API specification
│   ├── 03-analysis/
│   └── 04-report/
│
├── .mcp.json                   # bkend.ai MCP config (type: http)
├── .env.local                  # Environment variables
├── package.json
└── README.md

Core Patterns

bkend.ai Client Setup

// lib/bkend.ts - REST Service API Client
const API_BASE = process.env.NEXT_PUBLIC_BKEND_API_URL || 'https://api.bkend.ai/v1';
const PROJECT_ID = process.env.NEXT_PUBLIC_BKEND_PROJECT_ID!;
const ENVIRONMENT = process.env.NEXT_PUBLIC_BKEND_ENV || 'dev';

async function bkendFetch(path: string, options: RequestInit = {}) {
  const token = localStorage.getItem('bkend_access_token');
  const res = await fetch(`${API_BASE}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'x-project-id': PROJECT_ID,
      'x-environment': ENVIRONMENT,
      ...(token && { Authorization: `Bearer ${token}` }),
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

export const bkend = {
  auth: {
    signup: (body: {email: string; password: string}) => bkendFetch('/auth/email/signup', {method: 'POST', body: JSON.stringify(body)}),
    signin: (body: {email: string; password: string}) => bkendFetch('/auth/email/signin', {method: 'POST', body: JSON.stringify(body)}),
    me: () => bkendFetch('/auth/me'),
    refresh: (refreshToken: string) => bkendFetch('/auth/refresh', {method: 'POST', body: JSON.stringify({refreshToken})}),
    signout: () => bkendFetch('/auth/signout', {method: 'POST'}),
  },
  data: {
    list: (table: string, params?: Record<string,string>) => bkendFetch(`/data/${table}?${new URLSearchParams(params)}`),
    get: (table: string, id: string) => bkendFetch(`/data/${table}/${id}`),
    create: (table: string, body: any) => bkendFetch(`/data/${table}`, {method: 'POST', body: JSON.stringify(body)}),
    update: (table: string, id: string, body: any) => bkendFetch(`/data/${table}/${id}`, {method: 'PATCH', body: JSON.stringify(body)}),
    delete: (table: string, id: string) => bkendFetch(`/data/${table}/${id}`, {method: 'DELETE'}),
  },
};

Authentication Hook

// hooks/useAuth.ts
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { bkend } from '@/lib/bkend';

interface AuthState {
  user: User | null;
  isLoading: boolean;
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
}

export const useAuth = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      isLoading: false,

      login: async (email, password) => {
        set({ isLoading: true });
        const { user, token } = await bkend.auth.login({ email, password });
        set({ user, isLoading: false });
      },

      logout: () => {
        bkend.auth.logout();
        set({ user: null });
      },
    }),
    { name: 'auth-storage' }
  )
);

Data Fetching (TanStack Query)

// List query
const { data, isLoading, error } = useQuery({
  queryKey: ['items', filters],
  queryFn: () => bkend.collection('items').find(filters),
});

// Single item query
const { data: item } = useQuery({
  queryKey: ['items', id],
  queryFn: () => bkend.collection('items').findById(id),
  enabled: !!id,
});

// Create/Update (Mutation)
const mutation = useMutation({
  mutationFn: (newItem) => bkend.collection('items').create(newItem),
  onSuccess: () => {
    queryClient.invalidateQueries(['items']);
  },
});

Protected Route

// components/ProtectedRoute.tsx
'use client';

import { useAuth } from '@/hooks/useAuth';
import { redirect } from 'next/navigation';

export function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const { user, isLoading } = useAuth();

  if (isLoading) return <LoadingSpinner />;
  if (!user) redirect('/login');

  return <>{children}</>;
}

Data Model Design Principles

// Base fields (auto-generated)
interface BaseDocument {
  _id: string;
  createdAt: Date;
  updatedAt: Date;
}

// User reference
interface Post extends BaseDocument {
  userId: string;        // Author ID (reference)
  title: string;
  content: string;
  tags: string[];        // Array field
  metadata: {            // Embedded object
    viewCount: number;
    likeCount: number;
  };
}

MCP Integration

Claude Code CLI (Recommended)

claude mcp add bkend --transport http https://api.bkend.ai/mcp

.mcp.json (Per Project)

{
  "mcpServers": {
    "bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp"
    }
  }
}

Authentication

OAuth 2.1 + PKCE (browser auto-auth)
No API Key/env vars needed
First MCP request opens browser -> login to bkend console -> select Organization -> approve permissions
Verify: "Show my bkend projects"


## Environment Variables (.env.local)

NEXT_PUBLIC_BKEND_API_URL=https://api.bkend.ai/v1 NEXT_PUBLIC_BKEND_PROJECT_ID=your-project-id NEXT_PUBLIC_BKEND_ENV=dev


Note: Project ID is found in bkend console (console.bkend.ai).
Via MCP: "Show my project list" -> backend_project_list

## Limitations

❌ Complex backend logic (serverless function limits) ❌ Large-scale traffic (within BaaS limits) ❌ Custom infrastructure control ❌ Microservices architecture


## When to Upgrade

Move to **Enterprise Level** if you need:

→ "Traffic will increase significantly" → "I want to split into microservices" → "I need my own server/infrastructure" → "I need complex backend logic"


## bkit Features for Dynamic Level (v1.5.1)

### Output Style: bkit-pdca-guide (Recommended)

For optimal PDCA workflow experience, activate the PDCA guide style:

/output-style bkit-pdca-guide


This provides:
- PDCA status badges showing current phase progress
- Gap analysis suggestions after code changes
- Automatic next-phase guidance with checklists

### Agent Teams (2 Teammates)

Dynamic projects support Agent Teams for parallel PDCA execution:

| Role | Agents | PDCA Phases |
|------|--------|-------------|
| developer | bkend-expert | Do, Act |
| qa | qa-monitor, gap-detector | Check |

**To enable:**
1. Set environment: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
2. Start team mode: `/pdca team {feature}`
3. Monitor progress: `/pdca team status`

### Agent Memory (Auto-Active)

All bkit agents automatically remember project context across sessions.
No setup needed — agents use `project` scope memory for this codebase.

---

## Common Mistakes

| Mistake | Solution |
|---------|----------|
| CORS error | Register domain in bkend.ai console |
| 401 Unauthorized | Token expired, re-login or refresh token |
| Data not showing | Check collection name, query conditions |
| Type error | Sync TypeScript type definitions with schema |

Action	Description	Example
`init`	Project initialization (/init-dynamic feature)	`/dynamic init my-saas`
`guide`	Display development guide	`/dynamic guide`
`help`	BaaS integration help	`/dynamic help`

dynamic

Intermediate (Dynamic) Skill

Actions