Pier_v1/.hmcmkit/knowledge/templates/design.template.md

template, version, description, variables

template	version	description	variables
design	1.3	PDCA Design phase document template with Context Anchor, Session Guide, and Clean Architecture support	feature Feature name date Creation date (YYYY-MM-DD) author Author project Project name (from package.json or agents.md) version Project version (from package.json)

{feature} Design Document

Summary: {One-line description}

Project: {project} Version: {version} Author: {author} Date: {date} Status: Draft Planning Doc: {feature}.plan.md

Pipeline References (if applicable)

Phase	Document	Status
Phase 1	Schema Definition	✅/❌/N/A
Phase 2	Coding Conventions	✅/❌/N/A
Phase 3	Mockup	✅/❌/N/A
Phase 4	API Spec	✅/❌/N/A

Note

: If Pipeline documents exist, reference them in the relevant sections below.

---

Context Anchor

Copied from Plan document. Ensures strategic context survives Design→Do handoff.

Key	Value
WHY	{copied from Plan Context Anchor}
WHO	{copied from Plan Context Anchor}
RISK	{copied from Plan Context Anchor}
SUCCESS	{copied from Plan Context Anchor}
SCOPE	{copied from Plan Context Anchor}

---

Design Anchor (if Pencil MCP used)

Locked design tokens from initial concept pages. Enforced on every new page. Capture with: /design-anchor capture {feature} File: docs/02-design/styles/{feature}.design-anchor.md

Category	Tokens
Colors	primary: {value}, bg: {value}, text: {value}
Typography	{font-family}, sizes: {scale}
Spacing	{base-unit} grid, card: {value}, section: {value}
Radius	default: {value}
Tone	{design tone description}
Layout	{layout pattern description}

Remove this section if not using Pencil MCP for this feature.

---

1. Overview

1.1 Design Goals

{Technical goals this design aims to achieve}

1.2 Design Principles

• {Principle 1: e.g., Single Responsibility Principle}
• {Principle 2: e.g., Extensible architecture}
• {Principle 3}

---

2. Architecture Options (v1.7.0)

2.0 Architecture Comparison

Three architecture options are evaluated before detailed design. User selects one via Checkpoint 3.

Criteria	Option A: Minimal	Option B: Clean	Option C: Pragmatic
Approach	Least change, max reuse	Best separation, most maintainable	Good boundaries, balanced
New Files	{N}	{N}	{N}
Modified Files	{N}	{N}	{N}
Complexity	Low	High	Medium
Maintainability	Medium	High	High
Effort	Low	High	Medium
Risk	Low (coupled)	Low (clean)	Low (balanced)
Recommendation	Quick wins, hotfixes	Long-term projects	Default choice

Selected: {Option A/B/C} — Rationale: {why this was chosen}

The detailed design below follows the selected architecture option.

2.1 Component Diagram

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   Server    │────▶│  Database   │
│  (Browser)  │     │   (API)     │     │ (Storage)   │
└─────────────┘     └─────────────┘     └─────────────┘

BaaS Architecture (Dynamic Level)

Client (Next.js) -> bkend.ai Service API (REST) -> MongoDB
                 <-> MCP (schema management)
              Antigravity Platform

2.2 Data Flow

User Input → Validation → Business Logic → Data Storage → Response

2.3 Dependencies

Component	Depends On	Purpose
{Component A}	{Component B}	{Purpose}

---

3. Data Model

3.1 Entity Definition

// {Entity name}
interface {Entity} {
  id: string;           // Unique identifier
  createdAt: Date;      // Creation timestamp
  updatedAt: Date;      // Last update timestamp
  // Additional fields...
}

3.2 Entity Relationships

[User] 1 ──── N [Post]
   │
   └── 1 ──── N [Comment]

3.3 Database Schema (if applicable)

