1---2name: stacks-models-23description: Use when working with data models in Stacks — the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 50+ built-in framework models. Covers model definitions and storage/framework/models/.4license: MIT5---67# Stacks Models89## Key Paths10- Application models: `app/Models/`11- Framework models: `storage/framework/models/` (50+ auto-generated)12- Default templates: `storage/framework/defaults/models/`13- Attribute types: `storage/framework/types/attributes.ts` (240+ fields)1415## All 50+ Framework Models by Category1617### Users & Auth18- **User** — name, email, password | traits: useAuth(passkey), useUuid, useTimestamps, useSocials(github) | hasOne: Subscriber, Driver, Author | hasMany: PersonalAccessToken, Customer19- **Author** — name, email | belongsTo: User | hasMany: Post20- **Customer** — name, email, phone, totalSpent, lastOrder, status, avatar | belongsTo: User | hasMany: Order, GiftCard, Review, Payment21- **Driver** — name, phone, vehicleNumber, license, status | belongsTo: User | hasMany: DeliveryRoute22- **Subscriber** — email, status, source | belongsTo: User | hasMany: SubscriberEmail2324### Content25- **Post** — title, content, poster, excerpt, views, publishedAt, status, isFeatured | belongsTo: Author | traits: categorizable, taggable, commentable | seeder: 2026- **Page** — similar to Post with taggable, categorizable27- **Comment** — author info, approval, content fields28- **Tag** — name(unique), slug(unique), description, postCount, color | seeder: 1529- **Category** — name, description, slug, imageUrl, isActive, parentCategoryId, displayOrder | hasMany: Product | seeder: 103031### Commerce (20+ models)32- **Product** — name(max100), description, price(min1), imageUrl, isAvailable, inventoryCount, preparationTime, allergens(JSON), nutritionalInfo(JSON) | belongsTo: Category, Manufacturer | hasMany: Review, ProductUnit, ProductVariant, LicenseKey, WaitlistProduct, Coupon | seeder: 10, dashboard: highlighted33- **ProductVariant** — SKU, options, pricing34- **ProductUnit** — unit-specific pricing35- **Cart** — status(active|abandoned|converted|expired), totalItems, subtotal, taxAmount, discountAmount, total, expiresAt, currency(USD), notes | hasMany: CartItem | belongsTo: Customer, Coupon36- **CartItem** — quantity(min1), unitPrice, totalPrice, taxRate, taxAmount, discountPercentage, productName, productSku | belongsTo: Cart37- **Order** — status, totalAmount, taxAmount, discountAmount, deliveryFee, tipAmount, orderType(DINE_IN|TAKEOUT|DELIVERY), deliveryAddress, specialInstructions | hasMany: OrderItem, Payment | belongsTo: Customer, Coupon | observe: true | seeder: 2038- **OrderItem** — quantity(min1), price(min0), specialInstructions | belongsTo: Order, Product39- **Coupon** — code(unique), discountType(fixed_amount|percentage), discountValue, minOrderAmount, usageLimit, usageCount, startDate, endDate | seeder: 1540- **GiftCard** — code(unique), initialBalance, currentBalance, currency, status, recipientEmail, isDigital, isReloadable, expiryDate | seeder: 2041- **Manufacturer** — manufacturer info42- **Review** — rating(1-5), title, content(max2000), isVerifiedPurchase, isApproved, isFeatured, helpfulVotes, unhelpfulVotes | belongsTo: Product, Customer | seeder: 504344### Shipping & Delivery45- **ShippingMethod**, **ShippingRate** (weightFrom, weightTo, rate), **ShippingZone**46- **DeliveryRoute** — driver, vehicle, stops, totalDistance | belongsTo: Driver47- **DigitalDelivery** — name, downloadLimit, expiryDays, automaticDelivery48- **LicenseKey** — key(XXXX-XXXX-XXXX-XXXX-XXXX), template, expiryDate, status4950### Payments & Financial51- **Payment** — amount, method(creditCard|debitCard|paypal|...), status(pending|completed|failed|refunded), currency, transactionId(unique) | belongsTo: Order, Customer | seeder: 5052- **PaymentMethod**, **PaymentProduct**, **PaymentTransaction**53- **Subscription** — type, providerId, providerStatus, unitPrice54- **Transaction** — standard transaction tracking55- **TaxRate** — name, rate(0-100), type(VAT|GST|Sales Tax|Customs Duty), country, region, isDefault5657### Engagement & Marketing58- **Notification** — type, channel, recipient, subject, body, status(pending|sent|delivered|failed|read) | belongsTo: User | seeder: 3059- **Campaign** — name, type(email|sms|push|social|multi-channel), status, audienceSize, openRate, clickRate, budget | seeder: 1060- **Activity** — type, description, subjectType, subjectId, causer, properties(JSON), ipAddress | belongsTo: User | seeder: 5061- **EmailList**, **SocialPost**, **LoyaltyPoint** (walletId, points, source, expiryDate), **LoyaltyReward**6263### System64- **Job** — queue, payload, attempts, available_at, reserved_at | seeder: 1565- **FailedJob** — failed background jobs66- **Error** — type, message, stack, status, additionalInfo | seeder: 1067- **Log** — application logs68- **Request** — method, path, statusCode, durationMs, ipAddress, memoryUsage, userAgent, errorMessage | seeder: 5069- **Websocket** — connection tracking70- **PrintDevice** — name, location, terminal, lastPing, printCount, isActive71- **WaitlistProduct**, **WaitlistRestaurant** — waitlist tracking72- **Receipt** — receipt records7374## CLI Commands75- `buddy make:model [name]` — create new model76- `buddy make:migration [name]` — create migration for schema changes77- `buddy make:factory [name]` — create model factory78- `buddy generate:migrations` — generate migrations from model diffs7980## Gotchas81- Models work directly via the dynamic ORM — no code generation step needed82- `defineModel()` uses `createModel()` from bun-query-builder at runtime, providing typed query methods immediately83- Each model can have a `factory` function per attribute using `@stacksjs/faker`84- `hidden` attributes are excluded from JSON serialization (passwords)85- `guarded` attributes prevent mass assignment86- `fillable` explicitly allows mass assignment87- Model events fire when `observe: true` — emits `{model}:created/updated/deleted`88- Default seeder counts vary: User(10), Post(20), Review(50), Activity(50)89- Dashboard highlighted models appear prominently in the admin UI90- 240+ attribute definitions in `storage/framework/types/attributes.ts`