prisma: Architecture

Architecture health: 30/100 (F)

Overview

prisma is a TypeScript pnpm monorepo, built with React. It is a library of 52 packages. It stores data in SQLite, PostgreSQL, PostgreSQL (Neon), MySQL, MongoDB, and Prisma and integrates with GitHub. The main structural risks to watch: 15 oversized "god" files and 7 circular import chains. The file with the widest blast radius is packages/client/tests/functional/_utils/providers.ts: 347 files depend on it at runtime.

_This entire analysis runs on your machine with no AI required. Connect a model provider to also narrate the reasoning and recover decisions._

Where to start

1. packages/adapter-better-sqlite3/src/index.ts Start here: how the system boots and wires its subsystems together.
2. packages/client/tests/functional/_utils/providers.ts Core module: 347 other modules depend on it, so it shapes much of the system.
3. packages/config/src/defineConfig.ts Core module: 304 other modules depend on it, so it shapes much of the system.
4. packages/client/tests/functional/_utils/defineMatrix.ts Core module: 220 other modules depend on it, so it shapes much of the system.
5. packages/client/tests/functional/_utils/idForProvider.ts Core module: 185 other modules depend on it, so it shapes much of the system.
6. packages/credentials-store/src/index.ts Key flow: Authentication, a high-risk path that enters at invoke index.ts (packages/credentials-store/src/index.ts).
7. packages/param-graph-builder/src/index.ts Key flow: Mission execution, a high-risk path that enters at invoke index.ts (packages/param-graph-builder/src/index.ts).
8. packages/adapter-d1/src/d1-worker.ts Key flow: Background jobs, a medium-risk path that enters at scheduled trigger (packages/adapter-d1/src/d1-worker.ts).

System map

