Realbits
Back to Blog
May 25, 202612 sources4 arXiv

Prisma-backed creator studio inventory as a provider control-plane contract

A technical architecture article analyzing how Realbits should model creator-managed character inventory in PostgreSQL using Prisma so publish, versioning, and ownership workflows remain auditable and cross-app reusable.

prismacreator-studioinventorynextjs
<!-- Generated by the Realbits daily technology blog cron. Review before public publishing. -->

Abstract

Realbits now treats model packs, character cards, and app presets as provider assets that move across all surfaces, which makes the creator studio data layer a control-plane contract rather than a sidecar CMS.[S15] On 2026-05-25, the practical engineering question is whether the Prisma schema in packages/web can express three things at once: evolving character definitions, publish state transitions, and auditability across creators and evaluator feedback.[S1] This article argues that the schema should be modeled as an explicit inventory domain model, not merely a convenience storage table. A robust contract must preserve current draft usability while making irreversible events explicit enough to support disputes, reruns, and analytics for creator onboarding metrics.[S3]

The architecture proposed here is intentionally not a product marketing draft. It is an engineering-oriented blueprint for inventory semantics under a mixed on-chain/off-chain system: PostgreSQL for mutable content workflows, NFT ownership checks for entitlement, and Next.js API handlers as the write boundary. The key thesis is that each publishable asset should have a versioned source of truth, and each transition should be represented as a durable event with deterministic replay characteristics.[S2]

Realbits Context

Realbits already moved toward this direction in the repository design by keeping creator tooling in packages/web and aligning character production with package-level runtime surfaces. The local schema already includes a user model tied to createdCharacters, and the studio client uses a /api/characters API to send create/read payloads for character records.[S5] The current studio API pattern is thin and pragmatic: it relies on server validation and auth while writing JSON-like character payloads such as prompt text, tags, dialogue samples, and behavior overrides. This is a useful baseline but not yet a complete provider contract.[S11]

In this context, the API route boundary in Next.js is more than a transport layer. Route handlers are designed as typed, method-based request entry points and can express GET, POST, PATCH, and DELETE with explicit behaviors for cache control and request handling.[S11] Because Realbits is provider-led, the boundary must do more than accept form input: it must validate transitions, create immutable draft/version records, and provide idempotent semantics when clients retry publish operations.

The inventory contract should also reflect how on-chain identity interacts with creator records. On-chain ERC-721 ownership is a strong entitlement check, but it is not rich enough for internal curation states, draft provenance, or publish metadata. The standard emphasizes ownership, transfer events, approvals, and optional metadata URI retrieval, not studio-specific moderation and workflow attributes.[S16] So the DB layer must hold those additional states, while token ownership remains the source of final entitlement rights at runtime.[S15]

Related Work

This design aligns with two mature patterns: temporal consistency and provenance-aware records. Temporal relational thinking suggests that the same logical character can have multiple valid revisions without being destroyed and recreated; this matches the need to let creators iterate while preserving historical snapshots for analytics and rollback.[S1] In practical terms, Realbits should support draft versions, staged versions, published versions, and potentially post-publish patch versions without conflating user edits with a published artifact state.

Provenance literature reinforces that systems gain trust when they capture derivation history rather than relying on overwrite behavior.[S2] For creator inventories, provenance means not just updatedAt timestamps but explicit actor, action type, and source reason for each change. That is useful for evaluating eval gate outcomes, creator support disputes, and monetization debugging. A short provenance trail is especially important where one character card can be copied from another and modified into a derivative, because lineage affects discoverability and creator credit.[S3]

A recent data version-control line of work (for example, MatrixOne-inspired branching and atomic publish flow ideas) highlights the operational value of staged edit trees plus atomic publishing with rollback windows.[S4] Prisma does not force this pattern directly, but its migration model and transaction semantics make it practical to emulate by schema shape plus disciplined service code. The important distinction is that we want to import only the parts that match our operational profile: quick draft cycles, deterministic publish checkpoints, and no manual SQL merge workflows.

