# fuma-nama/fumadb architecture

> Architecture diagram of the GitHub repository fuma-nama/fumadb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fuma-nama/fumadb
- Repository: https://github.com/fuma-nama/fumadb

## Overview

##### Project type and purpose
- This is an open-source TypeScript monorepo, managed with pnpm and Turborepo.
- It contains:
- FumaDB: a unified database API library for other libraries (packages/fumadb).
- Documentation site: a Next.js app under apps/docs.
- Example apps: simple usage under examples/basic.
- Purpose: Provide a single API surface over multiple ORMs/adapters (Prisma, Drizzle, TypeORM, Kysely, MongoDB, Convex), plus CLI tools, schema generation/migration, and query building.

##### File structure
- Root
- pnpm-workspace.yaml, turbo.json: orchestrate tasks across workspaces.
- CI workflows (.github/workflows): lint, test, release.
- apps/docs
- Next.js 13+ app directory (app/, components/, content/, lib/).
- Serves documentation pages, MDX content.
- examples/basic
- A minimal consumer project showing integration with FumaDB and adapters.
- packages/fumadb
- Core library code under src/:
– adapters/: adapter implementations for each ORM.
– query/: condition builders, ORM-specific query implementations, polyfills.
– schema/: introspection, migration, generation, serialization.
– cli/: command-line interface entrypoint.
– shared, utils: common utilities.
- Tests under test/.
- Config (tsup, vitest, tsconfig).
- packages/typescript-config
- Shared TS configurations for libraries and Next.js.

##### README for additional insights
- Emphasizes FumaDB is built for library authors and unifies multiple database backends.

