Initial commit

2025-11-29 18:29:10 +08:00
commit 657f1e3da3
29 changed files with 2738 additions and 0 deletions
--- a/skills/data-modeling/SKILL.md
+++ b/skills/data-modeling/SKILL.md
@@ -0,0 +1,289 @@
+---
+name: grey-haven-data-modeling
+description: Design database schemas for Grey Haven multi-tenant SaaS - SQLModel models, Drizzle schema, multi-tenant isolation with tenant_id and RLS, timestamp fields, foreign keys, indexes, migrations, and relationships. Use when creating database tables.
+---
+
+# Grey Haven Data Modeling Standards
+
+Design **database schemas** for Grey Haven Studio's multi-tenant SaaS applications using SQLModel (FastAPI) and Drizzle ORM (TanStack Start) with PostgreSQL and RLS.
+
+## Multi-Tenant Principles
+
+### CRITICAL: Every Table Requires tenant_id
+
+```typescript
+// ✅ CORRECT - Drizzle
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenant_id: uuid("tenant_id").notNull(), // REQUIRED!
+  created_at: timestamp("created_at").defaultNow().notNull(),
+  updated_at: timestamp("updated_at").defaultNow().notNull(),
+  // ... other fields
+});
+```
+
+```python
+# ✅ CORRECT - SQLModel
+class User(SQLModel, table=True):
+    __tablename__ = "users"
+    
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    tenant_id: UUID = Field(foreign_key="tenants.id", index=True) # REQUIRED!
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    # ... other fields
+```
+
+### Naming Conventions
+
+**ALWAYS use snake_case** (never camelCase):
+
+```typescript
+// ✅ CORRECT
+email_address: text("email_address")
+created_at: timestamp("created_at")
+is_active: boolean("is_active")
+tenant_id: uuid("tenant_id")
+
+// ❌ WRONG
+emailAddress: text("emailAddress")  // WRONG!
+createdAt: timestamp("createdAt")   // WRONG!
+```
+
+### Standard Fields (Required on All Tables)
+
+```typescript
+// Every table should have:
+id: uuid("id").primaryKey().defaultRandom()
+created_at: timestamp("created_at").defaultNow().notNull()
+updated_at: timestamp("updated_at").defaultNow().notNull()
+tenant_id: uuid("tenant_id").notNull()
+deleted_at: timestamp("deleted_at") // For soft deletes (optional)
+```
+
+## Core Tables
+
+### 1. Tenants Table (Root)
+
+```typescript
+// Drizzle
+export const tenants = pgTable("tenants", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  name: text("name").notNull(),
+  slug: text("slug").notNull().unique(),
+  is_active: boolean("is_active").default(true).notNull(),
+  created_at: timestamp("created_at").defaultNow().notNull(),
+  updated_at: timestamp("updated_at").defaultNow().notNull(),
+});
+```
+
+```python
+# SQLModel
+class Tenant(SQLModel, table=True):
+    __tablename__ = "tenants"
+    
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    name: str = Field(max_length=255)
+    slug: str = Field(max_length=100, unique=True)
+    is_active: bool = Field(default=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+```
+
+### 2. Users Table (With Tenant Isolation)
+
+```typescript
+// Drizzle
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenant_id: uuid("tenant_id").notNull(),
+  email_address: text("email_address").notNull().unique(),
+  full_name: text("full_name").notNull(),
+  is_active: boolean("is_active").default(true).notNull(),
+  created_at: timestamp("created_at").defaultNow().notNull(),
+  updated_at: timestamp("updated_at").defaultNow().notNull(),
+  deleted_at: timestamp("deleted_at"),
+});
+
+// Index for tenant_id
+export const usersTenantIndex = index("users_tenant_id_idx").on(users.tenant_id);
+```
+
+```python
+# SQLModel
+class User(SQLModel, table=True):
+    __tablename__ = "users"
+    
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    tenant_id: UUID = Field(foreign_key="tenants.id", index=True)
+    email_address: str = Field(max_length=255, unique=True)
+    full_name: str = Field(max_length=255)
+    is_active: bool = Field(default=True)
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    updated_at: datetime = Field(default_factory=datetime.utcnow)
+    deleted_at: Optional[datetime] = None
+```
+
+## Relationships
+
+### One-to-Many
+
+```typescript
+// Drizzle - User has many Posts
+export const posts = pgTable("posts", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenant_id: uuid("tenant_id").notNull(),
+  user_id: uuid("user_id").notNull(),
+  title: text("title").notNull(),
+  // ... other fields
+});
+
+// Relations
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  user: one(users, {
+    fields: [posts.user_id],
+    references: [users.id],
+  }),
+}));
+```
+
+### Many-to-Many
+
+```typescript
+// Drizzle - User has many Roles through UserRoles
+export const user_roles = pgTable("user_roles", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  tenant_id: uuid("tenant_id").notNull(),
+  user_id: uuid("user_id").notNull(),
+  role_id: uuid("role_id").notNull(),
+  created_at: timestamp("created_at").defaultNow().notNull(),
+});
+
+// Indexes for join table
+export const userRolesUserIndex = index("user_roles_user_id_idx").on(user_roles.user_id);
+export const userRolesRoleIndex = index("user_roles_role_id_idx").on(user_roles.role_id);
+```
+
+## RLS Policies
+
+### Enable RLS on All Tables
+
+```sql
+-- Enable RLS
+ALTER TABLE users ENABLE ROW LEVEL SECURITY;
+
+-- Tenant isolation policy
+CREATE POLICY "tenant_isolation"
+ON users
+FOR ALL
+USING (tenant_id = current_setting('app.tenant_id')::uuid);
+
+-- Admin override policy
+CREATE POLICY "admin_override"
+ON users
+FOR ALL
+TO admin_role
+USING (true);
+```
+
+## Indexes
+
+### Required Indexes
+
+```typescript
+// ALWAYS index tenant_id
+export const usersTenantIndex = index("users_tenant_id_idx").on(users.tenant_id);
+
+// Index foreign keys
+export const postsUserIndex = index("posts_user_id_idx").on(posts.user_id);
+
+// Composite indexes for common queries
+export const postsCompositeIndex = index("posts_tenant_user_idx")
+  .on(posts.tenant_id, posts.user_id);
+```
+
+## Migrations
+
+### Drizzle Kit
+
+```bash
+# Generate migration
+bun run db:generate
+
+# Apply migration
+bun run db:migrate
+
+# Rollback migration (manual)
+```
+
+### Alembic (SQLModel)
+
+```bash
+# Generate migration
+alembic revision --autogenerate -m "add users table"
+
+# Apply migration
+alembic upgrade head
+
+# Rollback migration
+alembic downgrade -1
+```
+
+## Supporting Documentation
+
+All supporting files are under 500 lines per Anthropic best practices:
+
+- **[examples/](examples/)** - Complete schema examples
+  - [drizzle-models.md](examples/drizzle-models.md) - Drizzle schema examples
+  - [sqlmodel-models.md](examples/sqlmodel-models.md) - SQLModel examples
+  - [relationships.md](examples/relationships.md) - Relationship patterns
+  - [rls-policies.md](examples/rls-policies.md) - RLS policy examples
+  - [INDEX.md](examples/INDEX.md) - Examples navigation
+
+- **[reference/](reference/)** - Data modeling references
+  - [naming-conventions.md](reference/naming-conventions.md) - Field naming rules
+  - [indexes.md](reference/indexes.md) - Index strategies
+  - [migrations.md](reference/migrations.md) - Migration patterns
+  - [INDEX.md](reference/INDEX.md) - Reference navigation
+
+- **[templates/](templates/)** - Copy-paste ready templates
+  - [drizzle-table.ts](templates/drizzle-table.ts) - Drizzle table template
+  - [sqlmodel-table.py](templates/sqlmodel-table.py) - SQLModel table template
+
+- **[checklists/](checklists/)** - Schema checklists
+  - [schema-checklist.md](checklists/schema-checklist.md) - Pre-PR schema validation
+
+## When to Apply This Skill
+
+Use this skill when:
+- Creating new database tables
+- Designing multi-tenant data models
+- Adding relationships between tables
+- Creating RLS policies
+- Generating database migrations
+- Refactoring existing schemas
+- Implementing soft deletes
+- Adding indexes for performance
+
+## Template Reference
+
+These patterns are from Grey Haven's production templates:
+- **cvi-template**: Drizzle ORM + PostgreSQL + RLS
+- **cvi-backend-template**: SQLModel + PostgreSQL + Alembic
+
+## Critical Reminders
+
+1. **tenant_id**: Required on EVERY table (no exceptions!)
+2. **snake_case**: All fields use snake_case (NEVER camelCase)
+3. **Timestamps**: created_at and updated_at on all tables
+4. **Indexes**: Always index tenant_id and foreign keys
+5. **RLS policies**: Enable RLS on all tables for tenant isolation
+6. **Soft deletes**: Use deleted_at instead of hard deletes
+7. **Foreign keys**: Explicitly define relationships
+8. **Migrations**: Test both up and down migrations
+9. **Email fields**: Name as email_address (not email)
+10. **Boolean fields**: Use is_/has_/can_ prefix
--- a/skills/data-modeling/checklists/schema-checklist.md
+++ b/skills/data-modeling/checklists/schema-checklist.md
@@ -0,0 +1,60 @@
+# Database Schema Checklist
+
+**Use before creating PR for new database schemas.**
+
+## Naming Conventions
+
+- [ ] All field names use snake_case (NOT camelCase)
+- [ ] Boolean fields use is_/has_/can_ prefix
+- [ ] Timestamp fields use _at suffix
+- [ ] Foreign keys use _id suffix
+- [ ] Email field named email_address (not email)
+- [ ] Phone field named phone_number (not phone)
+
+## Multi-Tenant Requirements
+
+- [ ] tenant_id field present on ALL tables
+- [ ] tenant_id has NOT NULL constraint
+- [ ] tenant_id has index for performance
+- [ ] tenant_id has foreign key to tenants table
+- [ ] RLS policy created for tenant isolation
+- [ ] Test cases verify tenant isolation
+
+## Standard Fields
+
+- [ ] id field (UUID primary key)
+- [ ] created_at timestamp (NOT NULL, default now())
+- [ ] updated_at timestamp (NOT NULL, auto-update)
+- [ ] tenant_id (NOT NULL, indexed)
+- [ ] deleted_at timestamp (for soft delete, optional)
+
+## Indexes
+
+- [ ] tenant_id indexed
+- [ ] Foreign keys indexed
+- [ ] Unique fields indexed
+- [ ] Frequently queried fields indexed
+- [ ] Composite indexes for common query patterns
+
+## Relationships
+
+- [ ] Foreign keys defined explicitly
+- [ ] Relationships documented in schema
+- [ ] Cascade delete configured appropriately
+- [ ] Join tables for many-to-many
+
+## Migrations
+
+- [ ] Migration generated (Drizzle Kit or Alembic)
+- [ ] Migration tested locally
+- [ ] Migration reversible (has downgrade)
+- [ ] Migration reviewed by teammate
+- [ ] No breaking changes without coordination
+
+## Row Level Security
+
+- [ ] RLS enabled on table
+- [ ] Tenant isolation policy created
+- [ ] Admin override policy (if needed)
+- [ ] Anonymous policy (if public data)
+- [ ] RLS tested with different roles
--- a/skills/data-modeling/examples/INDEX.md
+++ b/skills/data-modeling/examples/INDEX.md
@@ -0,0 +1,36 @@
+# Data Modeling Examples
+
+Complete database schema examples for multi-tenant SaaS.
+
+## Available Examples
+
+### [drizzle-models.md](drizzle-models.md)
+Drizzle ORM schema examples (TypeScript).
+- Basic table definitions
+- Relationships (one-to-many, many-to-many)
+- Indexes and constraints
+
+### [sqlmodel-models.md](sqlmodel-models.md)
+SQLModel schema examples (Python).
+- Model definitions
+- Relationships and foreign keys
+- Type hints and validation
+
+### [relationships.md](relationships.md)
+Relationship patterns for both ORMs.
+- One-to-many relationships
+- Many-to-many with join tables
+- Self-referential relationships
+
+### [rls-policies.md](rls-policies.md)
+Row Level Security policy examples.
+- Tenant isolation policies
+- Admin override policies
+- Public data policies
+
+## Quick Reference
+
+**Need Drizzle?** → [drizzle-models.md](drizzle-models.md)
+**Need SQLModel?** → [sqlmodel-models.md](sqlmodel-models.md)
+**Need relationships?** → [relationships.md](relationships.md)
+**Need RLS?** → [rls-policies.md](rls-policies.md)
--- a/skills/data-modeling/reference/INDEX.md
+++ b/skills/data-modeling/reference/INDEX.md
@@ -0,0 +1,32 @@
+# Data Modeling Reference
+
+Configuration and pattern references.
+
+## Available References
+
+### [naming-conventions.md](naming-conventions.md)
+Field naming rules and conventions.
+- snake_case requirements
+- Boolean field prefixes
+- Timestamp field suffixes
+- Foreign key naming
+
+### [indexes.md](indexes.md)
+Index strategies and optimization.
+- When to create indexes
+- Composite indexes
+- Unique constraints
+- Performance considerations
+
+### [migrations.md](migrations.md)
+Migration patterns and best practices.
+- Drizzle Kit workflow
+- Alembic workflow
+- Rollback strategies
+- Testing migrations
+
+## Quick Reference
+
+**Need naming?** → [naming-conventions.md](naming-conventions.md)
+**Need indexes?** → [indexes.md](indexes.md)
+**Need migrations?** → [migrations.md](migrations.md)