Skip to content
Leverage AI Developer Support

MongoDB

MongoDB is the primary durable document store used by the repo’s auth, CMS, API metadata, and Mastra runtime paths.

What It Owns

Section titled “What It Owns”
  • apps/auth stores Better Auth state through the Better Auth MongoDB adapter.
  • apps/cms-customer and apps/cms-leverage store Payload documents through @payloadcms/db-mongodb.
  • apps/api stores API-owned metadata through Prisma’s MongoDB connector.
  • Mastra runtime memory and workflow state use @mastra/mongodb.
  • Local development uses mongo:8.2.4-noble as a replica set in docker-compose.yml.

Why This Dependency

Section titled “Why This Dependency”
  • It matches the document-heavy data shapes in auth, CMS content, connector metadata, and runtime memory.
  • It is the canonical metadata and policy system-of-record for connector runtime data and governance metadata.
  • It lets Payload store complex document shapes close to the Payload field schema.
  • Prisma can type API-owned MongoDB collections while MongoDB keeps document flexibility.
  • Mastra’s MongoDB store makes chat memory and workflow state durable across API restarts.
  • Better Auth’s MongoDB adapter does not require generated schema migrations, and its experimental joins can improve related-data endpoints by roughly 2x to 3x depending on database latency.
  • MongoDB 8.0 release notes call out read, web-app, replication-write, and bulk-write performance improvements versus MongoDB 7.0. The repo’s local image is already on the MongoDB 8 line.

Architecture Decision

Section titled “Architecture Decision”

Decision: use MongoDB as the shared document database technology, while keeping logical ownership boundaries separate by app, env var, credential, and database.

Do not turn shared infrastructure into shared ownership. Auth, API, customer CMS, Leverage CMS, and Mastra collections have different owners and must not raw-read each other’s persistence as a shortcut.

How To Upgrade

Section titled “How To Upgrade”

  1. Check MongoDB release notes, driver compatibility, and adapter compatibility for Better Auth, Payload, Prisma, Mastra, and the root mongodb package.

  2. Upgrade the local Docker image in docker-compose.yml only after checking the MongoDB upgrade path. MongoDB’s 8.0 replica-set upgrade docs require 7.0-series members before moving to 8.0 and require driver compatibility checks.

  3. Upgrade the Node driver where it is directly pinned:

    Terminal window
    bun update mongodb

  4. Re-run the app lanes that exercise each owner:

    Terminal window
    bun run test:auth
    bun run test:cms-customer:int
    bun run test:cms-leverage:int
    bun run --cwd apps/api check-types
    bun run --cwd apps/api db:audit-drift

  5. For production or customer-cluster MongoDB upgrades, use an explicit runbook. Do not mutate or repair stored user/operator data without approval.

Current Limits

Section titled “Current Limits”
  • apps/api Prisma models cover only API-owned MongoDB collections.
  • Mastra-owned collections use Mastra storage APIs and the mastra_ collection prefix.
  • Better Auth raw Mongo shapes are not guessed. Use Better Auth APIs/helpers first.
  • Payload CMS databases stay separate between cms-customer and cms-leverage.

Canonical Sources

Section titled “Canonical Sources”
  • docker-compose.yml
  • apps/api/prisma/schema.prisma
  • apps/api/src/mastra/runtimeStorage.ts
  • apps/api/src/env.ts
  • apps/auth/package.json
  • apps/cms-customer/package.json
  • apps/cms-leverage/package.json
  • docs/features/connectors/spec.md
  • docs/features/governance/spec.md
  • docs/features/chat/spec.md
  • docs/features/cms-control-plane-split/spec.md

Official Docs

Section titled “Official Docs”