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 91 shared packages. It stores data in PostgreSQL, 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: 52 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/1-core/contract/test/test-support.ts Core module: 149 other modules depend on it, so it shapes much of the system.
3. packages/3-extensions/sql-orm-client/test/helpers.ts Core module: 103 other modules depend on it, so it shapes much of the system.
4. packages/3-extensions/sql-orm-client/src/types.ts Core module: 70 other modules depend on it, so it shapes much of the system.
5. packages/3-targets/3-targets/postgres/src/core/postgres-schema.ts Core module: 67 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/4-lanes/sql-builder/src/index.ts Key flow: Mission execution, a high-risk path that enters at invoke index.ts (packages/2-sql/4-lanes/sql-builder/src/index.ts).
8. .claude/scripts/stop-quality-gate.mjs Key flow: File changes / writes, a high-risk path that enters at invoke stop-quality-gate.mjs (.claude/scripts/stop-quality-gate.mjs).
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: 52 files depend on it at runtime.
11. examples/prisma-8-demo/src/orm-client/client.ts Change with care: 49 files depend on it at runtime.
12. packages/3-extensions/sql-orm-client/src/collection.ts Change with care: 33 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"]
      sql_relational_core["sql-relational-core"]
    end
    mongo_demo["mongo-demo"]
    prisma_8_demo["prisma-8-demo"]
    store_postgresql[("PostgreSQL")]
    store_mongodb[("MongoDB")]
    store_prisma[("Prisma")]
    collapsed_units["89 more units, no cross-unit imports: telemetry-backend, paradedb-demo, prisma-8-cloudflare-worker +86"]
  end
  cli -->|uses| sql_contract
  sql_contract_psl -->|uses| sql_contract
  sql_contract_ts -->|uses| sql_contract
  sql_relational_core -->|uses| sql_contract
  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 sql_relational_core 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-builder, sql-runtime, family-sql, extension-arktype-json, middleware-cache, mongo, extension-paradedb, extension-pgvector, extension-postgis, postgres, sql-orm-client, sqlite, extension-supabase, target-mongo, adapter-mongo, driver-mongo, target-postgres, target-sqlite, adapter-postgres, postgres-codec-testkit, adapter-sqlite, sqlite-codec-testkit, driver-postgres, driver-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-postgres, orm-sqlite, orm-target-mongo, orm-target-postgres, orm-target-sqlite, orm-toolchain
  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/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 stop-quality-gate.mjs (.claude/scripts/stop-quality-gate.mjs)

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 stop-quality-gate.mjs
  participant F1 as worktree-create.mjs
  participant F2 as bundle.ts
  participant Disk as disk
  C0->>F0: invoke stop-quality-gate.mjs
  F0->>Disk: writes files to the working tree
  F1->>Disk: writes files to the working tree
  F2->>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 107.8): 52 files depend on it at runtime
• examples/prisma-8-demo/src/orm-client/client.ts (score 98.5): 49 files depend on it at runtime
• packages/3-extensions/sql-orm-client/src/collection.ts (score 82.3): 33 files depend on it at runtime; oversized and doing too much
• packages/3-extensions/sql-orm-client/test/helpers.ts (score 70.3): 29 files depend on it at runtime; types used by 10 modules
• packages/3-extensions/sql-orm-client/src/types.ts (score 68.8): 10 files depend on it at runtime; types used by 44 modules; oversized and doing too much
• packages/1-framework/3-tooling/cli/src/orm/normalize-error.ts (score 54): 27 files depend on it at runtime
• packages/3-targets/3-targets/postgres/src/core/errors.ts (score 52): 26 files depend on it at runtime
• examples/prisma-8-demo/src/prisma/db.ts (score 48.5): 24 files depend on it at runtime
• packages/3-targets/3-targets/postgres/src/core/data-types.ts (score 46.8): 23 files depend on it at runtime
• packages/3-targets/3-targets/postgres/src/core/codec-ids.ts (score 46): 23 files depend on it at runtime
• packages/1-framework/3-tooling/cli/src/orm/define-command.ts (score 44.3): 22 files depend on it at runtime
• examples/retail-store/src/db.ts (score 44): 18 files depend on it at runtime; types used by 8 modules

Architecture rules