For this repository, the relevant prior-art mapping is: on-chain contract events give identity and asset transfer truth, while Prisma + PostgreSQL captures creator intent and operational state. That split is healthy if we make it explicit in table boundaries and avoid overloading a single table with both semantic domains.

Architecture Analysis

1) Treat character inventory as bounded domains, not one loose model

A practical contract should at minimum include: user identity, draft identity, character identity, character versions, publish attempts, publish decisions, and immutable event logs.

Model boundary proposal (high-level):

  • user-owned entities:
    • User (existing)
    • Character (publishable record)
    • CharacterDraft (editor-only intermediate data)
    • CharacterVersion (immutable content snapshot)
    • CharacterPublishAttempt (external mint/reconciler attempt)
    • CharacterAuditLog (append-only)
    • CharacterManifestBinding (cross-app targeting for distribution)

The workflow invariant is: creators edit drafts, evaluate, promote to version, then publish and bind to manifests or app surfaces.

2) Core schema mechanics and relation discipline

Prisma relation fields should be used with explicit scalar FK fields for deterministic joins and enforceable ownership.[S5] A draft should use explicit creatorId pointing to user.id, and CharacterDraft should reference either a Character draft lineage or a parent draft for fork-like edits. The relation mode should remain database-native constraints for Postgres, since this avoids ambiguity and aligns with PostgreSQL FK guarantees.[S6]

Foreign key constraints should be treated as mandatory invariants in this domain, not optional conventions.[S12] For example:

  • every draft must belong to a creator
  • every publish attempt should link to a version
  • every version should map to exactly one character record after promotion

Use @@unique and @@index to separate fast read paths from safety paths. Typical constraints include:

  • unique active slug per creator or provider namespace
  • unique pair of character and version number
  • composite index for (creatorId, status, updatedAt) for studio list views
  • GiN/GIN-like JSON indexes where query patterns include array containment.

Prisma indexes support multiple index types in PostgreSQL, including GIN for JSON-oriented access patterns when needed for tag and attribute search.[S7]

3) Draft/version separation and publish sequencing

The draft object should remain mutable until publish. After publish, do not update the published row in place; insert a new CharacterVersion row and move the pointer on the Character aggregate.

Recommended sequence:

  1. Save draft in CharacterDraft (idempotent by client-provided draft key).
  2. On explicit publish call, start a database transaction.
  3. Validate draft completeness, ownership, and eligibility constraints.
  4. Create or update Character with immutable currentVersionId.
  5. Insert CharacterVersion row with full JSON payload snapshot and optional diff hash.
  6. Insert CharacterPublishAttempt row with status PENDING.
  7. Commit transaction.
  8. Run asynchronous mint/metadata publication using the attempt row as durable work item.

Prisma transactions provide atomicity for this entire chain when the operations are internal DB writes.[S8] This prevents a partial publish state where some records advance and others do not. However, on-chain minting cannot be made ACID with PostgreSQL; that boundary should be modeled as eventual and mirrored by post-mint reconciliation events.

4) JSONB payload strategy in Postgres via Prisma

Prisma allows JSON storage for flexible character properties such as settings and rule trees while still keeping relational integrity in dedicated columns.[S9] In PostgreSQL this maps to native JSONB functionality, which is useful for containment checks and flexible schema evolution for character examples, plugin configs, and voice/runtime maps.[S13]

Use JSON columns intentionally:

  • avoid putting frequently filtered business fields that are always queried via exact equality there unless index support is planned.
  • place stable query keys into scalar columns where possible for predictable index behavior.

For example, status, creatorId, and verticalApp belong in scalars. Deeply nested settings, persona card cards, and evaluator telemetry can remain JSON with selective extraction.

5) Provenance and lifecycle logging

To satisfy provenance requirements, the system should avoid silent updates without event records. CharacterAuditLog entries should include:

  • actorId
  • eventType (draft_created, draft_saved, eval_ran, publish_requested, publish_reverted, manifest_synced)
  • object references
  • requestId / route version / API fingerprint

This makes operational behavior explainable and gives the team a path to compliance and debugging. It also aligns with provenance research focus on data flow traceability.[S2][S3]

6) Migration and backward-compatible evolution

