Abstract

Realbits is now organized around a provider model: packages/web is the canonical creator and publishing surface, while mobile and desktop apps consume reusable character cards, model packs, and ownership state. In that setting, the most important job of a database schema is not generic CRUD convenience. It is to act as the contract between creator tooling, policy enforcement, publishing, and downstream runtime consumption. Prisma is a good fit for that role because its schema is both a modeling language and the source for generated client code and migrations [S1].

The repository excerpts provided for this task already show the outline of that contract: a PostgreSQL-backed Prisma schema mixes auth, custody, creator-side character inventory, and conversation-state data, while the studio API exposes authoring fields such as personaPrompt, greeting, scenario, tags, voiceId, characterBook, systemPromptOverride, and verticalApp. The architectural question is therefore not whether Prisma can store characters. It can. The real question is how to separate stable inventory facts from fast-changing creative metadata, and how to do so without creating schema drift, provenance loss, or an unqueryable blob store.

Realbits Context

Realbits' provider-first pivot changes what a "character" means in storage. A character is no longer only a prompt preset for one app session. It is an inventory object that may later connect to creator identity, royalty flows, app targeting, evaluation results, conversation behavior, and NFT-backed ownership. That means a creator-studio schema has to support at least five modes of access:

1. Draft-time editing.
2. Policy and safety validation before publish.
3. Marketplace and library queries after publish.
4. Runtime materialization into app-facing payloads.
5. Provenance and payout reconstruction after the fact.

Prisma's model system is useful here because application models become the foundation of the generated query API, rather than an isolated DDL artifact [S1]. Relation fields also give a clean way to distinguish ergonomic application links from actual foreign-key-bearing scalar fields in PostgreSQL [S2]. In practice, that matters because a creator studio does not only read whole records. It repeatedly slices them by ownership, visibility, app surface, quality gate status, and publish state.

The task-provided studio-api.ts excerpt reinforces that point. The client is intentionally thin: it sends a constrained body to /api/characters and trusts the server to enforce safety, eval, and visibility rules. That is aligned with Next.js Route Handlers, which are designed as request handlers inside the App Router and commonly serve as the policy boundary for data mutations [S6]. The result is a useful division of labor: Prisma owns structural correctness, Route Handlers own authorization and workflow rules, and the client stays relatively dumb.

Related Work

The most relevant external literature is not about character cards specifically. It is about schema change, provenance, and economic accountability.

Schema evolution research is immediately applicable. Edwards et al. describe schema evolution as a broader collaboration problem that slows feedback loops and often escapes normal version-control discipline [S7]. That maps closely to creator tools, where product fields evolve quickly: tags become taxonomies, single-voice assignment becomes voice bundles, and one publish state becomes a richer lifecycle. A creator studio that treats every new field as an ad hoc JSON patch will move fast once and then slow down permanently.

Provenance research adds a second lens. Atlas argues that ML supply chains need verifiable lineage metadata across training and deployment artifacts [S8]. Realbits is not shipping foundation model training pipelines from the creator studio, but the same logic applies at the provider layer. If a published character later triggers a revenue event, safety issue, or model-pack incompatibility, the system should be able to answer basic lineage questions: which draft produced it, which evaluator version approved it, which model/runtime assumptions it targeted, and which creator wallet or account owned the publish action.

The recent generator-economy literature sharpens the economic side. The 2026 paper on sustainable AI data deals argues that missing provenance and opaque compensation structures are structural reasons why creator-facing AI economies break down [S9]. For Realbits, that suggests the inventory model should not stop at display metadata. It should preserve enough normalized state to support royalty logic, creator attribution, and auditability later, even if the first web studio release does not yet expose all of that directly.

Architecture Analysis

The strongest Prisma pattern for this repository is a normalized core plus controlled semi-structured edges.

