nest: Architecture

Architecture health: 30/100 (F)

Overview

nest is a TypeScript npm project, built with Vite, Fastify, Express, and NestJS. It runs as a frontend (core) and 43 backend services (cats-app, gateways, microservices, grpc, sql-typeorm, mongoose, sequelize, webpack, babel-example, fastify, swagger, graphql-schema-first, mongo-typeorm, mongoose-base, mvc, gateways-ws, mvc-fastify, context, auth-jwt, cache, serializer, graphql-prisma, graphql-code-first, serve-static, dynamic-modules, queues, scheduling, sse, file-upload, event-emitter, graphql-federation-code-first-gateway, graphql-federation-code-first-posts-application, graphql-federation-code-first-users-application, graphql-federation-schema-first-gateway, graphql-federation-schema-first-posts-application, graphql-federation-schema-first-users-application, graphql-mercurius, hmr-esm, zod-validation, valibot-serializer, outbox, webhooks, file-storage), backed by 9 shared packages. It stores data in SQLite, PostgreSQL, MySQL, MongoDB, Prisma, Drizzle, TypeORM, Sequelize, and Redis and uses Bull, RabbitMQ, Kafka, and NATS for messaging. The main structural risks to watch: 15 oversized "god" files and 16 circular import chains. The file with the widest blast radius is packages/common/decorators/core/injectable.decorator.ts: 235 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. sample/01-cats-app/src/main.ts Start here: how the system boots and wires its subsystems together.
2. packages/common/decorators/core/injectable.decorator.ts Core module: 296 other modules depend on it, so it shapes much of the system.
3. packages/common/decorators/modules/module.decorator.ts Core module: 270 other modules depend on it, so it shapes much of the system.
4. packages/testing/test.ts Core module: 262 other modules depend on it, so it shapes much of the system.
5. packages/common/decorators/core/controller.decorator.ts Core module: 184 other modules depend on it, so it shapes much of the system.
6. sample/19-auth-jwt/src/main.ts Key flow: Authentication, a high-risk path that enters at invoke main.ts (sample/19-auth-jwt/src/main.ts).
7. packages/testing/testing-module.builder.ts Key flow: Mission execution, a high-risk path that enters at invoke testing-module.builder.ts (packages/testing/testing-module.builder.ts).
8. sample/31-graphql-federation-code-first/gateway/generate-supergraph.ts Key flow: File changes / writes, a high-risk path that enters at invoke generate-supergraph.ts (sample/31-graphql-federation-code-first/gateway/generate-supergraph.ts).
9. sample/39-file-storage/src/invoices/invoices.service.ts Key flow: Billing, a high-risk path that enters at invoke invoices.service.ts (sample/39-file-storage/src/invoices/invoices.service.ts).
10. packages/common/utils/shared.utils.ts Change with care: 134 files depend on it at runtime.

System map

flowchart TD
  subgraph sys_boundary["nest"]
    core["core"]
    common["common"]
    core_2["core"]
    microservices["microservices"]
    platform_express["platform-express"]
    platform_fastify["platform-fastify"]
    platform_ws["platform-ws"]
    testing["testing"]
    websockets["websockets"]
    cats_app(["cats-app"])
    sql_typeorm(["sql-typeorm"])
    sequelize(["sequelize"])
    graphql_prisma(["graphql-prisma"])
    outbox(["outbox"])
    store_sqlite[("SQLite")]
    store_postgresql[("PostgreSQL")]
    store_mysql[("MySQL")]
    store_mongodb[("MongoDB")]
    store_prisma[("Prisma")]
    store_drizzle[("Drizzle")]
    store_typeorm[("TypeORM")]
    store_sequelize[("Sequelize")]
    store_redis[("Redis")]
    queue_bull>"Bull"]
    queue_rabbitmq>"RabbitMQ"]
    queue_kafka>"Kafka"]
    queue_nats>"NATS"]
    collapsed_units["39 more units, no cross-unit imports: platform-socket.io, gateways, microservices +36"]
  end
  core -->|uses| common
  core -->|uses| testing
  core -->|uses| platform_express
  core -->|uses| platform_fastify
  core -->|uses| core_2
  core -->|uses| platform_ws
  core -->|uses| websockets
  core -->|uses| microservices
  core_2 -->|uses| common
  core_2 -->|uses| platform_express
  core_2 -->|uses| microservices
  core_2 -->|uses| websockets
  core_2 -->|uses| testing
  microservices -->|uses| common
  microservices -->|uses| core_2
  microservices -->|uses| websockets
  sql_typeorm -->|reads / writes| store_sqlite
  outbox -->|reads / writes| store_postgresql
  core -->|reads / writes| store_mysql
  core -->|reads / writes| store_mongodb
  graphql_prisma -->|reads / writes| store_prisma
  outbox -->|reads / writes| store_drizzle
  core -->|reads / writes| store_typeorm
  sequelize -->|reads / writes| store_sequelize
  core -->|reads / writes| store_redis
  cats_app -->|enqueues| queue_bull
  cats_app -->|enqueues| queue_rabbitmq
  cats_app -->|enqueues| queue_kafka
  cats_app -->|enqueues| queue_nats
  class core frontend
  class common library
  class core_2 library
  class microservices library
  class platform_express library
  class platform_fastify library
  class platform_ws library
  class testing library
  class websockets library
  class cats_app service
  class sql_typeorm service
  class sequelize service
  class graphql_prisma service
  class outbox service
  class store_sqlite store
  class store_postgresql store
  class store_mysql store
  class store_mongodb store
  class store_prisma store
  class store_drizzle store
  class store_typeorm store
  class store_sequelize store
  class store_redis store
  class queue_bull queue
  class queue_rabbitmq queue
  class queue_kafka queue
  class queue_nats queue
  class collapsed_units muted
  %% collapsed (no cross-unit imports): platform-socket.io, gateways, microservices, grpc, mongoose, webpack, babel-example, fastify, swagger, graphql-schema-first, mongo-typeorm, mongoose-base, mvc, gateways-ws, mvc-fastify, context, auth-jwt, cache, serializer, graphql-code-first, serve-static, dynamic-modules, queues, scheduling, sse, file-upload, event-emitter, graphql-federation-code-first-gateway, graphql-federation-code-first-posts-application, graphql-federation-code-first-users-application, graphql-federation-schema-first-gateway, graphql-federation-schema-first-posts-application, graphql-federation-schema-first-users-application, graphql-mercurius, hmr-esm, zod-validation, valibot-serializer, webhooks, file-storage
  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 (sample/01-cats-app/src/main.ts)

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

