Database Package (`packages/db`)

The packages/db package serves as the dedicated database access layer for the monorepo. It is responsible for defining the database schema, providing a configured database client, and managing database migrations. It utilizes Drizzle ORM to interact with a PostgreSQL database, offering a type-safe interface for other packages, primarily the apps/api server, to perform data operations.

This package encapsulates all database-related logic, ensuring a clear separation of concerns within the project. It exposes the Drizzle client instance, the complete database schema, and core Drizzle ORM functionalities for consumption by other parts of the application.

Sources: README.md, packages/db/package.json, packages/db/src/index.ts

Architecture and Core Technologies

The packages/db package is built on a foundation of Drizzle ORM and PostgreSQL. This combination provides a modern, TypeScript-centric approach to database management.

• Drizzle ORM: A TypeScript ORM used for schema definition and querying.
• PostgreSQL: The underlying relational database.
• pg: The Node.js driver used by Drizzle to connect to the PostgreSQL database.

Sources: README.md:28-30, packages/db/package.json:20-22

The following diagram illustrates the technology stack for the database package.

Package Exports

The public API of the packages/db package is defined by its entry points in package.json and the re-exports in src/index.ts. It provides two main entry points for consumers: the default . export and a specific ./schema export.

• @contract-based-monorepo/db: The main entry point exports the Drizzle client instance (db), the collected schema objects, and all named exports from the drizzle-orm library itself.
• @contract-based-monorepo/db/schema: This provides direct access to the database schema definitions.

Sources: packages/db/package.json:5-11, packages/db/src/index.ts:1-3

// packages/db/src/index.ts
export * from "./db";
export * as schema from "./schema";
export * from "drizzle-orm";

Sources: packages/db/src/index.ts:1-3

Database Schema

While the specific schema files are not fully detailed in the provided context, their structure can be inferred from their usage in other packages, particularly in apps/api/src/lib/auth.ts for authentication and packages/contract/src/schemas/planet.ts for application data.

The schema includes tables required by the better-auth library and application-specific tables like planets.

• user: Stores user profile information.
• session: Manages user session data for authentication.
• account: Used for linking multiple provider accounts (e.g., OAuth) to a single user.
• verification: Stores tokens for processes like email verification.
• planets: An example application table to store planet data.

Sources: apps/api/src/lib/auth.ts:13-18, packages/contract/src/schemas/planet.ts, apps/api/src/middlewares/db.ts:38-65

The following ER diagram shows the inferred relationships between these tables.

Management Scripts

The package includes several npm scripts for managing the database schema and development environment. These scripts use drizzle-kit for migrations and dotenv-cli to load environment variables from the monorepo root.

Sources: packages/db/package.json:13-17, README.md:68-70

Integration and Usage

The packages/db module is primarily consumed by the apps/api package to handle data persistence. A key example is its integration with the better-auth library.

Authentication Adapter

The better-auth instance in the API is configured with a drizzleAdapter. This adapter is initialized with the db client and the required schema tables (user, session, account, verification) exported from the packages/db package.

// apps/api/src/lib/auth.ts
import { db, schema } from "@contract-based-monorepo/db";
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
// ...

export const auth = betterAuth({
  // ...
  database: drizzleAdapter(db, {
    provider: "pg",
    schema: {
      user: schema.user,
      session: schema.session,
      account: schema.account,
      verification: schema.verification,
    },
  }),
});

Sources: apps/api/src/lib/auth.ts:1-19

The following diagram illustrates the sequence of initializing the authentication module with the database adapter.

API Middleware

The API application uses middleware to provide database access to request handlers. While the provided dbProviderMiddleware uses a mock database, it establishes the architectural pattern where a db context is injected into the request lifecycle for use by downstream procedures. This pattern is designed to work with the real db client from this package in a production scenario.

Sources: apps/api/src/middlewares/db.ts:14-28