CREATE TABLE {table_name} (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

MongoDB Collection Schema (Dynamic Level - bkend.ai)

Field	Type	Required	Unique	Description
_id	ObjectId	auto	auto	System generated
createdBy	String	auto	-	Creator user ID
createdAt	Date	auto	-	Creation timestamp
updatedAt	Date	auto	-	Update timestamp

---

4. API Specification

BaaS API (Dynamic Level)

Dynamic level uses bkend.ai auto-generated REST API. CRUD endpoints are auto-generated when tables are created (no separate API implementation needed). Reference: MCP tool 4_howto_implement_data_crud

4.1 Endpoint List

Method	Path	Description	Auth
GET	/api/{resource}	List all	Required
GET	/api/{resource}/:id	Get detail	Required
POST	/api/{resource}	Create	Required
PUT	/api/{resource}/:id	Update	Required
DELETE	/api/{resource}/:id	Delete	Required

4.2 Detailed Specification

POST /api/{resource}

Request:

{
  "field1": "string",
  "field2": "number"
}

Response (201 Created):

{
  "id": "string",
  "field1": "string",
  "field2": "number",
  "createdAt": "2024-01-01T00:00:00Z"
}

Error Responses:

• 400 Bad Request: Input validation failed
• 401 Unauthorized: Authentication required
• 409 Conflict: Duplicate data

---

5. UI/UX Design (if applicable)

5.1 Screen Layout

┌────────────────────────────────────┐
│  Header                            │
├────────────────────────────────────┤
│                                    │
│  Main Content Area                 │
│                                    │
├────────────────────────────────────┤
│  Footer                            │
└────────────────────────────────────┘

5.2 User Flow

Home → Login → Dashboard → Use Feature → View Results

5.3 Component List

Component	Location	Responsibility
{ComponentA}	src/components/	{Role}

5.4 Page UI Checklist (v2.1.0)

CRITICAL: List EVERY required UI element per page. Gap Detector verifies each item. Without this checklist, gap analysis only checks file existence (structural), not content (functional).

How to fill: For each page, list all interactive elements (forms, buttons, filters, dropdowns, badges, toggles) and data display elements (cards, lists, scores, charts) that MUST be present. Include specific field names, option values, and data types.

{Page Name 1}

• {Element type}: {Description} ({specific details: options, fields, values})
• {Element type}: {Description}

{Page Name 2}

• {Element type}: {Description}

Example (remove in actual document):

Search Page

• Filter: Property Type dropdown (6 options: Officetel, Apartment, House, Share House, Serviced Apt, Hotel)
• Filter: Price range slider (weekly rent, min/max KRW inputs)
• Filter: ARC Registration Available checkbox
• Filter: Pet Allowed checkbox
• Button: Save Search
• Card: Weekly rent display (₩{amount}/week)
• Card: Area display ({N}평)
• Card: ARC badge (green, conditional)
• Card: Pet badge (conditional)
• Toggle: List / Map view
• Sort: Recommended, Price ASC, Price DESC, Newest

---

6. Error Handling

6.1 Error Code Definition

Code	Message	Cause	Handling
400	Invalid input	Input error	Request re-entry from client
401	Unauthorized	Auth failure	Redirect to login page
404	Not found	Resource missing	Show 404 page
500	Internal error	Server error	Log error and notify user

6.2 Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "User-friendly message",
    "details": {}
  }
}

---

7. Security Considerations

• Input validation (XSS, SQL Injection prevention)
• Authentication/Authorization handling
• Sensitive data encryption
• HTTPS enforcement
• Rate Limiting

---

8. Test Plan (v2.3.0)

CRITICAL: Define WHAT to test here. Test CODE is written during Do phase alongside implementation. Do phase rule: code + test = 1 set. No module is "done" without its tests passing. Check phase: runs all tests, doesn't create new ones.

8.1 Test Scope

Type	Target	Tool	Phase
L1: API Tests	Endpoints — status, params, response shape	curl / Playwright request	Do
L2: UI Action Tests	Page elements — forms, buttons, data display	Playwright	Do
L3: E2E Scenario Tests	User journeys — multi-page flows	Playwright	Do

8.2 L1: API Test Scenarios

Define expected behavior for each endpoint. Do phase writes the actual test code.

#	Endpoint	Method	Test Description	Expected Status	Expected Response
1	/api/{resource}	GET	Returns list with data	200	.data is array, .pagination.total > 0
2	/api/{resource}/:id	GET	Returns detail with relations	200	.data.id exists, nested relations loaded
3	/api/{resource}	POST	Creates with valid data	201	.data.id exists
4	/api/{resource}	POST	Rejects invalid data	400	.error.code = "VALIDATION_ERROR", .error.details.fieldErrors present
5	/api/{protected}	GET	Blocks unauthenticated	401	.error.code = "UNAUTHORIZED"
6	/api/{resource}?filter=X	GET	Filter reduces results	200	filtered.data.length < all.data.length

8.3 L2: UI Action Test Scenarios

Define per-page: what action → what result. Reference §5.4 Page UI Checklist.

#	Page	Action	Expected Result	Data Verification
1	{page}	Load page	All §5.4 checklist elements visible	DB data renders (not skeleton)
2	{page}	Click filter	Results change	Count decreases
3	{page}	Submit form	Success state shown	API returns 201
4	{page}	Invalid submit	Error message shown	Validation errors display

8.4 L3: E2E Scenario Test Scenarios

Define complete user journeys. Each scenario chains multiple pages.

