prisma: Architecture

Architecture health: 48/100 (F)

Overview

prisma is a JavaScript/TypeScript pnpm monorepo, built with React, Next.js, and Vite. It runs as 6 frontends (lsp-playground, mongo-demo, prisma-8-demo, prisma-8-postgis-demo, react-router-demo, retail-store), backed by 97 shared packages. It stores data in PostgreSQL, MySQL, MongoDB, and Prisma. The main structural risks to watch: 15 oversized "god" files and 2 circular import chains. The file with the widest blast radius is packages/1-framework/3-tooling/cli/src/utils/cli-errors.ts: 55 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. apps/lsp-playground/ Start here: the primary entry point of the system.
2. packages/2-sql-family/1-core/contract/test/test-support.ts Core module: 155 other modules depend on it, so it shapes much of the system.
3. packages/3-extensions/sql-orm-client/test/helpers.ts Core module: 108 other modules depend on it, so it shapes much of the system.
4. examples/prisma-8-demo/src/prisma/db.ts Core module: 81 other modules depend on it, so it shapes much of the system.
5. packages/3-extensions/sql-orm-client/src/types.ts Core module: 74 other modules depend on it, so it shapes much of the system.
6. packages/1-framework/2-authoring/contract/src/index.ts Key flow: Authentication, a high-risk path that enters at invoke index.ts (packages/1-framework/2-authoring/contract/src/index.ts).
7. packages/2-sql-family/4-lanes/sql-builder/src/index.ts Key flow: Mission execution, a high-risk path that enters at invoke index.ts (packages/2-sql-family/4-lanes/sql-builder/src/index.ts).
8. examples/bundle-size/scripts/bundle.ts Key flow: File changes / writes, a high-risk path that enters at invoke bundle.ts (examples/bundle-size/scripts/bundle.ts).
9. packages/1-framework/3-tooling/migration/src/ledger-origin.ts Key flow: Billing, a high-risk path that enters at invoke ledger-origin.ts (packages/1-framework/3-tooling/migration/src/ledger-origin.ts).
10. packages/1-framework/3-tooling/cli/src/utils/cli-errors.ts Change with care: 55 files depend on it at runtime.
11. packages/3-extensions/sql-orm-client/src/collection.ts Change with care: 34 files depend on it at runtime; oversized and doing too much.

System map

flowchart TD
  subgraph sys_boundary["prisma"]
    subgraph apps_boundary["Apps"]
      lsp_playground["lsp-playground"]
    end
    subgraph pkgs_boundary["Packages"]
      cli["cli"]
      sql_contract["sql-contract"]
      sql_contract_psl["sql-contract-psl"]
      sql_contract_ts["sql-contract-ts"]
      family_sql["family-sql"]
    end
    mongo_demo["mongo-demo"]
    prisma_8_demo["prisma-8-demo"]
    store_postgresql[("PostgreSQL")]
    store_mongodb[("MongoDB")]
    store_prisma[("Prisma")]
    collapsed_units["96 more units, no cross-unit imports: telemetry-backend, paradedb-demo, prisma-8-cloudflare-worker +93"]
  end
  cli -->|uses| sql_contract
  sql_contract_psl -->|uses| sql_contract
  sql_contract_psl -->|uses| family_sql
  sql_contract_ts -->|uses| sql_contract
  sql_contract_ts -->|uses| sql_contract_psl
  prisma_8_demo -->|reads / writes| store_postgresql
  mongo_demo -->|reads / writes| store_mongodb
  lsp_playground -->|reads / writes| store_prisma
  class lsp_playground frontend
  class mongo_demo frontend
  class prisma_8_demo frontend
  class cli library
  class sql_contract library
  class sql_contract_psl library
  class sql_contract_ts library
  class family_sql library
  class store_postgresql store
  class store_mongodb store
  class store_prisma store
  class collapsed_units muted
  %% collapsed (no cross-unit imports): telemetry-backend, paradedb-demo, prisma-8-cloudflare-worker, prisma-8-demo-sqlite, prisma-8-postgis-demo, prisma7-adoption, react-router-demo, retail-store, tsconfig, tsdown, extension-author-tools, publish-surface, contract, utils, config, errors, framework-components, operations, ts-render, contract-authoring, ids, psl-parser, psl-printer, cli-telemetry, config-loader, emitter, language-server, migration-tools, vite-plugin-contract-emit, mongo-codec, mongo-contract, mongo-value, mongo-contract-prisma6, mongo-contract-psl, mongo-contract-ts, mongo-emitter, mongo-schema-ir, mongo-query-ast, mongo-orm, mongo-query-builder, mongo-lowering, mongo-wire, mongo-runtime, family-mongo, sql-errors, sql-operations, sql-schema-ir, sql-contract-prisma7, sql-contract-emitter, sql-relational-core, sql-builder, sql-runtime, extension-arktype-json, middleware-cache, extension-paradedb, extension-pgvector, extension-postgis, sql-orm-client, extension-supabase, target-mongo, adapter-mongo, driver-mongo, mongo, target-mysql, adapter-mysql, driver-mysql, mysql, target-postgres, adapter-postgres, driver-postgres, postgres-codec-testkit, postgres, target-sqlite, adapter-sqlite, driver-sqlite, sqlite-codec-testkit, sqlite, orm-extension-arktype-json, orm-extension-middleware-cache, orm-extension-paradedb, orm-extension-pgvector, orm-extension-postgis, orm-extension-supabase, orm-family-mongo, orm-family-sql, orm-framework, orm-mongo, orm-mysql, orm-postgres, orm-sqlite, orm-target-mongo, orm-target-mysql, orm-target-postgres, orm-target-sqlite, orm-toolchain, MySQL
  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

