Database Schemas (Prisma & Drizzle)

Relevant source files

The following files were used as context for generating this wiki page:

• apps/server/docker/CLAUDE.md
• apps/server/workers/src/db/comparison-tool.ts
• apps/server/workers/README.md
• apps/admin/web/CLAUDE.md
• apps/admin/api/CLAUDE.md
• CLAUDE.md

Database management in the Happy ecosystem is split across two primary ORM technologies: Prisma for the Node.js Docker-based backend and Drizzle for the Cloudflare Workers edge functions. This dual-schema architecture supports a transition from a centralized PostgreSQL infrastructure to a distributed edge-native environment using Cloudflare D1 (SQLite).

The project maintains a rigorous parity between these schemas to ensure data consistency during the migration phase. A specialized comparison tool is utilized to validate that the Drizzle schema implemented in the edge workers maintains 100% functional parity with the original Prisma baseline, subject to specific architectural adjustments for the edge runtime.

Sources: apps/server/workers/src/db/comparison-tool.ts:1-12, apps/server/workers/README.md:100-110, CLAUDE.md:140-150

Schema Architecture and Environments

The ecosystem utilizes three distinct database implementations depending on the application context:

1. PostgreSQL with Prisma: Powering the happy-server (Docker/Fastify) backend. It handles complex relational data and uses Prisma's migration system.
2. D1 (SQLite) with Drizzle: Powering the happy-server-workers edge API. This is designed for high-performance, globally distributed access with zero-knowledge architecture.
3. D1 with Drizzle (Admin): The happy-admin-api shares the main D1 databases (happy-dev and happy-prod) but focuses on authentication (Better-Auth) and metrics querying via the Analytics Engine.

Sources: CLAUDE.md:140-150, apps/server/docker/CLAUDE.md:15-30, apps/admin/api/CLAUDE.md:20-35

Entity Relationship Mapping

The following ER diagram represents the core tables shared across the Prisma and Drizzle implementations as of the migration baseline.

Core Data Models

The system defines 20 primary tables that constitute the application state. While the Prisma schema is the source of truth, the Drizzle schema includes optimizations for the edge.

Table Definitions and Parity

Table Name	Description	Parity Notes
Account	Central user identity, public keys, and settings.	avatar field removed (frontend-only).
Session	Encrypted Claude Code interaction sessions.	Includes metadataVersion and agentState.
SessionMessage	Encrypted individual messages within a session.	Linked via sid or id.
Machine	Remote CLI instances connected to an account.	Tracks online status and metadata.
Artifact	Code snippets or generated files from sessions.	Versioned and encrypted.
GlobalLock	Distributed lock mechanism for resource sync.	Handled via Cloudflare Durable Objects in edge.
UsageReport	Metrics for AI usage and token consumption.	Queried via Admin Analytics Engine.

Sources: apps/server/workers/src/db/comparison-tool.ts:33-75, apps/server/docker/CLAUDE.md:160-170

Specialized Admin Schemas

The Admin API utilizes the same database but manages specific tables for the Better-Auth integration:

• users: Admin accounts (role-based access).
• sessions: Active web dashboard sessions.
• accounts: Linked authentication providers.
• admin_audit_logs: Tracks role changes and administrative actions (90-day retention).

Sources: apps/admin/api/src/db/schema.ts:1-20, apps/admin/api/CLAUDE.md:220-240

Migration and Transformation Logic

Moving from Prisma (PostgreSQL) to Drizzle (D1/SQLite) requires specific data type transformations and logic shifts.

Structural Adjustments

Because SQLite does not support native Enums or certain PostgreSQL features, the Drizzle implementation applies the following transformations:

• Enums to Text: Enums like RelationshipStatus are migrated to TEXT fields with CHECK constraints.
• Defaults: cuid() defaults are moved from the database level to the application layer.
• Updated At: Prisma's native @updatedAt is replaced by the $onUpdate helper in Drizzle.
• Transactions: Prisma uses inTx wrappers, while Drizzle uses the D1 transaction API.

Sources: apps/server/workers/src/db/comparison-tool.ts:115-135, apps/server/docker/CLAUDE.md:155-165

Parity Verification Flow

The project employs a comparison-tool.ts to ensure the Drizzle schema matches the Prisma baseline during development.

Database Management Commands

Prisma (Server-Docker)

Prisma is managed via the Yarn CLI within the apps/server/docker directory.

yarn db        # Start local PostgreSQL in Docker
yarn migrate   # Run Prisma migrations
yarn generate  # Generate Prisma client types

Sources: apps/server/docker/CLAUDE.md:35-45

Drizzle (Workers & Admin)

Drizzle migrations for Cloudflare D1 are managed via Wrangler.

yarn db:generate  # Generate migrations from schema.ts
yarn db:migrate   # Apply to local D1
yarn db:migrate:prod # Apply to production D1
yarn db:studio    # Open GUI for data exploration

Sources: apps/server/workers/README.md:130-145, apps/admin/api/CLAUDE.md:85-95

Conclusion

The database architecture of the Happy ecosystem represents a hybrid approach to state management. By maintaining strict parity between Prisma/PostgreSQL and Drizzle/D1, the system ensures that the core entity relationships—Accounts, Sessions, and Machines—remain consistent whether accessed via the legacy Docker backend or the modern distributed edge API. The use of specialized tools for schema comparison ensures that structural changes like the removal of the avatar field or the conversion of enums to check constraints do not introduce regression during the ongoing migration to Cloudflare's edge infrastructure.

Sources: apps/server/workers/src/db/comparison-tool.ts:125-140, CLAUDE.md:230-245