The normalized core should hold stable, high-cardinality facts that participate in filters, joins, and policy. Examples include creator identity, publish state, visibility, vertical-app targeting, voice linkage, ownership references, and lifecycle timestamps. Those belong in ordinary scalar columns and explicit relations because Prisma models directly feed generated query methods and types [S1]. If engineers expect to sort, filter, or join on a field in production, it should probably not live only inside JSON.

The semi-structured edge is still important. Prisma's Json field support is useful when a payload is document-like, nested, and still evolving, and Prisma's PostgreSQL connector maps Json to jsonb by default [S3] [S5]. In Realbits, characterBook, eval detail payloads, draft-local authoring notes, and future tool-specific prompt metadata are plausible candidates. But the key is discipline: JSON should carry extensibility, not responsibility. If verticalApp, voiceId, or publish eligibility are operationally important, they should remain first-class columns even if equivalent values also appear inside richer documents.

That distinction matters because PostgreSQL can index both relational columns and document structures, but not at the same operational cost. Prisma supports explicit index declarations and PostgreSQL-specific access methods such as Gin [S4]. PostgreSQL's GIN indexes are designed for composite items where queries search for contained keys or elements, which makes them suitable for document-like jsonb or array search workloads [S10]. However, GIN is not free. It adds write overhead and is best reserved for genuinely document-centric queries. A creator studio with frequent saves, autosaves, and iterative updates should prefer cheap B-tree paths for hot workflow predicates such as creatorId + updatedAt, publishedAt, or verticalApp + visibility + createdAt, and use GIN only where nested search is a real product requirement.

A second design choice concerns many-to-many modeling. Prisma supports both implicit and explicit many-to-many relations, but explicit join models are the better long-term choice whenever the relation itself carries metadata [S2]. For provider-managed inventory, that case appears quickly. Character-to-app assignment may need rollout state. Character-to-model-pack compatibility may need version ranges. Character-to-creator collaboration may need percentage splits or editorial roles. Character-to-tag relations may eventually need curated ordering or moderation notes. All of those are reasons to choose explicit relation models early instead of hiding them behind arrays or implicit joins.

A third choice is workflow stratification. The current thin client plus server-side enforcement is directionally correct. Route Handlers are a good place to validate authoring payloads, resolve auth, and translate studio requests into Prisma writes [S6]. But the persistence model should distinguish at least three entities, even if the UI presents them as one object: CharacterDraft, CharacterRevision, and Character. Drafts are mutable working state. Revisions are immutable snapshots that support diffing, approval, and provenance. Character is the canonical published pointer used by libraries and apps. This pattern reduces accidental mutation of live inventory and makes rollback, moderation, and royalty attribution easier.

The final architectural issue is generated type pressure. Prisma's main benefit is not only cleaner queries; it is that schema changes propagate into generated types and query APIs [S1]. That is valuable in a creator studio because field drift otherwise hides in forms, API handlers, and runtime payload builders. But it only works if the team treats the Prisma schema as the canonical inventory contract, not merely a persistence afterthought.

Limitations

A Prisma-first inventory model still has limits.

First, a single operational schema can become too broad. The provided repository context suggests auth, custody, conversations, and creator inventory coexist in one Prisma domain. That is manageable at current scale, but inventory reads and conversation writes often have different performance shapes and retention policies. A shared schema is convenient until it becomes a hotspot.

Second, JSON flexibility can mask modeling debt. Prisma can store and filter JSON [S3], and PostgreSQL can index document-like structures [S10], but overusing that path often means business-critical fields stop being reliably queryable. Engineers then compensate with application-side scans or brittle duplicate fields.

Third, schema evolution is a real product risk, not only a migration chore. As the schema evolution literature emphasizes, changes in data shape ripple into code, workflows, and collaboration speed [S7]. Creator tooling is especially exposed because field semantics evolve faster than typical line-of-business CRUD.

Fourth, provenance can be partially specified and still fail in practice. Atlas-style lineage value comes from end-to-end linkage, not isolated metadata tables [S8]. If draft IDs exist but are not consistently attached to publish events, or if royalty claims exist without revision-level lineage, the repository will have provenance-shaped tables without provenance-quality answers.