Prisma Migrate is appropriate for managed schema evolution because it stores migration history as SQL and supports both local iteration and production application workflows.[S10] For this domain, adopt additive-first migration policy: add columns or tables before removing old ones, then backfill in controlled batches. Keep conversion scripts in one-off migration blocks where JSON payloads shift from ad hoc shapes.

A good migration sequence for versioned inventory:

  • add tables first (CharacterVersion, CharacterPublishAttempt)
  • dual-write from old model fields to new model
  • verify parity through checks
  • cutover reads
  • deprecate old paths only after parity windows close

Limitations

This architecture is not a universal answer.

First, JSON-heavy records improve iteration speed but increase query complexity. Even with GIN support, indexing semantics differ between engines and can become brittle when payload shape shifts frequently.[S7] A team should keep query-critical selectors normalized.

Second, Prisma relation integrity is strongest in foreignKeys mode, but any external data source that bypasses Prisma must still obey the same invariants, or logs and version chains become inconsistent.[S6]

Third, write-path transactions are local. Any publish flow with external services (minting, storage signing, eval scoring) remains two-phase in practice. Without explicit idempotency and reconciliation, retries can produce duplicate or phantom publish attempts.

Fourth, Row-level restrictions are valuable for creator isolation, but policy drift can become a hidden deployment risk if not tested per environment. PostgreSQL RLS defaults to deny when enabled without policies, which is safe but easy to misconfigure.[S14]

Finally, this model raises storage growth due to immutable versions and audit logs. That is intentional and should be measured against retention and archive requirements for creator analytics.

Implications for This Repository

For Realbits on 2026-05-25, the first concrete step is to promote inventory from a simple record surface into a contract with explicit lifecycle boundaries. Concretely:

  1. Add version and event models in packages/web/prisma/schema.prisma, while preserving current Character compatibility.
  2. Introduce strict FK relations and unique constraints for creator ownership and version numbering.[S12]
  3. Add transaction-wrapped publish endpoints in the existing API route surface under /api/characters, leveraging deterministic POST semantics and status transitions.[S11][S8]
  4. Create an append-only CharacterAuditLog table and include all publish/edit/eval transitions there.
  5. Use schema migrations through Prisma Migrate, not ad-hoc SQL drift, so local-to-production behavior remains reproducible.[S10]
  6. Treat NFT ownership checks as entitlement gates only, not as a substitute for rich studio state. ERC-721 metadata and transfer semantics should feed, but not define, studio workflows.[S15][S16]

This is not just a model change; it is a control-plane design change. Once complete, creator inventory becomes a verifiable interface between web creation and all app surfaces, with predictable migration, replay, and audit behavior.

References

S1 arXiv: https://arxiv.org/abs/1002.1143 S2 arXiv: https://arxiv.org/abs/0812.0564 S3 arXiv: https://arxiv.org/abs/2107.01678 S4 arXiv: https://arxiv.org/abs/2604.03927 S5 Prisma Relations: https://www.prisma.io/docs/orm/prisma-schema/data-model/relations S6 Prisma Relation Modes: https://docs.prisma.io/docs/orm/prisma-schema/data-model/relations/relation-mode S7 Prisma Indexes: https://www.prisma.io/docs/orm/prisma-schema/data-model/indexes S8 Prisma Transactions: https://www.prisma.io/docs/orm/prisma-client/queries/transactions S9 Prisma JSON Fields: https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/working-with-json-fields S10 Prisma Migrate: https://docs.prisma.io/docs/orm/prisma-migrate S11 Next.js Route Handlers: https://nextjs.org/docs/13/app/building-your-application/routing/route-handlers S12 PostgreSQL Constraints: https://www.postgresql.org/docs/current/ddl-constraints.html S13 PostgreSQL JSON Types: https://www.postgresql.org/docs/current/datatype-json.html S14 PostgreSQL RLS: https://www.postgresql.org/docs/17/ddl-rowsecurity.html S15 OpenZeppelin ERC721 API: https://docs.openzeppelin.com/contracts/4.x/api/token/erc721 S16 EIP-721 Standard: https://eips.ethereum.org/EIPS/eip-721

Source Ledger