flowchart TD
  subgraph sys_boundary["prisma"]
    adapter_better_sqlite3["adapter-better-sqlite3"]
    adapter_d1["adapter-d1"]
    adapter_libsql["adapter-libsql"]
    adapter_mariadb["adapter-mariadb"]
    adapter_mssql["adapter-mssql"]
    adapter_neon["adapter-neon"]
    adapter_pg["adapter-pg"]
    adapter_planetscale["adapter-planetscale"]
    adapter_ppg["adapter-ppg"]
    bundle_size["bundle-size"]
    prisma["prisma"]
    client["client"]
    client_common["client-common"]
    client_engine_runtime["client-engine-runtime"]
    client_generator_js["client-generator-js"]
    client_generator_registry["client-generator-registry"]
    client_generator_ts["client-generator-ts"]
    client_runtime_utils["client-runtime-utils"]
    config["config"]
    credentials_store["credentials-store"]
    debug["debug"]
    dmmf["dmmf"]
    driver_adapter_utils["driver-adapter-utils"]
    engines["engines"]
    fetch_engine["fetch-engine"]
    generator["generator"]
    generator_helper["generator-helper"]
    get_dmmf["get-dmmf"]
    get_platform["get-platform"]
    instrumentation["instrumentation"]
    instrumentation_contract["instrumentation-contract"]
    integration_tests["integration-tests"]
    internals["internals"]
    json_protocol["json-protocol"]
    migrate["migrate"]
    blog["blog"]
    nextjs_monorepo_workaround_plugin["nextjs-monorepo-workaround-plugin"]
    param_graph["param-graph"]
    param_graph_builder["param-graph-builder"]
    query_plan_executor["query-plan-executor"]
    schema_files_loader["schema-files-loader"]
    sqlcommenter["sqlcommenter"]
    sqlcommenter_query_insights["sqlcommenter-query-insights"]
    sqlcommenter_query_tags["sqlcommenter-query-tags"]
    sqlcommenter_trace_context["sqlcommenter-trace-context"]
    ts_builders["ts-builders"]
    type_benchmark_tests["type-benchmark-tests"]
    basic_postgres["basic-postgres"]
    basic_sqlite["basic-sqlite"]
    d1["d1"]
    tracing["tracing"]
    collapsed_units["7 more units, no cross-unit imports: bundled-js-drivers, SQLite, PostgreSQL +4"]
  end
  ext_github{{"GitHub"}}
  adapter_better_sqlite3 -->|uses| driver_adapter_utils
  adapter_d1 -->|uses| driver_adapter_utils
  adapter_libsql -->|uses| driver_adapter_utils
  adapter_mariadb -->|uses| driver_adapter_utils
  adapter_mssql -->|uses| driver_adapter_utils
  adapter_neon -->|uses| debug
  adapter_neon -->|uses| driver_adapter_utils
  adapter_pg -->|uses| debug
  adapter_pg -->|uses| driver_adapter_utils
  adapter_planetscale -->|uses| driver_adapter_utils
  adapter_ppg -->|uses| driver_adapter_utils
  bundle_size -->|uses| adapter_mariadb
  bundle_size -->|uses| adapter_mssql
  bundle_size -->|uses| adapter_neon
  bundle_size -->|uses| config
  bundle_size -->|uses| adapter_pg
  bundle_size -->|uses| adapter_planetscale
  prisma -->|uses| internals
  prisma -->|uses| config
  prisma -->|uses| engines
  prisma -->|uses| fetch_engine
  prisma -->|uses| client_generator_registry
  prisma -.->|types only| generator
  prisma -->|uses| debug
  prisma -->|uses| get_platform
  prisma -->|uses| driver_adapter_utils
  prisma -->|uses| migrate
  prisma -->|uses| generator_helper
  prisma -->|uses| adapter_pg
  prisma -->|uses| credentials_store
  prisma -.->|types only| dmmf
  client -->|uses| config
  client -->|uses| internals
  client -->|uses| dmmf
  client -->|uses| client_common
  client -->|uses| client_engine_runtime
  client -.->|types only| json_protocol
  client -->|uses| param_graph
  client -->|uses| param_graph_builder
  client -->|uses| adapter_better_sqlite3
  client -->|uses| client_runtime_utils
  client -->|uses| migrate
  client -->|uses| adapter_pg
  client -->|uses| debug
  client -->|uses| instrumentation_contract
  client -.->|types only| driver_adapter_utils
  client -.->|types only| generator
  client -.->|types only| sqlcommenter
  client -.->|types only| get_platform
  client -->|uses| ts_builders
  client -->|uses| client_generator_js
  client -.->|types only| schema_files_loader
  client -->|uses| adapter_mariadb
  client -->|uses| adapter_neon
  client -->|uses| generator_helper
  client -->|uses| nextjs_monorepo_workaround_plugin
  client -->|uses| adapter_planetscale
  client -->|uses| sqlcommenter_query_insights
  client -->|uses| sqlcommenter_query_tags
  client -->|uses| instrumentation
  client -->|uses| sqlcommenter_trace_context
  client -->|uses| query_plan_executor
  client -->|uses| client_generator_ts
  client -->|uses| prisma
  client -->|uses| adapter_mssql
  client_common -.->|types only| client_engine_runtime
  client_common -.->|types only| driver_adapter_utils
  client_common -.->|types only| generator
  client_common -.->|types only| param_graph
  client_common -->|uses| dmmf
  client_engine_runtime -->|uses| driver_adapter_utils
  client_engine_runtime -->|uses| client_runtime_utils
  client_engine_runtime -.->|types only| sqlcommenter
  client_engine_runtime -.->|types only| json_protocol
  client_engine_runtime -->|uses| get_dmmf
  client_engine_runtime -->|uses| param_graph
  client_engine_runtime -->|uses| param_graph_builder
  client_engine_runtime -->|uses| debug
  client_generator_js -->|uses| dmmf
  client_generator_js -->|uses| client_common
  client_generator_js -->|uses| ts_builders
  client_generator_js -.->|types only| generator
  client_generator_js -->|uses| internals
  client_generator_js -->|uses| client
  client_generator_js -->|uses| adapter_pg
  client_generator_js -->|uses| param_graph_builder
  client_generator_js -->|uses| debug
  client_generator_js -->|uses| config
  client_generator_registry -->|uses| client_generator_js
  client_generator_registry -->|uses| client_generator_ts
  client_generator_registry -.->|types only| generator
  client_generator_registry -.->|types only| internals
  client_generator_ts -->|uses| dmmf
  client_generator_ts -->|uses| client_common
  client_generator_ts -->|uses| ts_builders
  client_generator_ts -.->|types only| generator
  client_generator_ts -->|uses| internals
  client_generator_ts -->|uses| client
  client_generator_ts -->|uses| param_graph_builder
  client_generator_ts -->|uses| adapter_pg
  client_generator_ts -->|uses| debug
  client_generator_ts -->|uses| config
  config -->|uses| debug
  config -->|uses| get_platform
  driver_adapter_utils -->|uses| debug
  engines -->|uses| debug
  engines -->|uses| fetch_engine
  engines -->|uses| get_platform
  fetch_engine -->|uses| get_platform
  fetch_engine -->|uses| debug
  generator -.->|types only| dmmf
  generator_helper -->|uses| debug
  generator_helper -.->|types only| generator
  generator_helper -.->|types only| dmmf
  get_dmmf -->|uses| debug
  get_dmmf -.->|types only| dmmf
  get_platform -->|uses| debug
  instrumentation -->|uses| instrumentation_contract
  integration_tests -->|uses| migrate
  integration_tests -->|uses| adapter_libsql
  integration_tests -->|uses| adapter_mariadb
  integration_tests -->|uses| adapter_mssql
  integration_tests -->|uses| adapter_pg
  integration_tests -->|uses| client
  integration_tests -.->|types only| driver_adapter_utils
  integration_tests -->|uses| internals
  integration_tests -->|uses| client_runtime_utils
  internals -.->|types only| generator
  internals -->|uses| generator_helper
  internals -.->|types only| driver_adapter_utils
  internals -->|uses| config
  internals -->|uses| get_platform
  internals -->|uses| get_dmmf
  internals -->|uses| engines
  internals -->|uses| debug
  internals -->|uses| schema_files_loader
  internals -.->|types only| dmmf
  internals -->|uses| fetch_engine
  blog -->|uses| config
  migrate -->|uses| config
  migrate -->|uses| internals
  migrate -->|uses| debug
  migrate -.->|types only| driver_adapter_utils
  migrate -->|uses| get_platform
  migrate -.->|types only| get_dmmf
  migrate -.->|types only| generator
  param_graph_builder -->|uses| dmmf
  param_graph_builder -->|uses| param_graph
  query_plan_executor -->|uses| client_engine_runtime
  query_plan_executor -->|uses| driver_adapter_utils
  query_plan_executor -->|uses| adapter_pg
  query_plan_executor -->|uses| adapter_mariadb
  query_plan_executor -->|uses| adapter_mssql
  sqlcommenter -.->|types only| json_protocol
  sqlcommenter_query_insights -.->|types only| sqlcommenter
  sqlcommenter_query_tags -.->|types only| sqlcommenter
  sqlcommenter_trace_context -->|uses| instrumentation_contract
  sqlcommenter_trace_context -.->|types only| sqlcommenter
  ts_builders -->|uses| internals
  type_benchmark_tests -->|uses| config
  basic_postgres -->|uses| adapter_pg
  basic_postgres -->|uses| config
  basic_sqlite -->|uses| adapter_better_sqlite3
  basic_sqlite -->|uses| config
  d1 -->|uses| config
  tracing -->|uses| instrumentation
  tracing -->|uses| config
  class adapter_better_sqlite3 library
  class adapter_d1 library
  class adapter_libsql library
  class adapter_mariadb library
  class adapter_mssql library
  class adapter_neon library
  class adapter_pg library
  class adapter_planetscale library
  class adapter_ppg library
  class bundle_size library
  class prisma library
  class client library
  class client_common library
  class client_engine_runtime library
  class client_generator_js library
  class client_generator_registry library
  class client_generator_ts library
  class client_runtime_utils library
  class config library
  class credentials_store library
  class debug library
  class dmmf library
  class driver_adapter_utils library
  class engines library
  class fetch_engine library
  class generator library
  class generator_helper library
  class get_dmmf library
  class get_platform library
  class instrumentation library
  class instrumentation_contract library
  class integration_tests library
  class internals library
  class json_protocol library
  class migrate library
  class blog library
  class nextjs_monorepo_workaround_plugin library
  class param_graph library
  class param_graph_builder library
  class query_plan_executor library
  class schema_files_loader library
  class sqlcommenter library
  class sqlcommenter_query_insights library
  class sqlcommenter_query_tags library
  class sqlcommenter_trace_context library
  class ts_builders library
  class type_benchmark_tests library
  class basic_postgres library
  class basic_sqlite library
  class d1 library
  class tracing library
  class ext_github external
  class collapsed_units muted
  %% collapsed (no cross-unit imports): bundled-js-drivers, SQLite, PostgreSQL, PostgreSQL Neon, MySQL, MongoDB, Prisma
  classDef frontend fill:#2563eb,stroke:#93c5fd,color:#fff,stroke-width:2px;
  classDef service fill:#059669,stroke:#6ee7b7,color:#fff,stroke-width:2px;
  classDef store fill:#d97706,stroke:#fcd34d,color:#fff,stroke-width:2px;
  classDef queue fill:#9333ea,stroke:#d8b4fe,color:#fff,stroke-width:2px;
  classDef job fill:#4f46e5,stroke:#a5b4fc,color:#fff,stroke-width:2px;
  classDef external fill:#475569,stroke:#cbd5e1,color:#fff,stroke-width:2px;
  classDef aiprovider fill:#e11d48,stroke:#fda4af,color:#fff,stroke-width:2px;
  classDef library fill:#0891b2,stroke:#67e8f9,color:#fff,stroke-width:2px;
  classDef cli fill:#0d9488,stroke:#5eead4,color:#fff,stroke-width:2px;
  classDef user fill:#64748b,stroke:#e2e8f0,color:#fff,stroke-width:2px;
  classDef muted fill:#334155,stroke:#64748b,color:#cbd5e1,stroke-width:1px;

