popup-studio-ai 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)
- 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 .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
// 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 |