sequenceDiagram
  actor C0 as Process
  participant F0 as main.ts
  participant F1 as common/index.ts
  participant F2 as core/index.ts
  participant F3 as app.module.ts
  C0->>F0: process start
  F0->>F1: calls
  F0->>F2: calls
  F0->>F3: calls

Authentication high risk

Entry: invoke main.ts (sample/19-auth-jwt/src/main.ts)

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

sequenceDiagram
  actor C0 as Caller
  participant F0 as main.ts
  participant F1 as app.module.ts
  participant F2 as auth.module.ts
  participant F3 as users.module.ts
  participant F4 as auth.controller.ts
  participant F5 as auth.guard.ts
  C0->>F0: invoke main.ts
  F0->>F1: calls
  F1->>F2: calls
  F1->>F3: calls
  F2->>F4: calls
  F2->>F5: calls

Mission execution high risk

Entry: invoke testing-module.builder.ts (packages/testing/testing-module.builder.ts)

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

sequenceDiagram
  actor C0 as Caller
  participant F0 as testing-module.builder.ts
  C0->>F0: invoke testing-module.builder.ts

File changes / writes high risk

Entry: invoke generate-supergraph.ts (sample/31-graphql-federation-code-first/gateway/generate-supergraph.ts)

writes files to the working tree (disk); calls an external service (external API)

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 generate-supergraph.ts
  participant Disk as disk
  participant External as external API
  C0->>F0: invoke generate-supergraph.ts
  F0->>Disk: writes files to the working tree
  F0->>External: calls an external service

Billing high risk

Entry: invoke invoices.service.ts (sample/39-file-storage/src/invoices/invoices.service.ts)

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

sequenceDiagram
  actor C0 as Caller
  participant F0 as invoices.service.ts
  participant F1 as render-invoice.ts
  C0->>F0: invoke invoices.service.ts
  F0->>F1: calls

Background jobs medium risk

Entry: scheduled trigger (sample/27-scheduling/src/app.module.ts)

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

sequenceDiagram
  actor C0 as Scheduler
  participant F0 as app.module.ts
  participant F1 as app.e2e-spec.ts
  participant F2 as tasks.service.ts
  C0->>F0: scheduled trigger

Fragile zones

• packages/common/decorators/core/injectable.decorator.ts (score 470.3): 235 files depend on it at runtime
• packages/common/decorators/modules/module.decorator.ts (score 432.3): 216 files depend on it at runtime
• packages/common/utils/shared.utils.ts (score 268): 134 files depend on it at runtime
• packages/common/decorators/core/controller.decorator.ts (score 262.5): 131 files depend on it at runtime
• packages/common/decorators/http/request-mapping.decorator.ts (score 244.5): 122 files depend on it at runtime
• packages/common/decorators/http/route-params.decorator.ts (score 158): 72 files depend on it at runtime; types used by 9 modules; oversized and doing too much
• packages/common/interfaces/scope-options.interface.ts (score 154): 75 files depend on it at runtime
• packages/common/services/logger.service.ts (score 150.5): 71 files depend on it at runtime; part of an import cycle
• packages/common/decorators/core/inject.decorator.ts (score 146.5): 73 files depend on it at runtime
• packages/core/nest-factory.ts (score 126.5): 59 files depend on it at runtime; oversized and doing too much
• packages/common/enums/http-status.enum.ts (score 104): 52 files depend on it at runtime
• packages/common/interfaces/type.interface.ts (score 104): 1 file depends on it at runtime; type contract for 102 modules

Architecture rules