Data Models

High-level guide to the data models across the monorepo. For full field-level details, refer to the Prisma schema and BUN model definitions directly.

Database Architecture

A single PostgreSQL server (rump:5432) hosts everything:

Database/Schema	ORM	Owner Service	Purpose
`sirloin` (schemas: `users`, `characters`, `media`, `billing`, `bi`, `audits`, `autoscaling`, `mcp`)	BUN	sirloin	Billing, user credits, runtime state, admin, fraud
`sirloin?schema=fennec`	Prisma	brain	Generation records, character details, training, config

Brain and sirloin share the same PostgreSQL instance but use separate schemas. They communicate via gRPC — not direct cross-schema queries.

Domain Ownership

Each domain entity has a single source of truth. Some entities exist in both services with different responsibilities.

Users And Credits

Source of truth: sirloin (credits/billing), brain (identity)

Brain.User (id, clerkId, email, firstName, lastName)
    ↕ synced via Clerk ID
Sirloin.Credit (userId, standardCredits, fullAccessCredits, referralCode)
    → Sirloin.Purchase (itemPriceId, transactionId, price, currency)
    → Sirloin.Referral (referringUserId, referredUserId, creditsEarned)

Characters

Source of truth: sirloin (status, shop/reservation), brain (detailed attributes, training)

Sirloin tracks runtime state: status, availability, reservation, purchase, KYC verification, credit spend. Brain tracks detailed appearance attributes, onboarding images, body type, lora settings, and training jobs.

Sirloin.Character
    status, availabilityStatus, reservedBy, reservedUntil, purchasedBy, priceTier
    → Sirloin.ReferenceDatasetImage (imagePath, etag)

Brain.Character
    characterName, gender, ethnicity, hairColor, bodyType, lora, style, trigger
    → Brain.OnboardingImages (imageUrl, validationMethod, analysis)
    → Brain.BodyType (uiLabel, gender, defaultPromptValue)
    → Brain.CharacterControlGroup (name)

Media And Generations

Source of truth: sirloin (user-facing state), brain (generation records)

Sirloin owns favorites, archives, download tracking, and cost. Brain owns the permanent generation record with prompts, logs, and model parameters.

Sirloin.Media
    userId, characterId, status, isFavorite, isArchived, cost, controls
    → Sirloin.Example (embedding, characterModels[], explicitnessLevel)
        → Sirloin.Tag (via ExampleTag join table)

Brain.Generation
    genId, characterId, prompt, success, mediaType, logs, inputVariables
    → Brain.MotionType (name, prompt, lora)
    → Brain.GenerationExample → Brain.GenerationTag

Billing And Payments

Source of truth: sirloin (all billing)

Sirloin.DunningAttempt     — payment retry attempts for failed invoices
Sirloin.FailedOperation    — billing ops needing retry (cancel, apply_credits, rollback, etc.)
Sirloin.SubsAll (bi schema) — Chargebee subscription sync (email, customerId, mrr, planUnitPrice)

Sirloin.FraudEvent         — fraud signal audit log
Sirloin.FraudFlag          — persistent per-user fraud status
Sirloin.FraudCooldown      — velocity rule blocking
Sirloin.HighRiskBin        — high-risk BIN list
Sirloin.CardFingerprintAccount — maps card fingerprints to user accounts

Sirloin.PrimerPollingState  — cursor for Primer settled payment polling

Training And Datasets

Source of truth: brain

Brain.TrainingJob (characterId, status, detailedStatus, lastHeartbeatAt)
Brain.DatasetGenerationRequest (characterId, status, runpodJobId)

Shop VI

Source of truth: sirloin (reservations/purchases), brain (catalog metadata)

Sirloin.Character fields: priceTier, availabilityStatus, catalogueImagePaths,
    reservedBy, reservedUntil, reservationToken, purchasedBy, purchasedAt

Brain.Pack (packId, packName, packType, packItems[])
Brain.Item (itemId, itemName, packId)
Brain.ShopVIImportJob (directoryPath, status, stats)

Admin And Audit

Source of truth: sirloin

Sirloin.StripAuditLog (userId, action, entityType, entityId, changes, metadata)
Sirloin.StripAdminRole (userId, role: root|admin|creator|support|viewer)

Foxy360

Source of truth: sirloin

Sirloin.MCPThread → MCPRun → MCPRunStep
                           → MCPArtifact
                           → MCPConnectorCall
    MCPMessage (role: user|assistant|system|tool)

Configuration And Settings

Brain owns application config: Settings, CharacterSettings, Preset, WappySettings, IfastConfig, ApplicationSettings.

Sirloin owns infrastructure config: ScalingDecision (autoscaling decisions with worker counts, prediction methods, spike detection).

Special Field Types

Type	Examples	Notes
JSONB	`Media.controls`, `FailedOperation.operationData`, `FraudEvent.metadata`, `StripAuditLog.changes`	Structured metadata, varies per record
Arrays	`Character.captions[]`, `Example.characterModels[]`, `Character.catalogueImagePaths[]`	PostgreSQL native arrays
Vector	`Example.embedding`	Used for semantic search over examples
Soft deletes	`deletedAt` on Character, Media, ReferenceDatasetImage	BUN and Prisma both use soft delete patterns

Key Indexes

Brain (Prisma):

Generation(characterId), Generation(characterId, success), Generation(mediaType, createdAt DESC, success) — generation queries
Generation(modelUrls) GIN index — array filtering
OnboardingImages(characterId, createdAt DESC) — failed images query
InferenceProviderSpend(date, inferenceProvider) unique — spend dedup

Sirloin (BUN):

Standard FK indexes on userId, characterId, mediaId
Billing tables indexed on invoiceId, customerId, subscriptionId
Fraud tables indexed on userId, cardFingerprint, bin6

Proto To Model Mapping

Proto messages in proto/sirloin/v5/ map closely to BUN models but are not 1:1. Key differences:

Proto Character message is a projection — combines fields from both sirloin and brain character records
Proto Media message includes computed fields (thumbnail_url, video_preview_url) not stored in DB
Proto ShopCharacter is a specialized view of Character with shop-specific fields
Proto billing messages (SubscriptionDetails, Product, CouponInfo) aggregate data from Chargebee + local billing tables

Source Locations

What	Path
Brain Prisma schema	`apps/brain/prisma/schema.prisma`
Sirloin BUN models	`apps/sirloin/internal/pkg/models/`
Proto definitions	`proto/sirloin/v5/`, `proto/round/v1/`
Generated proto docs	`api/server.md`