Critical flows

Application startup medium risk

Entry: process start (packages/adapter-better-sqlite3/src/index.ts)

reads or writes persistent records (database)

Boot wires every subsystem together; a fault here stops the whole process from starting.

sequenceDiagram
  actor C0 as Process
  participant F0 as index.ts
  participant F1 as better-sqlite3.ts
  participant DB as database
  C0->>F0: process start
  F0->>F1: calls
  F1->>DB: reads or writes persistent records

Authentication high risk

Entry: invoke index.ts (packages/credentials-store/src/index.ts)

writes files to the working tree (disk)

Authentication guards every protected resource; a regression here can expose data or grant unauthorized access.

sequenceDiagram
  actor C0 as Caller
  participant F0 as index.ts
  participant F1 as build.ts
  participant Disk as disk
  C0->>F0: invoke index.ts
  F0->>Disk: writes files to the working tree

Mission execution high risk

Entry: invoke index.ts (packages/param-graph-builder/src/index.ts)

Mission execution drives autonomous code changes; errors here corrupt runs or the target repository.

sequenceDiagram
  actor C0 as Caller
  participant F0 as index.ts
  participant F1 as build-param-graph.ts
  participant F2 as dmmf-traverser.ts
  participant F3 as param-graph-builder.ts
  participant F4 as build.ts
  C0->>F0: invoke index.ts
  F0->>F1: calls
  F0->>F2: calls
  F0->>F3: calls

