nest: Architecture

Architecture health: 30/100 (F)

Overview

nest is a TypeScript npm project, built with Fastify, Express, and NestJS. It runs as 41 backend services (core, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-babel-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, auth-sample, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, nest-typescript-starter, gateway, posts-application, users-application, gateway, posts-application, users-application, nest-typescript-starter, 34-using-esm-packages, 35-using-esm-package-after-node22, nest-typescript-starter), backed by 9 shared packages. It stores data in MySQL, MongoDB, Prisma, TypeORM, Sequelize, and Redis and uses Bull, RabbitMQ, Kafka, and NATS for messaging. The main structural risks to watch: 15 oversized "god" files and 14 circular import chains. The file with the widest blast radius is packages/common/decorators/core/injectable.decorator.ts: 207 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/common/decorators/core/injectable.decorator.ts Core module: 242 other modules depend on it, so it shapes much of the system.
2. packages/common/decorators/modules/module.decorator.ts Core module: 215 other modules depend on it, so it shapes much of the system.
3. packages/testing/test.ts Core module: 170 other modules depend on it, so it shapes much of the system.
4. packages/common/decorators/core/controller.decorator.ts Core module: 128 other modules depend on it, so it shapes much of the system.
5. 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).
6. 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).
7. packages/common/decorators/core/apply-decorators.ts Key flow: File changes / writes, a high-risk path that enters at invoke apply-decorators.ts (packages/common/decorators/core/apply-decorators.ts).
8. sample/27-scheduling/src/app.module.ts Key flow: Background jobs, a medium-risk path that enters at scheduled trigger (sample/27-scheduling/src/app.module.ts).
9. packages/common/utils/shared.utils.ts Change with care: 120 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_socket_io["platform-socket.io"]
    platform_ws["platform-ws"]
    testing["testing"]
    websockets["websockets"]
    nest_typescript_starter(["nest-typescript-starter"])
    nest_typescript_starter_2(["nest-typescript-starter"])
    nest_typescript_starter_3(["nest-typescript-starter"])
    nest_typescript_starter_4(["nest-typescript-starter"])
    nest_typescript_starter_5(["nest-typescript-starter"])
    nest_typescript_starter_6(["nest-typescript-starter"])
    nest_typescript_starter_7(["nest-typescript-starter"])
    nest_typescript_starter_8(["nest-typescript-starter"])
    nest_babel_starter(["nest-babel-starter"])
    nest_typescript_starter_9(["nest-typescript-starter"])
    nest_typescript_starter_10(["nest-typescript-starter"])
    nest_typescript_starter_11(["nest-typescript-starter"])
    nest_typescript_starter_12(["nest-typescript-starter"])
    nest_typescript_starter_13(["nest-typescript-starter"])
    nest_typescript_starter_14(["nest-typescript-starter"])
    nest_typescript_starter_15(["nest-typescript-starter"])
    nest_typescript_starter_16(["nest-typescript-starter"])
    nest_typescript_starter_17(["nest-typescript-starter"])
    auth_sample(["auth-sample"])
    nest_typescript_starter_18(["nest-typescript-starter"])
    nest_typescript_starter_19(["nest-typescript-starter"])
    nest_typescript_starter_20(["nest-typescript-starter"])
    nest_typescript_starter_21(["nest-typescript-starter"])
    nest_typescript_starter_22(["nest-typescript-starter"])
    nest_typescript_starter_23(["nest-typescript-starter"])
    nest_typescript_starter_24(["nest-typescript-starter"])
    nest_typescript_starter_25(["nest-typescript-starter"])
    nest_typescript_starter_26(["nest-typescript-starter"])
    nest_typescript_starter_27(["nest-typescript-starter"])
    store_mysql[("MySQL")]
    store_mongodb[("MongoDB")]
    store_prisma[("Prisma")]
    store_typeorm[("TypeORM")]
    store_sequelize[("Sequelize")]
    store_redis[("Redis")]
    queue_bull>"Bull"]
    queue_rabbitmq>"RabbitMQ"]
    queue_kafka>"Kafka"]
    queue_nats>"NATS"]
    collapsed_units["11 more units, no cross-unit imports: nest-typescript-starter, gateway, posts-application +8"]
  end
  core -->|uses| common
  core -->|uses| testing
  core -->|uses| platform_express
  core -->|uses| platform_fastify
  core -->|uses| core_2
  core -->|uses| microservices
  core -->|uses| websockets
  core -->|uses| platform_ws
  core_2 -->|uses| common
  core_2 -->|uses| websockets
  core_2 -->|uses| microservices
  core_2 -->|uses| platform_express
  core_2 -->|uses| testing
  microservices -->|uses| common
  microservices -->|uses| core_2
  microservices -->|uses| websockets
  platform_express -->|uses| common
  platform_express -->|uses| core_2
  platform_fastify -->|uses| common
  platform_fastify -->|uses| core_2
  platform_socket_io -->|uses| common
  platform_socket_io -->|uses| websockets
  platform_ws -->|uses| common
  platform_ws -->|uses| websockets
  testing -->|uses| common
  testing -->|uses| core_2
  testing -->|uses| microservices
  testing -->|uses| platform_express
  websockets -->|uses| common
  websockets -->|uses| core_2
  websockets -->|uses| platform_socket_io
  nest_typescript_starter -->|uses| common
  nest_typescript_starter -->|uses| testing
  nest_typescript_starter -->|uses| core_2
  nest_typescript_starter_2 -->|uses| common
  nest_typescript_starter_2 -->|uses| testing
  nest_typescript_starter_2 -->|uses| platform_socket_io
  nest_typescript_starter_2 -->|uses| websockets
  nest_typescript_starter_2 -->|uses| core_2
  nest_typescript_starter_3 -->|uses| common
  nest_typescript_starter_3 -->|uses| microservices
  nest_typescript_starter_3 -->|uses| core_2
  nest_typescript_starter_4 -->|uses| common
  nest_typescript_starter_4 -->|uses| microservices
  nest_typescript_starter_4 -->|uses| core_2
  nest_typescript_starter_5 -->|uses| common
  nest_typescript_starter_5 -->|uses| core_2
  nest_typescript_starter_5 -->|uses| testing
  nest_typescript_starter_6 -->|uses| common
  nest_typescript_starter_6 -->|uses| testing
  nest_typescript_starter_6 -->|uses| core_2
  nest_typescript_starter_7 -->|uses| common
  nest_typescript_starter_7 -->|uses| core_2
  nest_typescript_starter_7 -->|uses| testing
  nest_typescript_starter_8 -->|uses| common
  nest_typescript_starter_8 -->|uses| core_2
  nest_babel_starter -->|uses| common
  nest_babel_starter -->|uses| core_2
  nest_typescript_starter_9 -->|uses| common
  nest_typescript_starter_9 -->|uses| core_2
  nest_typescript_starter_9 -->|uses| platform_fastify
  nest_typescript_starter_10 -->|uses| common
  nest_typescript_starter_10 -->|uses| core_2
  nest_typescript_starter_11 -->|uses| common
  nest_typescript_starter_11 -->|uses| testing
  nest_typescript_starter_11 -->|uses| core_2
  nest_typescript_starter_12 -->|uses| common
  nest_typescript_starter_12 -->|uses| core_2
  nest_typescript_starter_12 -->|uses| testing
  nest_typescript_starter_13 -->|uses| common
  nest_typescript_starter_13 -->|uses| testing
  nest_typescript_starter_13 -->|uses| core_2
  nest_typescript_starter_14 -->|uses| common
  nest_typescript_starter_14 -->|uses| core_2
  nest_typescript_starter_14 -.->|types only| platform_express
  nest_typescript_starter_15 -->|uses| common
  nest_typescript_starter_15 -->|uses| websockets
  nest_typescript_starter_15 -->|uses| core_2
  nest_typescript_starter_15 -->|uses| platform_ws
  nest_typescript_starter_16 -->|uses| common
  nest_typescript_starter_16 -->|uses| core_2
  nest_typescript_starter_16 -->|uses| platform_fastify
  nest_typescript_starter_17 -->|uses| common
  nest_typescript_starter_17 -->|uses| core_2
  auth_sample -->|uses| common
  auth_sample -->|uses| testing
  auth_sample -->|uses| core_2
  nest_typescript_starter_18 -->|uses| common
  nest_typescript_starter_18 -->|uses| core_2
  nest_typescript_starter_19 -->|uses| common
  nest_typescript_starter_19 -->|uses| core_2
  nest_typescript_starter_20 -->|uses| common
  nest_typescript_starter_20 -->|uses| core_2
  nest_typescript_starter_21 -->|uses| common
  nest_typescript_starter_21 -->|uses| core_2
  nest_typescript_starter_22 -->|uses| common
  nest_typescript_starter_22 -->|uses| core_2
  nest_typescript_starter_23 -->|uses| testing
  nest_typescript_starter_23 -->|uses| common
  nest_typescript_starter_23 -->|uses| core_2
  nest_typescript_starter_24 -->|uses| testing
  nest_typescript_starter_24 -->|uses| common
  nest_typescript_starter_24 -->|uses| core_2
  nest_typescript_starter_25 -->|uses| common
  nest_typescript_starter_25 -->|uses| core_2
  nest_typescript_starter_26 -->|uses| common
  nest_typescript_starter_26 -->|uses| core_2
  nest_typescript_starter_27 -->|uses| common
  nest_typescript_starter_27 -->|uses| testing
  core -->|reads / writes| store_mysql
  core -->|reads / writes| store_mongodb
  nest_typescript_starter_20 -->|reads / writes| store_prisma
  core -->|reads / writes| store_typeorm
  nest_typescript_starter_7 -->|reads / writes| store_sequelize
  core -->|reads / writes| store_redis
  core -->|enqueues| queue_bull
  core -->|enqueues| queue_rabbitmq
  core -->|enqueues| queue_kafka
  core -->|enqueues| queue_nats
  class core service
  class common library
  class core_2 library
  class microservices library
  class platform_express library
  class platform_fastify library
  class platform_socket_io library
  class platform_ws library
  class testing library
  class websockets library
  class nest_typescript_starter service
  class nest_typescript_starter_2 service
  class nest_typescript_starter_3 service
  class nest_typescript_starter_4 service
  class nest_typescript_starter_5 service
  class nest_typescript_starter_6 service
  class nest_typescript_starter_7 service
  class nest_typescript_starter_8 service
  class nest_babel_starter service
  class nest_typescript_starter_9 service
  class nest_typescript_starter_10 service
  class nest_typescript_starter_11 service
  class nest_typescript_starter_12 service
  class nest_typescript_starter_13 service
  class nest_typescript_starter_14 service
  class nest_typescript_starter_15 service
  class nest_typescript_starter_16 service
  class nest_typescript_starter_17 service
  class auth_sample service
  class nest_typescript_starter_18 service
  class nest_typescript_starter_19 service
  class nest_typescript_starter_20 service
  class nest_typescript_starter_21 service
  class nest_typescript_starter_22 service
  class nest_typescript_starter_23 service
  class nest_typescript_starter_24 service
  class nest_typescript_starter_25 service
  class nest_typescript_starter_26 service
  class nest_typescript_starter_27 service
  class store_mysql store
  class store_mongodb store
  class store_prisma 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): nest-typescript-starter, gateway, posts-application, users-application, gateway, posts-application, users-application, nest-typescript-starter, 34-using-esm-packages, 35-using-esm-package-after-node22, nest-typescript-starter
  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 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 apply-decorators.ts (packages/common/decorators/core/apply-decorators.ts)

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 apply-decorators.ts
  C0->>F0: invoke apply-decorators.ts

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 tasks.service.ts
  C0->>F0: scheduled trigger

Fragile zones

• packages/common/decorators/core/injectable.decorator.ts (score 414.3): 207 files depend on it at runtime
• packages/common/decorators/modules/module.decorator.ts (score 368.3): 184 files depend on it at runtime
• packages/common/utils/shared.utils.ts (score 240): 120 files depend on it at runtime
• packages/common/decorators/core/controller.decorator.ts (score 202.5): 101 files depend on it at runtime
• packages/common/decorators/http/request-mapping.decorator.ts (score 190.5): 95 files depend on it at runtime
• packages/common/interfaces/scope-options.interface.ts (score 148): 73 files depend on it at runtime
• packages/common/decorators/core/inject.decorator.ts (score 132.5): 66 files depend on it at runtime
• packages/common/services/logger.service.ts (score 117.3): 56 files depend on it at runtime
• packages/core/nest-factory.ts (score 114.8): 53 files depend on it at runtime; oversized and doing too much
• packages/common/decorators/http/route-params.decorator.ts (score 109.8): 50 files depend on it at runtime; oversized and doing too much
• packages/common/constants.ts (score 101): 48 files depend on it at runtime
• packages/common/interfaces/type.interface.ts (score 95): 1 file depends on it at runtime; type contract for 93 modules

Architecture rules