Implications for This Repository

The practical implication is that Realbits should treat Prisma as the inventory contract for provider assets, not merely the ORM behind /api/characters.

Concretely, the next durable step is to keep identity, ownership, publish state, app targeting, and payout hooks normalized; keep Json for extensible subdocuments; and introduce immutable revision records before publish. Indexes should reflect product access paths first, not hypothetical search features [S4] [S10]. Explicit join models should be preferred wherever relationships may later carry royalties, compatibility metadata, or moderation state [S2].

Most importantly, the schema should encode provenance at publish time: source draft, source revision, evaluator version, target runtime assumptions, mint or escrow references, and actor identity. That recommendation is less about compliance theater than about preserving future leverage. In a provider-managed character economy, inventory that cannot be traced cannot be trusted, and inventory that cannot be trusted is hard to monetize or govern [S8] [S9].

If Realbits follows that path, Prisma is not just an implementation convenience. It becomes the typed, queryable backbone that keeps creator tooling, provider policy, and downstream app consumption aligned as the repository evolves.

References

• S1: https://www.prisma.io/docs/orm/v6/prisma-schema/overview
• S2: https://www.prisma.io/docs/orm/prisma-schema/data-model/relations
• S3: https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/working-with-json-fields
• S4: https://docs.prisma.io/docs/orm/prisma-schema/data-model/indexes
• S5: https://docs.prisma.io/docs/v6/orm/overview/databases/postgresql
• S6: https://nextjs.org/docs/app/getting-started/route-handlers
• S7: https://arxiv.org/abs/2412.06269
• S8: https://arxiv.org/abs/2502.19567
• S9: https://arxiv.org/abs/2601.09966
• S10: https://www.postgresql.org/docs/current/gin.html

Source Ledger

• [S1] Prisma schema overview (official-doc): https://www.prisma.io/docs/orm/v6/prisma-schema/overview - Explains that the Prisma schema defines the data model and drives generated client code and migrations.
• [S2] Prisma relations documentation (official-doc): https://www.prisma.io/docs/orm/prisma-schema/data-model/relations - Defines relation fields, relation scalar fields, and the tradeoff between implicit and explicit many-to-many modeling.
• [S3] Prisma JSON fields documentation (official-doc): https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/working-with-json-fields - Describes how Prisma reads, writes, and filters Json fields, including their flexibility and typing limits.
• [S4] Prisma indexes documentation (official-doc): https://docs.prisma.io/docs/orm/prisma-schema/data-model/indexes - Documents Prisma index declarations and PostgreSQL-specific index access methods such as Gin and Brin.
• [S5] Prisma PostgreSQL connector documentation (official-doc): https://docs.prisma.io/docs/v6/orm/overview/databases/postgresql - Shows PostgreSQL connector behavior, including Json to jsonb mapping and schema-oriented connection configuration.
• [S6] Next.js Route Handlers (official-doc): https://nextjs.org/docs/app/getting-started/route-handlers - Explains the request-handler model used by App Router APIs that commonly front Prisma-backed mutations.
• [S7] Schema Evolution in Interactive Programming Systems (arxiv): https://arxiv.org/abs/2412.06269 - Provides a research framing for schema evolution as a collaboration and feedback-loop problem, not only a database problem.
• [S8] Atlas: A Framework for ML Lifecycle Provenance & Transparency (arxiv): https://arxiv.org/abs/2502.19567 - Motivates stronger provenance and lineage metadata for model and asset pipelines.
• [S9] A Sustainable AI Economy Needs Data Deals That Work for Generators (arxiv): https://arxiv.org/abs/2601.09966 - Argues that missing provenance and opaque compensation weaken creator-facing AI economies, which is relevant to royalty-aware inventory systems.
• [S10] PostgreSQL GIN Indexes (official-doc): https://www.postgresql.org/docs/current/gin.html - Explains what GIN indexes are optimized for and why they fit composite or document-like search workloads.