dynamic

# Intermediate (Dynamic) Skill ## Actions | 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` | ### init (Project Initialization) 1. Create Next.js + Tailwind project structure 2. Configure bkend.ai MCP (.mcp.json) 3. Create CLAUDE.md (Level: Dynamic specified) 4. Create docs/ folder structure 5. src/lib/bkend.ts client template 6. Initialize .bkit-memory.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 ```typescript // 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 ```typescript // 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) ```typescript // 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 ```typescript // 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 ```typescript // 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) ```bash claude mcp add bkend --transport http https://api.bkend.ai/mcp ``` ### .mcp.json (Per Project) ```json { "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 |