File changes / writes high risk

Entry: invoke index.ts (packages/credentials-store/src/index.ts)

writes files to the working tree (disk)

Direct writes to the working tree are hard to reverse; an unguarded write can clobber user code.

sequenceDiagram
  actor C0 as Caller
  participant F0 as index.ts
  participant Disk as disk
  C0->>F0: invoke index.ts
  F0->>Disk: writes files to the working tree

Background jobs medium risk

Entry: scheduled trigger (packages/adapter-d1/src/d1-worker.ts)

reads or writes persistent records (database)

Background jobs run unattended; failures are silent and can pile up unnoticed.

sequenceDiagram
  actor C0 as Scheduler
  participant F0 as d1-worker.ts
  participant F1 as d1.ts
  participant F2 as index-workerd.ts
  participant DB as database
  C0->>F0: scheduled trigger
  F0->>DB: reads or writes persistent records

Fragile zones

• packages/client/tests/functional/_utils/providers.ts (score 694): 347 files depend on it at runtime
• packages/client/tests/functional/_utils/defineMatrix.ts (score 438.3): 218 files depend on it at runtime
• packages/client/tests/functional/_utils/idForProvider.ts (score 370.3): 185 files depend on it at runtime
• packages/client/tests/e2e/_utils/executeSteps.ts (score 178): 89 files depend on it at runtime
• packages/debug/src/index.ts (score 102): 51 files depend on it at runtime
• packages/client/index.js (score 96): 48 files depend on it at runtime
• helpers/compile/build.ts (score 91.8): 44 files depend on it at runtime
• packages/ts-builders/src/Writer.ts (score 84): 42 files depend on it at runtime
• packages/internals/src/cli/utils.ts (score 74): 37 files depend on it at runtime
• packages/internals/src/cli/Help.ts (score 70): 35 files depend on it at runtime
• packages/adapter-pg/src/pg.ts (score 69.3): 34 files depend on it at runtime
• packages/config/src/defineConfig.ts (score 62.5): 28 files depend on it at runtime; part of an import cycle

Architecture rules