Database Access (@wrelik/db)

Relevant source files

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

• README.md
• DECISIONS.md
• packages/db/package.json
• packages/eslint-config/index.js
• packages/db/CHANGELOG.md
• CONTRIBUTING.md

The @wrelik/db package serves as the centralized database abstraction layer for the Wrelik ecosystem. It provides a Prisma client singleton and tenant-context helpers designed to enforce safe multi-tenant access patterns across all consuming applications. By acting as a vendor-agnostic adapter, it ensures that application code interacts with the database through a controlled boundary rather than utilizing vendor SDKs directly.

The architecture follows a "Postgres-first" principle, utilizing Neon as the primary serverless Postgres provider. This package is treated as critical infrastructure, emphasizing stability and explicit boundaries to allow for vendor replacement with minimal impact on application logic.

Sources: README.md:12-35, DECISIONS.md:5-15

Architecture and Vendor Integration

The database layer is built upon the Prisma ORM, specifically integrated with Neon for serverless Postgres scaling. This combination is chosen for its developer experience (DX) and ability to scale in serverless environments.

Core Components

Component	Technology	Role
ORM	Prisma	Provides the client singleton and schema management.
Provider	Neon	Serverless Postgres database hosting.
Enforcement	ESLint	Prevents direct imports of @prisma/client in apps.
Dependencies	@wrelik/errors	Handles database-specific application errors.

Sources: DECISIONS.md:8, packages/db/package.json:17, packages/eslint-config/index.js:25-28

Integration Flow

The following diagram illustrates how applications interact with the database through the @wrelik/db adapter.

This flow ensures that applications remain decoupled from the underlying database provider. If the provider changes, only the adapter package needs modification.

Sources: README.md:12-20, DECISIONS.md:18-22

Implementation Details

Package Structure

The package is developed using TypeScript and bundled using tsup. It exports both CommonJS and ESM formats, along with TypeScript definitions to maintain type safety across the monorepo.

• Entry Point: src/index.ts
• Scripts:
  • build: Generates distribution files using tsup.
  • test: Executes tests using vitest.
• Internal Dependencies: Relies on @wrelik/errors for centralized error tracking and Sentry integration.

Sources: packages/db/package.json:9-17, CONTRIBUTING.md:14-18

Safety and Multi-Tenancy

The package is explicitly designed to handle tenant-context helpers. While the specific implementation of these helpers is contained within the source, the package's primary goal is to enforce safe access patterns, ensuring data isolation between different organizational units or users.

Sources: README.md:33-35

Dependency Constraints

To maintain the integrity of the adapter-first architecture, the repository enforces strict import rules via @wrelik/eslint-config. Developers are prohibited from importing the Prisma client directly into application code.

Restricted Import	Required Alternative	Reason
@prisma/client	@wrelik/db	Standardize integration and reduce vendor lock-in.

Sources: packages/eslint-config/index.js:25-28, DECISIONS.md:18-22

Development and Release Lifecycle

Changes to the database package follow a structured release process using Changesets to manage versioning and changelogs.

1. Modification: Developers implement changes in packages/db/src/index.ts.
2. Versioning: A changeset is created via pnpm changeset, identifying the impact (patch/minor/major).
3. CI/CD: On merge to main, the GitHub Action triggers a versioning PR.
4. Publishing: Merging the versioning PR publishes the updated package to the registry.

Sources: CONTRIBUTING.md:27-46, packages/db/CHANGELOG.md:3-15

Conclusion

@wrelik/db provides a robust, standardized interface for database operations within the Wrelik ecosystem. By wrapping Prisma and Neon, it enforces best practices, simplifies the API for application developers, and ensures that the infrastructure remains flexible and decoupled from specific vendor implementations.