Authentication high risk

Entry: invoke index.ts (packages/1-framework/2-authoring/contract/src/index.ts)

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 authoring-argument-types.ts
  participant F2 as capability-registry.ts
  participant F3 as composed-helpers-scaffolding.ts
  participant F4 as descriptors.ts
  participant F5 as enum-members.ts
  C0->>F0: invoke index.ts
  F0->>F1: calls
  F0->>F2: calls
  F0->>F3: calls
  F0->>F4: calls
  F0->>F5: calls

Mission execution high risk

Entry: invoke index.ts (packages/2-sql-family/4-lanes/sql-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 expression.ts
  participant F2 as resolve.ts
  participant F3 as scope.ts
  participant F4 as db.ts
  participant F5 as grouped-query.ts
  C0->>F0: invoke index.ts
  F0->>F1: calls
  F0->>F2: calls
  F0->>F3: calls
  F0->>F4: calls
  F0->>F5: calls

File changes / writes high risk

Entry: invoke bundle.ts (examples/bundle-size/scripts/bundle.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 bundle.ts
  participant Disk as disk
  C0->>F0: invoke bundle.ts
  F0->>Disk: writes files to the working tree

Billing high risk

Entry: invoke ledger-origin.ts (packages/1-framework/3-tooling/migration/src/ledger-origin.ts)

Billing touches money and the ledger; errors here are financially material and may be irreversible.

sequenceDiagram
  actor C0 as Caller
  participant F0 as src/ledger-origin.ts
  participant F1 as exports/ledger-origin.ts
  C0->>F0: invoke ledger-origin.ts

Background jobs medium risk

Entry: scheduled trigger (apps/telemetry-backend/src/handler.ts)

moves work onto a queue (queue)

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

sequenceDiagram
  actor C0 as Scheduler
  participant F0 as handler.ts
  participant Queue as queue
  C0->>F0: scheduled trigger
  F0->>Queue: moves work onto a queue

Fragile zones

• packages/1-framework/3-tooling/cli/src/utils/cli-errors.ts (score 116.8): 55 files depend on it at runtime
• examples/prisma-8-demo/src/prisma/db.ts (score 96.8): 26 files depend on it at runtime; types used by 44 modules
• packages/3-extensions/sql-orm-client/src/collection.ts (score 84): 34 files depend on it at runtime; oversized and doing too much
• packages/3-extensions/sql-orm-client/src/types.ts (score 72.8): 10 files depend on it at runtime; types used by 48 modules; oversized and doing too much
• packages/3-extensions/sql-orm-client/test/helpers.ts (score 72.3): 30 files depend on it at runtime; types used by 10 modules
• packages/3-targets/postgres/1-target/src/core/errors.ts (score 58): 29 files depend on it at runtime
• packages/1-framework/3-tooling/cli/src/orm/normalize-error.ts (score 54): 27 files depend on it at runtime
• packages/1-framework/2-authoring/psl-parser/src/syntax/ast/expressions.ts (score 48.3): 20 files depend on it at runtime
• packages/3-targets/postgres/1-target/src/core/codec-ids.ts (score 48): 24 files depend on it at runtime
• packages/1-framework/2-authoring/psl-parser/src/diagnostic.ts (score 46): 10 files depend on it at runtime; types used by 26 modules
• packages/3-extensions/sql-orm-client/src/orm-errors.ts (score 46): 23 files depend on it at runtime
• packages/3-targets/postgres/1-target/src/core/data-types.ts (score 46): 22 files depend on it at runtime

Architecture rules