##### Elements
- Clear labels for:
- Monorepo root (workspace manager, CI/CD)
- FumaDB core modules (schema, query, CLI)
- Adapter implementations
- Docs site and example app as consumers
- External database engines
- From consumers → library API
- From library adapters → external databases
- From CLI → schema & migration modules → database
- CI/CD → build/test/publish workflows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Orchestration Layer
    subgraph "Monorepo Orchestrator" 
        direction TB
        PNPM["pnpm-workspace.yaml"]:::orchestration
        TURBO["turbo.json"]:::orchestration
        ROOTPKG["package.json"]:::orchestration
    end

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines" 
        direction TB
        LINT["lint.yml"]:::cicd
        TEST["test.yml"]:::cicd
        RELEASE["release.yml"]:::cicd
    end

    %% FumaDB Core Library
    subgraph "FumaDB Core Library" 
        direction TB
        CORE["index.ts"]:::core

        subgraph "CLI Module" 
            direction TB
            CLI["cli/index.ts"]:::module
        end

        subgraph "Schema Module"
            direction TB
            S_INDEX["schema/index.ts"]:::module
            S_CREATE["schema/create.ts"]:::module
            S_INTROSPECT["schema/introspect.ts"]:::module
            S_MIGRATE["schema/migrate"]:::module
            S_GENERATE["schema/generate"]:::module
            S_SERIALIZE["schema/serialize.ts"]:::module
            S_VALIDATE["schema/validate.ts"]:::module
        end

        subgraph "Query Module"
            direction TB
            Q_INDEX["query/index.ts"]:::module
            Q_COND["query/condition-builder.ts"]:::module
            Q_ORM["query/orm"]:::module
            Q_POLY["query/polyfills"]:::module
        end

        subgraph "Adapters"
            direction TB
            A_INDEX["adapters/index.ts"]:::adapter
            A_PRISMA["adapters/prisma.ts"]:::adapter
            A_DRIZZLE["adapters/drizzle.ts"]:::adapter
            A_KYSLEY["adapters/kysely.ts"]:::adapter
            A_TYPEORM["adapters/typeorm.ts"]:::adapter
            A_MONGODB["adapters/mongodb.ts"]:::adapter
            A_CONVEX["convex"]:::adapter
        end
    end

    %% Consumers
    subgraph "Consumers"
        direction TB
        DOCS["Documentation Site (apps/docs)"]:::consumer
        EXAMPLE["Example App (examples/basic)"]:::consumer
    end

    %% External Databases
    subgraph "External Databases"
        direction TB
        POSTGRES["PostgreSQL"]:::database
        MYSQL["MySQL"]:::database
        SQLITE["SQLite"]:::database
        MONGO["MongoDB"]:::database
        COCKROACH["CockroachDB"]:::database
        CONVEXDB["Convex"]:::database
    end

    %% Relationships
    PNPM -->|manages| CORE
    TURBO -->|orchestrates| CORE
    ROOTPKG -->|defines workspaces| CORE
    PNPM -->|triggers| LINT
    PNPM -->|triggers| TEST
    PNPM -->|triggers| RELEASE
    LINT -->|runs on| CORE
    TEST -->|runs on| CORE
    RELEASE -->|publishes| CORE

    DOCS -->|imports| CORE
    EXAMPLE -->|imports| CORE

    CLI -->|invokes| S_INDEX
    S_INDEX -->|uses| A_INDEX
    S_CREATE -->|uses| A_INDEX
    S_INTROSPECT -->|uses| A_INDEX
    S_MIGRATE -->|uses| A_INDEX
    S_GENERATE -->|uses| A_INDEX
    S_SERIALIZE -->|uses| A_INDEX
    S_VALIDATE -->|uses| A_INDEX

    Q_INDEX -->|uses| A_INDEX
    Q_COND -->|builds conditions| Q_INDEX
    Q_ORM -->|implements| Q_INDEX
    Q_POLY -->|polyfills| Q_INDEX

    A_PRISMA -->|connects| POSTGRES
    A_PRISMA -->|connects| MYSQL
    A_DRIZZLE -->|connects| POSTGRES
    A_DRIZZLE -->|connects| SQLITE
    A_KYSLEY -->|connects| POSTGRES
    A_TYPEORM -->|connects| POSTGRES
    A_TYPEORM -->|connects| MYSQL
    A_MONGODB -->|connects| MONGO
    A_CONVEX -->|connects| CONVEXDB

    CORE --> CLI
    CORE --> S_INDEX
    CORE --> Q_INDEX
    CORE --> A_INDEX

    %% Click Events
    click PNPM "https://github.com/fuma-nama/fumadb/blob/dev//pnpm-workspace.yaml"
    click TURBO "https://github.com/fuma-nama/fumadb/blob/dev//turbo.json"
    click ROOTPKG "https://github.com/fuma-nama/fumadb/blob/dev//package.json"
    click LINT "https://github.com/fuma-nama/fumadb/blob/dev//.github/workflows/lint.yml"
    click TEST "https://github.com/fuma-nama/fumadb/blob/dev//.github/workflows/test.yml"
    click RELEASE "https://github.com/fuma-nama/fumadb/blob/dev//.github/workflows/release.yml"
    click DOCS "https://github.com/fuma-nama/fumadb/tree/dev//apps/docs"
    click EXAMPLE "https://github.com/fuma-nama/fumadb/tree/dev//examples/basic"
    click CORE "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/index.ts"
    click CLI "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/cli/index.ts"
    click S_INDEX "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/schema/index.ts"
    click S_CREATE "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/schema/create.ts"
    click S_INTROSPECT "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/schema/introspect.ts"
    click S_MIGRATE "https://github.com/fuma-nama/fumadb/tree/dev//packages/fumadb/src/schema/migrate"
    click S_GENERATE "https://github.com/fuma-nama/fumadb/tree/dev//packages/fumadb/src/schema/generate"
    click S_SERIALIZE "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/schema/serialize.ts"
    click S_VALIDATE "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/schema/validate.ts"
    click Q_INDEX "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/query/index.ts"
    click Q_COND "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/query/condition-builder.ts"
    click Q_ORM "https://github.com/fuma-nama/fumadb/tree/dev//packages/fumadb/src/query/orm"
    click Q_POLY "https://github.com/fuma-nama/fumadb/tree/dev//packages/fumadb/src/query/polyfills"
    click A_INDEX "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/adapters/index.ts"
    click A_PRISMA "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/adapters/prisma.ts"
    click A_DRIZZLE "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/adapters/drizzle.ts"
    click A_KYSLEY "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/adapters/kysely.ts"
    click A_TYPEORM "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/adapters/typeorm.ts"
    click A_MONGODB "https://github.com/fuma-nama/fumadb/blob/dev//packages/fumadb/src/adapters/mongodb.ts"
    click A_CONVEX "https://github.com/fuma-nama/fumadb/tree/dev//packages/fumadb/src/convex"
    
    %% Styles
    classDef orchestration fill:#f9f,stroke:#333,stroke-width:1px
    classDef cicd fill:#ff9,stroke:#333,stroke-width:1px
    classDef core fill:#9ff,stroke:#333,stroke-width:1px
    classDef module fill:#aff,stroke:#333,stroke-width:1px
    classDef adapter fill:#fea,stroke:#333,stroke-width:1px
    classDef consumer fill:#afa,stroke:#333,stroke-width:1px
    classDef database fill:#ddd,stroke:#333,stroke-width:1px
```
