# Popup Studio AI Bkit Codex Phase 1 Schema

> Phase 1: Schema & Data Modeling

- Skill: `tomevault-io/popup-studio-ai-bkit-codex-phase-1-schema` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/popup-studio-ai-bkit-codex-phase-1-schema`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/popup-studio-ai-bkit-codex-phase-1-schema/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/popup-studio-ai-bkit-codex-phase-1-schema

---


# Phase 1: Schema & Data Modeling

> Define your data foundation before writing any code.

## Purpose

Phase 1 establishes the data layer that everything else builds on. Poor data modeling leads to costly refactors later.

## Actions

| Action | Description | Example |
|--------|-------------|---------|
| `start` | Begin Phase 1 | `$phase-1-schema start` |
| `review` | Review current schema | `$phase-1-schema review` |
| `glossary` | Generate terminology glossary | `$phase-1-schema glossary` |

## Deliverables

1. **Terminology Glossary** - Project-wide term definitions
2. **Entity List** - All data entities with descriptions
3. **ERD (Entity Relationship Diagram)** - Visual entity relationships
4. **Field Definitions** - Per-entity field specs (name, type, constraints)
5. **Schema Document** - `docs/01-plan/schema.md`

## Process

### Step 1: Define Terminology

Create a glossary of domain terms used across the project:

```markdown
| Term | Definition | Korean | Example |
|------|-----------|--------|---------|
| User | Person with an account | 사용자 | john@example.com |
| Post | Content created by a user | 게시글 | Blog article |
| Comment | Response to a post | 댓글 | Feedback on article |
```

### Step 2: Identify Entities

List all data entities:

```markdown
## Entities
- User: Account holder (email, name, role)
- Post: User-generated content (title, body, status)
- Comment: Feedback on posts (body, author)
- Tag: Content categorization (name, slug)
```

### Step 3: Define Relationships

```
User 1--* Post       (one user has many posts)
Post 1--* Comment    (one post has many comments)
User 1--* Comment    (one user has many comments)
Post *--* Tag        (many-to-many via PostTag)
```

### Step 4: Field Specifications

For each entity, define fields:

```markdown
### User
| Field | Type | Required | Unique | Default | Description |
|-------|------|----------|--------|---------|-------------|
| id | UUID | Yes | Yes | auto | Primary key |
| email | String(255) | Yes | Yes | - | Login email |
| name | String(100) | Yes | No | - | Display name |
| role | Enum | Yes | No | 'user' | user/admin |
| created_at | DateTime | Yes | No | now() | Creation time |
```

### Step 5: Validation Rules

Define business rules per entity:

- Email must be valid format
- Name must be 2-100 characters
- Role must be one of: user, admin
- Post title must be 1-200 characters

## Schema Patterns

See `references/schema-patterns.md` for common patterns:
- Soft delete pattern
- Audit trail pattern
- Multi-tenancy pattern
- Polymorphic associations

## Output Location

```
docs/01-plan/
├── schema.md          # Full schema document
├── glossary.md        # Terminology glossary
└── erd.md             # Entity relationship diagram
```

## Next Phase

When schema is complete, proceed to **$phase-2-convention** for coding conventions.

## Common Mistakes

| Mistake | Solution |
|---------|----------|
| Skipping terminology | Leads to naming inconsistency later |
| Over-normalizing | Start simple, normalize when needed |
| Missing timestamps | Always include created_at, updated_at |
| No soft delete | Add deleted_at for recoverable data |
| Ignoring indexes | Plan indexes for query patterns early |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/popup-studio-ai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->