#	Scenario	Steps	Success Criteria
1	Guest browsing	Home → Search(data>0) → Filter → Detail(title+host+price)	All data renders from DB
2	Auth flow	Register → Login → Access protected page	No 401 errors
3	Form submission	Navigate → Fill all fields → Submit → Verify success	Confirmation UI shown
4	i18n	Switch language → Verify text changes	UI text matches locale
5	Error handling	Wrong credentials → Error shown, Invalid form → Validation shown	User gets feedback

8.5 Seed Data Requirements

Tests need data. Define minimum seed data for tests to be meaningful.

Entity	Minimum Count	Key Fields Required
{entity}	{N}	{fields that must have values}

Do phase: implement src/lib/db/seed.ts before writing tests. Check phase: run seed before test execution.

---

9. Clean Architecture

Reference: docs/01-plan/conventions.md or Phase 2 Pipeline output

9.1 Layer Structure

Layer	Responsibility	Location
Presentation	UI components, hooks, pages	src/components/, src/hooks/, src/app/
Application	Use cases, services, business logic orchestration	src/services/, src/features/*/hooks/
Domain	Entities, types, core business rules	src/types/, src/domain/
Infrastructure	API clients, DB, external services	src/lib/, src/api/

9.2 Dependency Rules

┌─────────────────────────────────────────────────────────────┐
│                    Dependency Direction                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Presentation ──→ Application ──→ Domain ←── Infrastructure│
│                          │                                  │
│                          └──→ Infrastructure                │
│                                                             │
│   Rule: Inner layers MUST NOT depend on outer layers        │
│         Domain is independent (no external dependencies)    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

9.3 File Import Rules

From	Can Import	Cannot Import
Presentation	Application, Domain	Infrastructure directly
Application	Domain, Infrastructure	Presentation
Domain	Nothing external (pure types/logic)	All external layers
Infrastructure	Domain only	Application, Presentation

9.4 This Feature's Layer Assignment

Component	Layer	Location
{ComponentA}	Presentation	src/components/{feature}/
{ServiceA}	Application	src/services/{feature}.ts
{TypeA}	Domain	src/types/{feature}.ts
{ApiClient}	Infrastructure	src/lib/api/{feature}.ts

---

10. Coding Convention Reference

Reference: docs/01-plan/conventions.md or Phase 2 Pipeline output

10.1 Naming Conventions

Target	Rule	Example
Components	PascalCase	UserProfile, LoginForm
Functions	camelCase	getUserById(), handleSubmit()
Constants	UPPER_SNAKE_CASE	MAX_RETRY_COUNT, API_BASE_URL
Types/Interfaces	PascalCase	UserProfile, ApiResponse
Files (component)	PascalCase.tsx	UserProfile.tsx
Files (utility)	camelCase.ts	formatDate.ts
Folders	kebab-case	user-profile/, auth-provider/

10.2 Import Order

// 1. External libraries
import { useState } from 'react'
import { useQuery } from '@tanstack/react-query'

// 2. Internal absolute imports
import { Button } from '@/components/ui'
import { userService } from '@/services/user'

// 3. Relative imports
import { useLocalState } from './hooks'

// 4. Type imports
import type { User } from '@/types'

// 5. Styles
import './styles.css'

10.3 Environment Variables

Prefix	Purpose	Scope	Example
NEXT_PUBLIC_	Client-side accessible	Browser	NEXT_PUBLIC_API_URL
DB_	Database connections	Server only	DB_HOST, DB_PASSWORD
API_	External API keys	Server only	API_STRIPE_SECRET
AUTH_	Authentication secrets	Server only	AUTH_SECRET, AUTH_GOOGLE_ID

10.4 This Feature's Conventions

Item	Convention Applied
Component naming	{convention used}
File organization	{convention used}
State management	{convention used}
Error handling	{convention used}

---

11. Implementation Guide

11.1 File Structure

src/
├── features/{feature}/
│   ├── components/
│   ├── hooks/
│   ├── api/
│   └── types/

11.2 Implementation Order

1. Define data model
2. Implement API
3. Implement UI components
4. Integration and testing

11.3 Session Guide

Auto-generated from Design structure. Session split is recommended, not required. Use /pdca do {feature} --scope module-N to implement one module per session.

Module Map

Module	Scope Key	Description	Estimated Turns
{module name}	module-1	{description}	{turns}
{module name}	module-2	{description}	{turns}

Recommended Session Plan

Session	Phase	Scope	Turns
Session 1	Plan + Design	전체	30-35
Session 2	Do	--scope module-1	40-50
Session 3	Do	--scope module-2	40-50
Session 4	Check + Report	전체	30-40

---

Version History

Version	Date	Changes	Author
0.1	{date}	Initial draft	{author}