DEV Community: Victor Shkirov

Feature Based Clean Architecture. Part 5: Scaling FBCA and a Graph-Theoretic Analysis of Dependencies

Victor Shkirov — Sun, 10 May 2026 19:29:00 +0000

An architectural doctrine for NestJS projects: a breakdown of typical codebase degradation scenarios and the structural constraints that keep them from emerging as the feature set grows.

In parts 1–2 we watched a simple signUp turn, under the pressure of requirements, into a god-service of hundreds of lines that knew about a dozen modules at once. In part 3 we worked through how forwardRef and circular dependencies are born from this naturally — that very tangle that can no longer be untangled. In part 4 we designed an FBCA architecture from scratch — domain / use-case / infrastructure / presentation with layers, external ports, and Result-based error handling — and showed how the same signUp looks inside it.

Part 5 is a parallel universe of the same plot. The same business requirements that hit feature-based in parts 1–2 now hit the FBCA codebase from part 4: the sign-up handler grows the same external services (anti-fraud, referrals, partners, analytics), and the Users module grows the same features (profile, settings, privacy, stats). Let's see what changes in form, what changes in content, and why the dependency graph stays acyclic even after a multi-fold growth. At the end — a formal justification in the language of graph theory: why the DAG invariant, the coupling bound, and the constant cost of an increment aren't a property of the architecture in the sense of "convenient," but its mathematical content.

Remember the set of requirements from part 2 — the one under whose weight AuthService.signUp turned into an eight-hundred-line god service, surrounded by six neighboring services and a single backward forwardRef? The same list now arrives at the FBCA codebase:

a partner program with bloggers and streamers
different monetization models (revenue share, bonuses, tiers)
a more complex anti-fraud (multiple scenarios and scoring)
extended analytics (marketing, product, finance)
additional checks and limits for referrals

The business logic has to remain the same — otherwise the comparison isn't fair. But the form of the code and of the dependency graph — let's see how those change. The note on transactions from part 1 continues to apply here and onward — we're examining decomposition, not transactional integrity.

export type SignUpInput = {
  email: string;
  password: string;
  referralCode?: string;
  adSourceCode?: string;
  ip?: string;
  deviceId?: string;
};

@Injectable()
export class SignUpHandler {
  constructor(
    private readonly bonusExternalService: BonusExternalService,
    private readonly usersExternalService: UsersExternalService,
    private readonly partnerExternalService: PartnerExternalService,
    private readonly adSourceExternalService: AdSourceExternalService,
    private readonly referralExternalService: ReferralExternalService,
    private readonly analyticsExternalService: AnalyticsExternalService,
    private readonly antiFraudExternalService: AntiFraudExternalService,
  ) {}

  async run(
    input: SignUpInput,
  ): Promise<Result<SignUpResult, SignUpErrorCode>> {
    const { email, password, referralCode, adSourceCode, ip, deviceId } = input;

    // anti-fraud
    const checkAntiFraudResult =
      await this.antiFraudExternalService.checkSignUp({ ip, deviceId });

    if (checkAntiFraudResult.isErr()) {
      return err("SIGN_UP_ANTI_FRAUD_FAILED");
    }

    if (!checkAntiFraudResult.value.allowed) {
      return err("SIGN_UP_ANTI_FRAUD_REJECTED");
    }

    // make sure the user isn't already registered — before any side effects
    const findUserResult =
      await this.usersExternalService.getUserByEmail(email);

    if (findUserResult.isErr()) {
      return err("SIGN_UP_GET_USER_FAILED");
    }

    if (findUserResult.value) {
      return err("SIGN_UP_USER_ALREADY_EXISTS");
    }

    // traffic source / A/B
    const applyAdSourceResult =
      await this.adSourceExternalService.applyAdSource(adSourceCode);

    if (applyAdSourceResult.isErr()) {
      return err("SIGN_UP_AD_SOURCE_FAILED");
    }

    // referral / partner (the module decides what kind of code this is)
    const resolveReferralResult = await this.referralExternalService.resolve(
      referralCode,
      email,
    );

    if (resolveReferralResult.isErr()) {
      return err("SIGN_UP_REFERRAL_RESOLVE_FAILED");
    }

    const createUserResult = await this.usersExternalService.createUser({
      email,
      password,
      adSource: applyAdSourceResult.value,
      ip,
      deviceId,
    });

    if (createUserResult.isErr()) {
      return err("SIGN_UP_CREATE_USER_FAILED");
    }

    const referral = resolveReferralResult.value;
    const user = createUserResult.value;

    // bonuses
    if (referral?.kind === "user") {
      const giveReferralBonusResult =
        await this.bonusExternalService.giveReferralBonus(referral.ownerId);

      if (giveReferralBonusResult.isErr()) {
        return err("SIGN_UP_BONUS_FAILED");
      }

      const createReferralResult =
        await this.referralExternalService.createReferral(
          referral.ownerId,
          user.id,
        );

      if (createReferralResult.isErr()) {
        return err("SIGN_UP_REFERRAL_CREATE_FAILED");
      }
    }

    if (referral?.kind === "partner") {
      const processPartnerResult =
        await this.partnerExternalService.processPartner(referral);

      if (processPartnerResult.isErr()) {
        return err("SIGN_UP_PARTNER_FAILED");
      }

      const givePartnerRewardResult =
        await this.bonusExternalService.givePartnerReward(
          processPartnerResult.value,
        );

      if (givePartnerRewardResult.isErr()) {
        return err("SIGN_UP_PARTNER_REWARD_FAILED");
      }

      const trackPartnerRewardResult =
        await this.analyticsExternalService.trackPartnerReward(
          processPartnerResult.value,
        );

      if (trackPartnerRewardResult.isErr()) {
        return err("SIGN_UP_ANALYTICS_FAILED");
      }
    }

    // final analytics
    const trackRegistrationResult =
      await this.analyticsExternalService.trackRegistration({
        userId: user.id,
        source: applyAdSourceResult.value?.code,
        ip,
      });

    if (trackRegistrationResult.isErr()) {
      return err("SIGN_UP_ANALYTICS_FAILED");
    }

    return ok({ id: user.id, email: user.email });
  }
}

As you can observe, the logic, the queries, and the algorithms have remained exactly the same. At which point the reader naturally has these questions:

Why did we even introduce feature-based-clean if the business logic is identical to the FB version?
There's more code now, not less. Where's the promised readability?
What do I, as a developer, gain right now if the result is the same steps, just with more folders and abstractions?

These questions look like a refutation of the whole idea. In reality they highlight what we already fixed at the close of part 4: FBCA isn't about today's code, it's about the code two or three sprints from now. If you compare only the current snapshot, FB and FBCA look about the same — the difference is that one of them has points where you can stop, and the other doesn't. That difference isn't visible until architectural load shows up. And that's exactly what we'll now see in action.

Let's look at how the Users module developed over time under the rules of feature-based-clean. While the sign-up handler was growing external services, the Users module itself was developing too — the frontend asked for the profile, marketing for stats, analytics for counters. By the current moment, Users is no longer that small module with two use-cases that we designed in part 4. Now it's a full-fledged domain:

fetching the user profile
updating the profile (bio, avatar, username)
updating account settings
account privacy (public / private)
fetching basic stats (followers, follows)
managing user preferences (language, theme, etc.)
fetching the current user (me endpoint)

src/modules/users/
├── domain/                           # User, UserProfile, UserSettings, UserPrivacy, ...
│
├── use-case/
│   ├── presentation/                 # Scenarios for UsersController
│   │   ├── get-profile/
│   │   ├── update-profile/
│   │   ├── update-account-settings/
│   │   ├── update-privacy/
│   │   ├── update-preferences/
│   │   ├── get-user-stats/
│   │   └── get-current-user/
│   │
│   └── external/                     # Scenarios for other modules (via the external port)
│       ├── create-user/              # ← Auth
│       ├── get-user-by-email/        # ← Auth
│       ├── check-user-exists/        # ← Likes, Comments, Follows
│       ├── get-following-ids/        # ← Feed
│       ├── can-view-content/         # ← Feed
│       ├── can-receive-notification/ # ← Notifications
│       ├── get-public-user-info/     # ← Comments, Likes
│       ├── is-searchable/            # ← Search
│       ├── is-user-blocked/          # ← Moderation, AntiFraud
│       └── get-user-status/          # ← various modules
│
├── infrastructure/
│   └── repositories/
│       ├── user/
│       ├── user-profile/
│       ├── user-settings/
│       ├── user-privacy/
│       ├── user-preferences/
│       ├── user-stats/
│       └── user-session/
│
├── external/                         # The port for other modules (Auth, Feed, Comments, Search, ...)
│
└── presentation/                     # UsersController + DTO

As we can see, the need for a big "split by responsibility" refactoring has gone away. In feature-based, when UsersService reaches critical mass — say, eight hundred lines and fifteen methods across different user subsystems — the time comes for a major rewrite. Break it apart into UserProfileService, UserSettingsService, UserPrivacyService. That's serious work: rewrite the calls, untangle the cycles, update the tests, reassemble the modules. A month, a month and a half at minimum — and during all of that the system has to keep running in production.

In FBCA, that point simply doesn't exist. When the PM comes in with "we need privacy settings" — that's use-case/presentation/update-privacy/ next to the already-existing update-profile/ and update-account-settings/. When the DBA says "it would be nice to move user_sessions into a separate table" — that's infrastructure/repositories/user-session/ next to user/ and user-profile/. Each new artifact lands next to the old ones, shifting nothing. There are more folders, but this isn't sprawl — it's horizontal growth that reads the same way five files used to read.

And when the count of use-cases reaches twenty or thirty and your eyes start scattering across one directory, "splitting by responsibility" reduces to one mechanical operation: lay out the ready-made Lego pieces into thematic folders. update-profile/, update-bio/, update-avatar/ move into use-case/presentation/profile/. update-privacy/, update-account-settings/ — into use-case/presentation/security/. No dependencies to untangle, no cycles, no Nest DI reconfiguration. The PR may turn out fat — but only because import paths are changing; you don't edit a single line of logic in the process.

Let's now look at the dependency graph that emerged as a result of FBCA.

Now let's look at the FB graph before cycles start there.

FB is obviously losing here: many neighboring services have started pulling code out of UsersService, and it seems that if you remove this dependency, everything will be fine.

That's self-deception. The arrows aren't lazy development — they're a reflection of the business: the referral program really does need to know who invited whom; anti-fraud needs to see the account history; analytics needs to enrich events with profile data. You can't remove the dependencies — the modules will stop working.

The same needs exist in FBCA — there are just as many arrows above, but they point at UsersExternalService. The difference is that each such arrow isn't a "universal key to all of Users," but a concrete authorization: one neighbor is allowed to call only getUserByEmail, another — only isUserBlocked. In FB, anyone with UsersService in their DI graph has access to the full hub API and may, tomorrow, call from there a method no one ever agreed on. In FBCA, that's an obvious contract violation: what isn't in external/ doesn't exist for the neighbor.

Even if you remove the internal services' dependency on UsersService, set up separate repositories for each entity, and instill the discipline of "service doesn't call service" — that won't save you for long.

The point is that a service as a unit of code organization is built in a way that it can't help but expand. One class — many methods. Today UserProfileService.updateBio() and updateAvatar(). Tomorrow also getProfileMetadata(), recalculateCompletenessScore(), markAsViewed(). A sprint later it has twenty public methods, and any importer gets access to all of them at once. The problem isn't that Profile depends on Users — the problem is that depending on a class automatically grants access to the whole class.

That's where the use-case in the FBCA sense comes in — and it is not a "business scenario" in the usual sense of the word. A use-case here is a structural unit: one folder, one handler, one operation. update-profile/ isn't "all the work on the profile," it's specifically "update bio/avatar/username." To add "fetch profile metadata," you need a new folder get-profile-metadata/ next to it, not a new method in the existing handler. The form itself doesn't allow operations to accumulate at one point.

That's what removes the problem. When an importer needs one operation, they import exactly that — not the whole service. When a new operation appears, it sits next to the others without shifting them. The dependency graph stops being pulled toward hubs, because there's nowhere for the hubs to pull to: every node is an atomic unit.

In part 3 we already worked through how forwardRef is born from a single backward import. On the graph, that looks like this.

Can this be proven mathematically?

In short — the statement "the architecture doesn't degrade" is, by itself, not mathematical. Degradation is defined by people, and any structure can be broken with deliberate disregard. But structural properties, under which degradation is hindered in a specific way, can be formally proven. Let's go through three such properties.

1. The DAG invariant

The system's dependency graph splits into two levels — inside a single module and between modules. We'll show that both levels are DAGs.

The intra-module graph. Let's introduce:

V_M — the set of classes of module M (handlers, repositories, domain types, presentation, the external port)
E_M ⊆ V_M × V_M — the intra-module "depends on" edges
L: V_M → ℕ — the layer function within a single module: domain = 0, infrastructure = 1, use-case = 2, external = 3, presentation = 4

Claim. If for every edge (x, y) ∈ E_M we have L(x) > L(y), then the intra-module graph (V_M, E_M) contains no cycle. Technically, such a graph is called a DAG, Directed Acyclic Graph.

Proof. Suppose the graph contains a cycle x₁ → x₂ → ... → xₙ → x₁. Then from the condition:

L(x₁) > L(x₂) > ... > L(xₙ) > L(x₁)

which gives L(x₁) > L(x₁) — a contradiction. No cycle can exist. What does this step mean? A cycle is a path that brings us back to the starting point. But every edge along this path strictly lowers the value of L: from the first class to the second (L(x₁) > L(x₂)), from the second to the third, and so on. By the end of the path, we have to be strictly lower than the starting value — and at the same time at the starting point itself, where L again equals the starting value. "Strictly lower" and "the same" simultaneously — impossible. That is the contradiction.

In FBCA this function exists by construction: every file lives in one of the layers, and the direction of imports is set by convention. External acts as a facade over the use-cases of its own module — it imports handlers (L(external) = 3 > L(use-case) = 2), not the other way around.

The inter-module graph. The intra-module L function says nothing about the ties between modules — for those, a separate rule applies.

V_inter — the set of modules in the system
Edges — "module X imports code of module Y"

Rule. Any import from module X into module Y is permitted only through the external/ port of module Y. The external itself doesn't import other modules — this is its constructive property: it declares the surface of its own module and delegates into the internal handlers of that same module, and nothing more.

Consequence. A cycle M₁ → M₂ → ... → Mₙ → M₁ would require every module in the chain to import the external of the next one. But if M₁.external imports nothing from outside its own module, there is simply nowhere for the edge Mₙ → M₁ to come from — that's a violation of the rule itself. A cycle between modules is topologically impossible.

Result: the system graph is a DAG both inside each module (through the layer function) and between modules (through the external-only rule).

This is the formalization of the phrase "dependencies flow in only one direction." In feature-based, there's neither L nor an external rule: services can import each other in any direction, so cycles are topologically possible — and that's what materializes in practice (the very case from part 3).

What this means in practice (and where `forwardRef` fits in)

The clearest way to explain what a DAG is — imagine you walk through the graph on foot, following the arrows.

In FBCA, every step strictly lowers you down the layers: from presentation to use-case, from use-case to infrastructure, from infrastructure to domain. Once you reach domain, there are no arrows out. The walk ends naturally.

In a graph with a cycle, no such "end" exists. You go along an arrow, then a second, then a third — and discover that you've returned to where you started. And you'll go around the same loop again, and again, and so on to infinity. The only way to stop is to separately remember "I've already been here."

That's exactly what NestJS does via forwardRef. When the DI container encounters a circular dependency, it can't resolve it "honestly" — it would have to create A in order to pass it to B, but B is required to create A. forwardRef tells the container: "hold off on instantiating right now, I'll come back to this connection later." That is, the framework marks for itself "already seen," so as not to go into a loop.

In an FBCA structure, that crutch isn't needed at all. The graph has nowhere to loop — every walk along the arrows has a natural end at the domain layer. NestJS resolves dependencies in one pass, without marks and without forwardRef.

2. The coupling bound

A module's coupling = the size of its public API.

In feature-based:

API(M) = the union of all public methods of all services exported from M

This size grows automatically with every new method of any service.

In FBCA:

API(M) = the public methods of M.external

The size grows only when an operation is explicitly added to the external/ port.

Consequence. At equal functionality, |API_FBCA(M)| ≤ |API_FB(M)|, because in FB every public method of a service automatically becomes part of the module's API, while in FBCA — only what's explicitly laid out in external/.

In information-theoretic terms: coupling, as the mutual information between consumer and module, is bounded by the size of the API. The FBCA structure rigidly limits the surface through which accidental coupling is possible.

3. The cost of change

Let F be the feature being added.

In FB, when a method is added to a god service S:

Writing the new logic: O(1) lines
Hidden expansion of the surface: O(|consumers(S)|) consumers now have access to the new operation
Possible regressions: proportional to the number of consumers

In FBCA, when a new operation is added:

Creating a new folder <verb-noun>/ with a handler and a module: O(1) lines
Hidden expansion of the surface: O(0) — no existing handler changes, no external service grows

Qualitatively:

IncrementalCost_FB(F)   ∈ O(|consumers|)
IncrementalCost_FBCA(F) ∈ O(1)

This is the very "cost flatness" we were talking about earlier: in FB, the price of each next feature grows with the number of existing consumers; in FBCA, it stays a constant.

Under what conditions this holds

All three claims are conditional on three invariants:

The function L is monotonic — no "upward" edges: a handler doesn't call presentation, a repository doesn't call a use-case.
Every module exposes only the external/ port. Internal handlers and repositories are exported nowhere outward.
A use-case doesn't call a neighboring use-case. Common logic descends downward — into the repository or the domain — rather than spreading sideways.

Without these conditions, the proofs don't work. That is, what can be strictly stated is only the following:

When the layer and external-port invariants are observed, the dependency graph is a DAG, the API size is bounded by the size of the external surface, and the cost of adding a feature is constant.

What is proven is concrete structural properties under the observance of concrete rules. These properties (the absence of cycles, bounded coupling, constant cost of an increment) constitute the real content of the term "doesn't degrade."

Let's now visualize the scaling process of the project and the Users module — first, let's simplify the graph visualization and take a snapshot of the current state.

Let's imagine a year of production use has gone by. The set of use-cases in the graph below isn't a preventive decomposition, it's the accumulated answer to concrete requirements and incidents: each group emerged as a response to a specific PM request, an incident, or a regulatory requirement. A quick rundown by group, with the source of each.

Presentation (what the user does with their own account):

Profile. The basic "every user has a profile" page sprouted dedicated endpoints after A/B tests on inline editing (bio, avatar) and incidents with username changes and displayName impersonation.
Settings. Support got tired of "I can't unsubscribe from emails" tickets — email-prefs were carved out into a separate flow. Privacy and blocking-rules — under GDPR and extended blocking. Language and theme are separated because each has its own external flow (an i18n cache, theme sync across devices).
Me and my data. The me endpoint and stats — the basic surface for the frontend. Engagement-stats was added after the creator-tools release.
GDPR / Compliance. Deletion with a 14-day window, restoration, and export of all data as JSON — the mandatory trio under GDPR/CCPA.

External (what neighboring modules need):

Identity. The basic "create / find / check user" operations. Some were introduced from day one (for Auth), some — after incidents: bulk-get-users after the first slow feed with N+1, check-user-exists after a DB-load analysis ("why pull an object when a boolean is enough"), display-info — a lightweight profile for rendering in comments.
Graph. The social graph: follows, visibility, notifications. can-view-content appeared after the private-accounts release; check-blocked-by — after an incident in which Feed delivered content from a user who had blocked the viewer.
Access. Permissions and statuses: blocks, verification, tiers (after monetization), get-user-since for anti-fraud (a new account = less trust), permissions after the admin panel was expanded.

And what matters: in each of these cases, a new endpoint is a new folder next to the others, with no edits to the old ones. The graph grows vertically, not outward.

The graph has grown threefold, but its shape is the same. The same five boxes, the same arrows top to bottom. If three more releases come tomorrow and the count of use-cases reaches sixty — the picture won't change structurally: the same five boxes, just with the HTML labels inside getting cramped. No new edges, no new graph entities.

This is what's called "the architecture stayed in shape." Not because we didn't touch it — we added dozens of new files. It's because we didn't deform it: we didn't have to introduce new types of relationships, rewrite existing use-cases under new requirements, or untangle accumulated compromises. Every requirement landed as a new folder next to the others, and the old folders had no interest in it.

Feature Based Clean Architecture. Part 4: FBCA: Formalizing Responsibility Boundaries in a NestJS Module

Victor Shkirov — Sun, 10 May 2026 19:18:52 +0000

An architectural doctrine for NestJS projects: a breakdown of typical codebase degradation scenarios and the structural constraints that keep them from emerging as the feature set grows.

For three parts we've watched how an "ordinary" NestJS project arrives at forwardRef and the rest of the wall. It's time to answer the question, "how not to do this." This is the moment to say "Clean Architecture" — and immediately offer a caveat. Anyone who has read about it for more than five minutes knows: there are so many contradictory interpretations grazing around this term that for two different people "Clean Architecture" means two different systems. It isn't a single approach, and it isn't the circles Bob Martin drew in the form of commandments. It's a family of ideas that converges on a single thesis: business logic is separated from infrastructure, and dependencies flow in only one direction. Everything else is implementation choices.

The basic idea

If you strip out all the "architectural magic," what's left is a few very simple rules:

business logic must not depend on frameworks
dependencies should go in one direction — inward, toward the domain
code should have boundaries, not be a dump
the database, HTTP, queues — these are just details, not the center of the system

Everything else is a consequence of breaking these rules.

Domain / Use Case / Infrastructure / Presentation

To stop building a system that turns into legacy half a year later, we finally need to introduce boundaries. Not "folders for the sake of order," but boundaries that can't be accidentally crossed — without breaking through TypeScript, NestJS DI, or the team's own discipline.

The simplest working model:

Domain — what is actually going on in the business
Use Case — which scenarios we implement
Infrastructure — how it's stored and how it works technically
Presentation — how all of this is approached from the outside

This isn't about a "pretty project structure," it's about control over the system: without boundaries, logic flows wherever, dependencies grow, and code turns into chaos. And this isn't a matter of taste — every architecture has a formal description through graph theory, where modules and services are vertices and dependencies are edges. On such a graph it's strictly visible why one system degrades while another stays manageable. Clean Architecture in this sense is a way of imposing constraints on that graph. We'll tackle the numbers in part 5.

We move from simple to complex — redoing the same project from the other side, starting with the original structure.

The old project structure

src/
├── main.ts
├── app.module.ts
│
├── modules/
│   ├── auth/
│   ├── users/
│   ├── tweets/
│   ├── feed/
│   ├── likes/
│   ├── comments/
│   ├── retweets/
│   ├── follows/
│   ├── notifications/
│   ├── search/
│   └── media/
│
├── common/
│   ├── guards/
│   ├── interceptors/
│   ├── filters/
│   ├── decorators/
│   └── utils/
│
├── database/
│   ├── typeorm/
│   └── migrations/
│
├── config/
│   └── configuration.ts

The structure itself isn't bad — splitting by features is a working approach. The trouble isn't on the top level, but in the fact that the internals of the modules and their interactions with each other have no rules that would keep the system in shape after half a year of work.

Previously the internal module was structured like this

src/modules/tweets/
├── tweets.module.ts
├── tweets.controller.ts
├── tweets.service.ts
├── dto/
│   └── create-tweet.dto.ts
├── entities/
│   └── tweet.entity.ts

How will we introduce Clean Architecture?

I propose we don't abandon the idea of splitting the system's modules by features or by the project's key domains. Classical Clean Architecture has its own problems, which are also hard to solve. We'll be doing what is essentially Feature Based Clean Architecture.

How the internal module will be structured now

src/modules/tweets/
├── domain/
│   └── tweet.ts
│
├── use-case/
│   └── create-tweet/
│       ├── create-tweet.handler.ts
│       └── create-tweet.module.ts
│
├── infrastructure/
│   └── repositories/
│       ├── tweet.entity.ts
│       ├── tweet.repository.ts
│       └── tweet.repository.module.ts
│
└── presentation/
    ├── tweets-presentation.controller.ts
    ├── tweets-presentation.service.ts
    ├── tweets-presentation.module.ts
    └── dto/
        └── create-tweet.dto.ts

The structure literally reads in layers.

Presentation — presentation/. The transport: controller, DTO, presentation-service. It knows only about HTTP and which use-case to call.
Use-case — use-case/create-tweet/. The "create a tweet" scenario: orchestration, checks, all the business logic. That very place where, in feature-based, TweetsService would bloat.
Infrastructure — infrastructure/repositories/. Data access through a repository abstraction, plus the ORM entity that only the repository sees.
Domain — domain/tweet.ts. The model and its invariants, with no knowledge of where it's stored or how it got here.

The rule that holds all of this together — dependencies point inward: presentation → use-case → infrastructure (through the repository port) → domain. Domain knows about no one. Use-case knows nothing about HTTP. Infrastructure knows nothing about the scenario.

Let's also start with auth

@Controller("auth")
export class AuthPresentationController {
  constructor(
    private readonly authPresentationService: AuthPresentationService,
  ) {}

  @Post("sign-up")
  async signUp(@Body() dto: SignUpDto): Promise<SignUpResponse> {
    return this.authPresentationService.signUp(dto.email, dto.password);
  }

  @Post("sign-in")
  async signIn(@Body() dto: SignInDto): Promise<SignInResponse> {
    return this.authPresentationService.signIn(dto.email, dto.password);
  }
}

And here's the most interesting question, the one we kept putting off in feature-based until it was too late: how does Auth actually get the user? In the previous architecture, AuthService.signUp quietly burrowed straight into UsersService.create(...), which in turn called something else, and a couple of iterations later we had a forwardRef, a cycle, and the very case from part 3. Here, SignUpHandler lives inside Auth, and the user data lives inside Users. A boundary has to run between them — otherwise everything we've built here will simply move into the use-case, and a couple of sprints later the handler will start importing UserRepository directly. Before drawing that boundary — let's look at the Users module itself.

src/modules/users/
├── domain/
│   └── user.ts
│
├── use-case/
│   ├── create-user/
│   │   ├── create-user.handler.ts
│   │   └── create-user.module.ts
│   │
│   └── get-user-by-email/
│      ├── get-user-by-email.handler.ts
│      └── get-user-by-email.module.ts
│
├── infrastructure/
│   └── repositories/
│       ├── user.entity.ts
│       ├── user.repository.ts
│       └── user.repository.module.ts

How will Auth communicate with Users to avoid repeating past mistakes? We need a contract — and the most honest way to justify it comes through microservices. In the microservice world, the database per service pattern has been around for a long time: each service has its own database, and a neighbor doesn't reach into your table, no matter how much they'd like to. Out of this restriction, a useful side effect emerges on its own — Auth and Users start communicating only through an explicit, restricted contract, because there's no other way. The idea is so good it would be a shame to leave it only beyond the network boundary: it can be carried inside the monolith, without spinning up a zoo of real services. This contract is what's called a port.

A port is the module's interface,
describing what it exposes outward — and nothing else.

That is, not an implementation, not a repository, not a business scenario. It's a declaration — a list of operations and data available to neighboring modules, as if a network boundary stood behind the module. You can pick your own naming; what matters is the meaning. Next — how this port will fit inside Users.

src/modules/users/
├── domain/
│   └── user.ts
│
├── use-case/
│   ├── create-user/
│   │   ├── create-user.handler.ts
│   │   └── create-user.module.ts
│   │
│   └── get-user-by-email/
│       ├── get-user-by-email.handler.ts
│       └── get-user-by-email.module.ts
│
├── infrastructure/
│   └── repositories/
│       ├── user.entity.ts
│       ├── user.repository.ts
│       └── user.repository.module.ts
│
├── external/                         # The port (contract) of the Users module
│   ├── users-external.module.ts
│   └── users-external.service.ts

An important detail: neither outside nor inside the module is the entity exposed — everywhere the code leaves the repository, what travels is user.ts. The handler that actually drives the business logic never holds a UserEntity in its hands: the repository itself goes to the database, maps the row into the entity, converts it into a domain object, and passes that on. Which means the use-case doesn't care which ORM lies underneath — TypeORM, Prisma, raw SQL — and which database is there. So if one day you want to move from TypeORM to Prisma, or from Postgres to Mongo, the migration hits the infrastructure layer: rewrite the entity, rewrite the body of the repository, fix the connection config. The business logic won't notice the swap. If the entity surfaced outward — whether through the port or straight into the use-case via findOne() — save(), decorators, and the binding to the table schema would ride out with it; and any neighboring module would start mutating data around your port.

// user.ts
export type User = {
  id: string;
  email: string;
  password: string;
  createdAt: Date;
};

// user.entity.ts
@Entity("users")
export class UserEntity {
  @PrimaryGeneratedColumn("uuid")
  id: string;

  @Column({ unique: true })
  email: string;

  @Column()
  password: string;

  @CreateDateColumn()
  createdAt: Date;
}

// user.repository.ts
@Injectable()
export class UserRepository {
  constructor(
    @InjectRepository(UserEntity)
    private readonly repository: Repository<UserEntity>,
  ) {}

  async create(data: CreateUserData): Promise<Result<User, CreateErrorCode>> {
    const insertUserResult = await fromAsyncThrowable(async () =>
      this.repository.insert(data),
    )();

    if (insertUserResult.isErr()) {
      if (isUniqueQueryError(insertUserResult.error)) {
        return err("CREATE_USER_CONFLICT");
      }

      return err("CREATE_USER_DATABASE_ERROR");
    }

    const now = new Date();
    return ok({
      id: insertUserResult.value.identifiers[0].id,
      email: data.email,
      password: data.password,
      createdAt: now,
    });
  }

  async findByEmail(
    email: string,
  ): Promise<Result<User | undefined, FindErrorCode>> {
    const findUserResult = await fromAsyncThrowable(async () =>
      this.repository.findOne({ where: { email } }),
    )();

    if (findUserResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }

    return ok(findUserResult.value ?? undefined);
  }
}

Since we're in the context of NestJS, we need to think about how use-cases and ports will inject the repository. The rule is simple: each repository lives in its own module and is plugged in one at a time, where it's needed. No UsersInfrastructureModule that exports everything at once. The reason is in the dependency graph. When get-user-by-email.module.ts explicitly writes imports: [UserRepositoryModule], at a glance it's clear what exactly this scenario needs. When a generic UsersInfrastructureModule sits there — nothing is clear: the handler can reach into UserRepository, into UserProfileRepository, into UserSettingsRepository, and all of that is invisible to the reviewer. And half a year later it'll turn out that get-user-by-email quietly pulls in three unnecessary tables, because "it's coming from the shared module anyway."

In essence, what we're doing here is taking the idea of Clean Architecture and lowering it to the level of the DI framework: the same boundaries between layers, only now they're expressed not through a directory, but through a Nest module. The rule "a handler knows only about its own dependencies" stops being a convention point and becomes mechanical. The architecture and the DI graph begin to coincide.

// user.repository.module.ts
@Module({
  imports: [TypeOrmModule.forFeature([UserEntity])],
  providers: [UserRepository],
  exports: [UserRepository],
})
export class UserRepositoryModule {}

Now we need to expose two methods, createUser and getUserByEmail, through the port so that auth can use them. And here it's worth noting that you can't simply hand a repository method out through the port directly. A repository is the data layer — it has no checks, no invariants, no orchestration; if the port calls it bypassing the use-case, there's simply nowhere to put any business logic around that call. Today, "get a user by email" is one query. Tomorrow — a query plus a block check, a cache, and tracking. All of that lives in the handler. If the port goes around it, the handler is excluded from the chain, and any new logic will have to land either in the repository (a layer violation) or in the port (the same). That's why we need a dedicated handler that will perform exactly this function.

// get-user-by-email.handler.ts
@Injectable()
export class GetUserByEmailHandler {
  constructor(private readonly userRepository: UserRepository) {}

  async run(
    email: string,
  ): Promise<Result<User | undefined, GetUserByEmailHandlerErrorCode>> {
    const findUserResult = await this.userRepository.findByEmail(email);

    if (findUserResult.isErr()) {
      return err("GET_USER_BY_EMAIL_DATABASE_ERROR");
    }

    return ok(findUserResult.value);
  }
}

The same rule as for the repository: one scenario — its own module, its own export. Whoever needs GetUserByEmailHandler imports exactly that, not "all of Users's use-cases in bulk."

// get-user-by-email.module.ts
@Module({
  imports: [UserRepositoryModule],
  providers: [GetUserByEmailHandler],
  exports: [GetUserByEmailHandler],
})
export class GetUserByEmailModule {}

In the end, UsersExternalService works as a thin facade: it holds the handlers inside and forwards calls into them, deciding nothing on its own. This is the very public contract for whose sake we were remembering database per service. Neighboring modules see neither UserRepository nor the internal handlers — they see only the set of operations Users has explicitly laid out in external. Everything else is conceptually behind a "network boundary" that doesn't actually exist, but that exists in the rules.

// users-external.service.ts
@Injectable()
export class UsersExternalService {
  constructor(
    private readonly createUserHandler: CreateUserHandler,
    private readonly getUserByEmailHandler: GetUserByEmailHandler,
  ) {}

  async getUserByEmail(
    email: string,
  ): Promise<Result<User | undefined, GetUserByEmailHandlerErrorCode>> {
    return this.getUserByEmailHandler.run(email);
  }

  async createUser(
    data: CreateUserData,
  ): Promise<Result<User, CreateUserHandlerErrorCode>> {
    return this.createUserHandler.run(data);
  }
}

Let's return to the Auth module. The new architecture doesn't let you stuff a scenario just anywhere — but it also won't tell you if you stick it in the wrong place. Before showing the right place, let's look at a typical mistake: plugging UsersExternalService directly into AuthPresentationService, right at the transport itself.

One important nuance. Nest won't complain in this case: DI will calmly resolve the dependency, because UsersExternalService is exported and AuthPresentationService is allowed to import it. The "who can call whom" restrictions are not the DI graph — they're layer rules; for a machine to catch them, you need a separate linter like eslint-plugin-boundaries. Without it, such violations are caught only by eyes at review — which, as we remember, passes in thirty seconds.

Bad usage

@Injectable()
export class AuthPresentationService {
  constructor(
    private readonly jwtService: JwtService,
    private readonly usersExternalService: UsersExternalService,
  ) {}

  async signUp(
    email: string,
    password: string,
    res: Response,
  ): Promise<SignUpResponse> {
    const findUserResult =
      await this.usersExternalService.getUserByEmail(email);

    if (findUserResult.isErr()) {
      throw new InternalServerErrorException();
    }

    if (findUserResult.value) {
      throw new ConflictException("User already exists");
    }

    const createUserResult = await this.usersExternalService.createUser({
      email,
      password,
    });

    if (createUserResult.isErr()) {
      throw new InternalServerErrorException();
    }

    const signTokenResult = await fromAsyncThrowable(async () =>
      this.jwtService.signAsync({ sub: createUserResult.value.id }),
    )();

    if (signTokenResult.isErr()) {
      throw new InternalServerErrorException();
    }

    res.cookie("accessToken", signTokenResult.value, {
      httpOnly: true,
      secure: true,
      sameSite: "strict",
    });

    return {
      id: createUserResult.value.id,
      email: createUserResult.value.email,
    };
  }

  async signIn(
    email: string,
    password: string,
    res: Response,
  ): Promise<SignInResponse> {
    const findUserResult =
      await this.usersExternalService.getUserByEmail(email);

    if (findUserResult.isErr()) {
      throw new InternalServerErrorException();
    }

    if (!findUserResult.value) {
      throw new UnauthorizedException("Invalid credentials");
    }

    if (findUserResult.value.password !== password) {
      throw new UnauthorizedException("Invalid credentials");
    }

    const signTokenResult = await fromAsyncThrowable(async () =>
      this.jwtService.signAsync({ sub: findUserResult.value.id }),
    )();

    if (signTokenResult.isErr()) {
      throw new InternalServerErrorException();
    }

    res.cookie("accessToken", signTokenResult.value, {
      httpOnly: true,
      secure: true,
      sameSite: "strict",
    });

    return {
      id: findUserResult.value.id,
      email: findUserResult.value.email,
    };
  }
}

Why is this wrong? Because the business logic still lives in AuthPresentationService. You've removed direct access to the repository, but you haven't removed the main thing — the concentration of scenarios in one place.

What this will lead to:

All scenarios will start flowing into AuthPresentationService: sign-up, sign-in, refresh, logout, social login, 2FA, recovery.
Dependencies will pile up alongside it: Users, Tokens, Sessions, Email, AntiFraud, Analytics.
The service will again turn into an orchestrator of everything, even though its primary task is to serve the transport layer.

After a couple of iterations, you'll have exactly what was in feature-based. It doesn't matter what the code goes through inside — UserRepository or UsersExternalService. You again have one class that knows too much and carries the whole system on its back.

The right approach

src/modules/auth/
├── use-case/
│   ├── sign-up/
│   │   ├── sign-up.handler.ts
│   │   └── sign-up.module.ts
│   │
│   └── sign-in/
│       ├── sign-in.handler.ts
│       └── sign-in.module.ts
│
├── presentation/
│   ├── auth-presentation.controller.ts
│   ├── auth-presentation.service.ts
│   └── dto/
│       ├── sign-up.dto.ts
│       └── sign-in.dto.ts

We need a handler that doesn't care who called it. On the input — the scenario's parameters; on the output — the result; in between — the business logic. No HTTP wrapper, no knowledge of Express, Fastify, or that a controller exists at all. This gives two concrete things. First, the scenario can now be tested with a single handler.run(...) call — no HTTP-stack mocks, no e2e wrappers. Second, if tomorrow a GraphQL schema or gRPC service appears on top of the REST API, only the presentation layer will need to be rewritten; the handler will stay as it is.

@Injectable()
export class SignUpHandler {
  constructor(
    private readonly jwtService: JwtService,
    private readonly usersExternalService: UsersExternalService,
  ) {}

  async run(
    email: string,
    password: string,
  ): Promise<Result<SignUpResult, SignUpErrorCode>> {
    const findUserResult =
      await this.usersExternalService.getUserByEmail(email);

    if (findUserResult.isErr()) {
      return err("SIGN_UP_GET_USER_FAILED");
    }

    if (findUserResult.value) {
      return err("SIGN_UP_USER_ALREADY_EXISTS");
    }

    const createUserResult = await this.usersExternalService.createUser({
      email,
      password,
    });

    if (createUserResult.isErr()) {
      return err("SIGN_UP_CREATE_USER_FAILED");
    }

    const signTokenResult = await fromAsyncThrowable(async () =>
      this.jwtService.signAsync({ sub: createUserResult.value.id }),
    )();

    if (signTokenResult.isErr()) {
      return err("SIGN_UP_TOKEN_SIGN_FAILED");
    }

    return ok({
      user: createUserResult.value,
      accessToken: signTokenResult.value,
    });
  }
}

And now — back to presentation. Here lives the code that explicitly knows about the transport: in our case it's HTTP via Express, and that means — headers, cookies, statuses, everything that relates specifically to this communication channel.

@Injectable()
export class AuthPresentationService {
  constructor(private readonly signUpHandler: SignUpHandler) {}

  async signUp(dto: SignUpDto, res: Response): Promise<SignUpResponse> {
    const signUpResult = await this.signUpHandler.run(dto.email, dto.password);

    if (signUpResult.isErr()) {
      if (signUpResult.error === "SIGN_UP_USER_ALREADY_EXISTS") {
        throw new ConflictException("User already exists");
      }

      throw new InternalServerErrorException();
    }

    res.cookie("accessToken", signUpResult.value.accessToken, {
      httpOnly: true,
      secure: true,
      sameSite: "strict",
    });

    return {
      id: signUpResult.value.user.id,
      email: signUpResult.value.user.email,
    };
  }
}

Of course, you can also keep cookie logic directly in the controller — formally it's the same presentation zone, and @Controller will set cookies just fine through @Res() res. This is a matter of taste, but I prefer for the controller to read like a map: a list of endpoints, their paths, input DTOs, Guards, interceptors — and nothing else. Everything that relates to the body of handling — packing cookies, assembling the response, mapping exceptions to HTTP statuses — moves into the presentation-service. The controller remains a declaration of the module's surface; the presentation-service — the place where it's implemented.

@Controller("auth")
export class AuthPresentationController {
  constructor(
    private readonly authPresentationService: AuthPresentationService,
  ) {}

  @Post("sign-up")
  async signUp(
    @Body() dto: SignUpDto,
    @Res({ passthrough: true }) res: Response,
  ): Promise<SignUpResponse> {
    return this.authPresentationService.signUp(dto, res);
  }
}

Let's now look at our dependency graph.

Why does this approach help the architecture hold its shape longer? Not because Nest watches over this — it doesn't watch, it's just a DI framework, and it knows about layers no more than tsc does. The protection rests on three things, none of which come out of the box.

Convention. Every module exposes outward only *External*Service; handlers, repositories, the domain — are exported nowhere. This can be broken; Nest will calmly hand out any provider you decide to export. But the shortcut "let me just open GetUserByEmailHandler to Auth" leaves a trace: users-external.module.ts changes, an export gets added, it's imported into the Auth handler. Each of these files lands in the diff and at review.

Linter. eslint-plugin-boundaries or dependency-cruiser lets you describe "auth/ imports only from users/external/*" — and catch violations in the IDE before commit. This is the very layer where the architectural rule becomes checkable at build time. Optional, but it's exactly what turns discipline from "we agreed" into "won't pass."

Review. When there's no linter, what's left is eyes. Without a linter, the FBCA structure helps not with "don't degrade," but with "degrade more visibly": every shortcut now leaves a diff that looks suspicious. It lowers the odds, but not to zero.

In sum: a new feature lands cleanly into a new module more easily than sloppily — not because sloppily isn't allowed, but because sloppy is now visible. Half a year later, it's exactly this asymmetry that determines how quickly the team adds features.

For comparison, let's look at what the feature-based dependency graph would look like at this stage of development.

It looks much simpler, which is why it's hard to grasp the real meaning of Clean Architecture right away. The deceptiveness of the FB graph is in one thing: it's drawn by new projects. Legacy in which AuthService has grown ten dependencies and a forwardRef doesn't publish its own graphs — it's already too well-known to the team for anyone to bother drawing it.

So when a newcomer sees the comparison "here's FB — three classes and an arrow," "here's FBCA — ten classes and clusters," they're looking at the phase in which FB really does win: the first month of the project. This is survivorship bias in pure form: static comparisons almost always show the moment when nothing has had time to break yet.

Understanding of Clean Architecture comes not right away — when it seems cumbersome — but a year later, when it turns out it hasn't fallen apart. And it's exactly this difference that's hard to feel in advance: people see today's cost, and they find it hard to believe that the investment will pay off.

In the next part, I'll show visually why feature-based started to degrade, while feature-based-clean will keep going for a very long time.

Feature Based Clean Architecture. Part 3: The Architectural Risk of Cycles in NestJS: ROI of Decisions on a Five-Year Horizon

Victor Shkirov — Sun, 10 May 2026 19:09:15 +0000

An architectural doctrine for NestJS projects: a breakdown of typical codebase degradation scenarios and the structural constraints that keep them from emerging as the feature set grows.

Now let's see what this "decomposition into services" actually costs on a horizon a little longer than one sprint. Our product already has a FollowsService — it lives tidily in its own module, drops "followerId → targetUserId" relations into its table, and knows nothing it shouldn't. In parallel — UsersModule, with the pieces split out into separate services: UserPrivacyService and UserSettingsService. Each is responsible for its own facet of the user. Single responsibility, the implementation is clean, review is a celebration.

Then complaints start coming in through support: strangers send all kinds of nastiness in DMs, users want to hide their profiles from random eyes. The request is clear, human — the PM picks it up: we'll do private accounts. You can't follow a private profile directly — you send a follow request, the owner either approves it or not. The logic fits on half a page in Notion. The idea is trivial, a day's work, maybe two.

Case: private accounts and follows

The ticket lands in the backend. What needs to change? Before FollowsService creates a record in follows, it has to go and find out whether the account being followed is private. If yes — we drop the request into follow_requests and wait for the owner's approval. If no — we continue as usual. Knowledge about privacy lives in UsersModule (where else should it live?), which means FollowsService starts depending on UserPrivacyService. A dependency like that passes review in thirty seconds.

@Injectable()
export class FollowsService {
  constructor(private readonly userPrivacyService: UserPrivacyService) {}

  async follow(
    followerId: string,
    targetUserId: string,
  ): Promise<FollowResponse> {
    const isPrivateResult =
      await this.userPrivacyService.isPrivate(targetUserId);

    if (isPrivateResult.isErr()) {
      throw new InternalServerErrorException(isPrivateResult.error);
    }

    if (isPrivateResult.value) {
      return this.createFollowRequest(followerId, targetUserId);
    }

    return this.createFollow(followerId, targetUserId);
  }

  private async createFollowRequest(
    followerId: string,
    targetUserId: string,
  ): Promise<FollowResponse> {
    // create the follow request
  }

  private async createFollow(
    followerId: string,
    targetUserId: string,
  ): Promise<FollowResponse> {
    // create the follow
  }
}

At this stage, everything really is in order. FollowsService asked UsersModule: "private or not?" — and moved on. One dependency arrow, going one way, drawn on the architect's diagram without loops. If features ended here — we'd have neither this article nor the problem. But features, as a rule, don't end.

A couple of sprints later, a second scenario appears in the product: a viewer visits someone else's profile. And here a whole batch of questions surfaces that "private or not" no longer covers. Can the viewer see the profile? Can they see the tweets? Can they see the likes, the stories, someone else's follows? The logic grows: each type of content gets its own rules, private accounts get their own, blocked users get separate ones. The old UserPrivacyService can no longer handle this (it can only answer the binary question "private or not"), and the team sets up a new service alongside it — UserAccessService. By every textbook — single responsibility, separation of concerns, everything as it should be.

And it's at exactly this point that UserAccessService runs into an uncomfortable question. To answer "can the viewer see the owner's tweets," it has to know whether the viewer follows the owner. And that information lives in FollowsService. Which means UserAccessService starts depending on FollowsService.

@Injectable()
export class UserAccessService {
  constructor(
    private readonly followsService: FollowsService,
    private readonly userPrivacyService: UserPrivacyService,
  ) {}

  async canViewProfile(
    viewerId: string,
    ownerId: string,
  ): Promise<Result<boolean, UserAccessErrorCode>> {
    const isPrivateResult = await this.userPrivacyService.isPrivate(ownerId);
    if (isPrivateResult.isErr()) {
      return err(isPrivateResult.error);
    }
    if (!isPrivateResult.value) {
      return ok(true);
    }

    const isFollowingResult = await this.followsService.isFollowing(
      viewerId,
      ownerId,
    );
    if (isFollowingResult.isErr()) {
      return err(isFollowingResult.error);
    }
    return ok(isFollowingResult.value);
  }

  async canViewTweets(
    viewerId: string,
    ownerId: string,
  ): Promise<Result<boolean, UserAccessErrorCode>> {
    const isPrivateResult = await this.userPrivacyService.isPrivate(ownerId);
    if (isPrivateResult.isErr()) {
      return err(isPrivateResult.error);
    }
    if (!isPrivateResult.value) {
      return ok(true);
    }

    const isFollowingResult = await this.followsService.isFollowing(
      viewerId,
      ownerId,
    );
    if (isFollowingResult.isErr()) {
      return err(isFollowingResult.error);
    }

    return ok(isFollowingResult.value);
  }
}

We have our first cycle. At first glance — an innocuous problem: at the service level, it's still hidden behind good naming.

UserAccessService:
  → FollowsService
  → UserPrivacyService

FollowsService:
  → UserPrivacyService

All arrows point forward, none of them backward — formally pretty. But at the module level, the picture is already mirrored:

FollowsModule  ⇄  UsersModule

FollowsModule imports UsersModule for UserPrivacyService. UsersModule imports FollowsModule for FollowsService. Each import on its own is completely justified — any reviewer can let it through and approve. But together they form a trap that won't snap shut today, and not tomorrow — but in two or three sprints, on a random Thursday, on someone's PR that has nothing to do with these imports themselves.

And now the same thing in code

If you unfold all of this into a flat set of @Module decorators, the picture looks deceptively simple. FollowsModule declares "I need UsersModule," UsersModule declares "I need FollowsModule":

@Module({
  imports: [UsersModule],
  providers: [FollowsService],
  exports: [FollowsService],
})
export class FollowsModule {}

@Module({
  imports: [FollowsModule],
  providers: [UserPrivacyService, UserAccessService],
  exports: [UserPrivacyService, UserAccessService],
})
export class UsersModule {}

Four imports, two exports, no forwardRef, no tricks. Not a single line looks suspicious — on any of them, in any team, you'll get an approve in ten seconds. And it's exactly this pair of imports that's enough for NestJS to throw that very Nest can't resolve dependencies.

Nest provides the cure itself, right in the documentation — forwardRef. You wrap the import in an arrow function, and DI resolves the dependency lazily, at use time, not at build time. Sounds like permission from above: the framework doesn't just allow it — it recommends it. The team reads, nods, patches both decorators:

@Module({
  imports: [forwardRef(() => UsersModule)],
  providers: [FollowsService],
  exports: [FollowsService],
})
export class FollowsModule {}

@Module({
  imports: [forwardRef(() => FollowsModule)],
  providers: [UserPrivacyService, UserAccessService],
  exports: [UserPrivacyService, UserAccessService],
})
export class UsersModule {}

And everything seems to work again. The build compiles, tests run, the logs are quiet. At review, the two words forwardRef will pass as easily as the imports themselves — it's a documented API, everything is legitimate. The PR gets merged — and for half a year the cycle is collectively forgotten.

And now — the moment `forwardRef` starts taking revenge

Half a year later, no one remembers the Users ↔ Follows cycle anymore. Life goes on, features ship, CI is green, new developers see forwardRef in imports and accept it as part of the project's style — if it's done everywhere, that's how it's supposed to be.

And then the team sits down to a new feature — a feed with comments. We already have CommentsModule and ModerationModule. Guess what relationship they're in. CommentsService calls into ModerationService to ask "can this comment be posted?" (anti-spam, ban, rate-limit). ModerationService calls into CommentsService for the user's last N comments to compute the spam score. A cycle? A cycle. forwardRef? forwardRef.

@Module({
  imports: [forwardRef(() => ModerationModule)],
  providers: [CommentsService],
  exports: [CommentsService],
})
export class CommentsModule {}

@Module({
  imports: [forwardRef(() => CommentsModule)],
  providers: [ModerationService],
  exports: [ModerationService],
})
export class ModerationModule {}

Now FeedModule appears. The feed is built from posts, under each post — comments, and comments from banned users have to be hidden. The straightforward option is to import both modules:

@Module({
  imports: [CommentsModule, ModerationModule],
  providers: [FeedService],
})
export class FeedModule {}

And you could stop there. But then a completely healthy architectural instinct kicks in:

"Hold on, why should Feed even know about Moderation? Moderation is an implementation detail of Comments. If tomorrow we replace it with an ML model, Feed shouldn't have to know about it. Let's make CommentsModule a facade and re-export ModerationService through it."

This is the right reasoning. By every textbook — facades, encapsulation, minimum knowledge at the consumer. Any reviewer who knows their stuff will approve a PR like this.

@Module({
  imports: [forwardRef(() => ModerationModule)],
  providers: [CommentsService],
  exports: [CommentsService, ModerationService], // facade-ing
})
export class CommentsModule {}

And here Nest tells us:

Nest can't resolve dependencies of the FeedService (?).
Please make sure that the argument ModerationService at index [0] is available in the FeedModule context.

No forwardRef will help here. Because forwardRef is not a module, it's a proxy-placeholder, and it can't be carried transitively through exports. At the moment CommentsModule is being assembled, ModerationService for it still "doesn't exist" in any full sense.

And so begins the iteration through options, none of which look appealing. You can import ModerationModule into Feed directly — but that's a rejection of the facade, and knowledge of moderation spreads out to everyone working with comments. You can drop the re-export and leave two separate imports — essentially the same thing, plus the feeling that the architecture is "leaking." You can break the cycle for real — rewrite CommentsModule and ModerationModule, dig into code that was touched half a year ago and that no one really remembers; a senior at standup promises "let's do it next sprint," and that sprint, naturally, never comes. You can, finally, pour more forwardRefs on top — sometimes it helps, sometimes it doesn't, always fragile, and the logs start showing pretty TypeError: Cannot read properties of undefined.

And this is the real cost of forwardRef: it doesn't solve the problem, it freezes it. It doesn't formally forbid normal patterns — but as soon as you try to apply them, it forces you to invent workarounds: the facade can't be done via re-export — let's do it through a separate aggregator service; then the aggregator itself falls into a cycle — let's call it through ModuleRef.get() at runtime; then in tests half the graph doesn't come up — let's mock by hand. And these dances around an old cycle eat up the lion's share of time on every next feature. Development turns into attempts to make this thing at least compile and start up, not into moving the product forward — even if the author of that cycle has long since quit, and all that's left in the code is their comment // TODO: untangle.

And now imagine that it isn't one cycle written like this, but 60% of the codebase. Refactoring on the inside is no longer possible on a reasonable timeline — any change in one module drags five neighboring ones along through forwardRefs, the "two-day" estimate turns into "two sprints," the result is unpredictable in advance. And nobody even wants to go into code that was touched eight years ago and that no one remembers anymore — fixing the old thing is psychologically more expensive than writing a new one next to it. And "next to it" in a broken monolith is already a separate service. And right here the team finds an "adequate" way out: chop the functionality into microservices. Not because that's domain-correct, not because the load demands it, but because the monolith physically doesn't compile, and no one inside is ready to fix it. Next — design the transport between services (gRPC? REST? Kafka? RabbitMQ?), separate synchronous and asynchronous interaction, set up load balancing and service discovery, split CI/CD into separate pipelines, write contract tests, smear everything with retries, circuit breakers, and distributed tracing, occupy DevOps for a quarter, retrain the team on network errors. And all of this — to hide comments from banned users. The perfect ratio of "infrastructure investment" to "product benefit": $10k a month in operating costs for one checkbox on a feature checklist.

Let's even calculate the cost difference for a small team. You have a product, your team is 2 backend engineers and 1 frontend engineer. Take an averaged fully-loaded cost for one mid-level backend engineer — $5k/month with all taxes, insurance, and equipment. Two backend engineers for a year = $120k.

In a healthy project, "fighting the architecture" — debugging the build, fixing tests, working around things — takes 5–10% of the time. In a project that's been sitting under forwardRefs for half a year to a year — a steady 30–50%. On the delta between these two states, $30–60k a year is literally burned on flat ground, even if not a single feature has been written in that period.

But these are just the direct costs. Much scarier — opportunity cost. In a healthy codebase your team ships a feature a week. With accumulated cycles the same team ships the same feature in three to four weeks — not because the developers got worse, but because 70% of the sprint goes to "why doesn't it compile / why don't the tests run / how do we get around the cycle." Over a year, that's 9 months of undelivered features. In a market where, over the same period, a competitor shipped a partner program, recommendations, and a paid subscription, you simply stop being considered.

And here's the final chord. That very first forwardRef, which half a year ago saved the team at most 4 hours, in fact gets paid for with $30–60k a year of direct costs and nine months of lost market. ROI of that decision: –35,000% in the first year, –180,000% by the fifth, –360,000% by the tenth. But no one counts it that way, because the bill doesn't come at once — it comes as a smeared payment across every future sprint — and there's no one really to blame: the author quit, the team turned over, and the forwardRef stands as it stood.

And now imagine if this is big tech or enterprise. The team isn't 2 backend engineers, but 50–200 people on a single product. The fully-loaded cost of one senior is already $30–40k/month with all benefits and L&D. One product — $20–30M a year just on development. The share of time spent "fighting the architecture" is the same — 30–50%. On the delta, that's $6–15M a year flat down the drain, without a single feature written.

On top of that, a separate platform team of 10–15 seniors emerges, whose only job is to help product teams work around their own architecture. Another $4–6M a year. Any attempt at a large migration is an 18–24 month project with a $15–30M budget, during which no features ship at all. In that time, a competitor ships three new product lines.

Then second-order effects kick in. The seniors who understand that fixing it is no longer possible leave within a year or two — their career here boils down to an endless fight with their own legacy. In their place come people who need half a year just to figure out where they can touch and where they can't. Inside the product, a "framework war" blooms: teams build their own local wrappers just to avoid touching the central modules. Any M&A deal slips on its timeline by half — integrating the acquired company into this tangle is physically impossible. Technical debt turns into a corporate risk at the board-of-directors level — and at the same time it still looks like "an innocuous forwardRef that someone put in eight years ago."

To summarize briefly: everything we've gone through in this part — from cycles and forwardRefs to millions per year and framework wars — is symptoms of the same problem. Modules have no internal structure. Services call services, methods call methods, and any attempt to "split things up properly" runs into the fact that there's nothing to split — inside the module everything is mixed equally. No one wrote bad code. It's just that no one wrote any good code either. In the next part, we'll start from the other side: what has to be inside a module to make a cycle like this physically impossible to build.

So what do we actually do? This example was meant to convey how poorly thought-out architecture turned the project's code into Schrödinger's cat. You and I, step by step, built a system that brought losses to the business, made time-to-market for features many times longer, turned developers from people who develop into people who stabilize a system held together with duct tape. Even though everything started off well.

Feature Based Clean Architecture. Part 2: Decomposition into Services: An Analysis of the Approach's Limits

Victor Shkirov — Sun, 10 May 2026 19:06:42 +0000

An architectural doctrine for NestJS projects: a breakdown of typical codebase degradation scenarios and the structural constraints that keep them from emerging as the feature set grows.

A quick recap, to avoid going back to part 1. We left AuthService.signUp in a state that needs no defense: two hundred lines in one function, six parameters at the input, four independent business domains in one method, and five different repositories in one dependency. And we've already formulated which answer comes up first: split it across services — UsersService, ReferralsService, MarketingService, FraudService, PartnerService — each with its own zone of responsibility; leave AuthService as the orchestrator. This answer is the standard one, recognized by the NestJS community, and any team will adopt it for refactoring without extra discussion.

Part 2 is about what happens when the team honestly carries this refactoring out. Spoiler: the code will become more pleasant on the eye, more files will appear, the signUp method will slim down — and at the same time, everything that was bad in V3 will stay bad, just in new packaging. To see this, you first have to go through the refactoring step by step, the way any normal team would.

The team's standard reaction to code in this state is to open a separate refactoring ticket. The plan is obvious: while preserving the current behavior, split the logic from one method across several services, each with its own zone of responsibility. AuthService remains the orchestration point, and the other services perform concrete operations in their domains.

AuthService (orchestration)
│
├── UsersService        — user creation, lookup by email, working with user data
├── AntiFraudService    — abuse checks (IP, device, behavioral scoring)
├── ReferralService     — referral validation, link creation, limits and abuse protection
├── PartnerService      — handling partner programs (bloggers, streamers, partners) and revenue calculation
├── BonusService        — bonus accrual (referral, partner, multi-level)
├── AnalyticsService    — event recording (registration, experiments, conversions, segmentation)
├── AdSourceService     — working with traffic sources (lookup, increments, A/B tests)

The team sits down to the refactoring with this plan in hand. The ticket goes into work, gets wrapped in tests, passes the architect's review, and a few days later auth.service.ts ends up roughly like this.

AuthService.signUp V4

async signUp(
  email: string,
  password: string,
  referralCode?: string,
  adSourceCode?: string,
  ip?: string,
  deviceId?: string,
): Promise<SignUpResponse> {
  await this.antiFraudService.checkIp(ip);
  await this.antiFraudService.checkDevice(deviceId);
  await this.antiFraudService.checkBehavior(ip, deviceId);

  const adSource = adSourceCode
    ? await this.adSourceService.resolve(adSourceCode)
    : undefined;
  if (adSourceCode && !adSource) {
    throw new BadRequestException("Invalid ad source");
  }

  if (adSource) {
    await this.adSourceService.increment(adSource.id);
    await this.analyticsService.trackExperiment({
      source: adSource.code,
    });
  }

  const referral = referralCode
    ? await this.referralService.getByCode(referralCode)
    : undefined;
  if (referralCode && !referral) {
    throw new BadRequestException("Invalid referral code");
  }

  const partnerResult =
    referral && referral.influencerPartner
      ? await this.partnerService.processPartner(referral)
      : undefined;
  const referralOwner =
    referral && !referral.influencerPartner
      ? await this.referralService.validateReferral(referral, email)
      : undefined;

  const existingUserByEmail = await this.usersService.findByEmail(email);
  if (existingUserByEmail) {
    throw new BadRequestException("User already exists");
  }

  const newUser = await this.usersService.createUser({
    email,
    password,
    adSource,
    ip,
    deviceId,
  });

  if (referralOwner) {
    await this.bonusService.giveReferralBonus(referralOwner.id);
    await this.referralService.createReferral(referralOwner, newUser);
  }

  if (partnerResult) {
    await this.bonusService.givePartnerReward(
      partnerResult.ownerId,
      partnerResult.reward,
    );
    await this.analyticsService.trackPartnerReward(partnerResult);
  }

  await this.analyticsService.trackRegistration({
    userId: newUser.id,
    source: adSource?.code,
    ip,
  });

  return {
    id: newUser.id,
    email: newUser.email,
  };
}

A note on error handling. Further on in the code, you'll see that the services signUp depends on (all the ones we just extracted) start returning not thrown exceptions, but an explicit Result<T, E>. This is an object that communicates the operation's outcome through the .isErr() method and access to .value or .error. The change is deliberate: each internal service handles errors as part of the function's contract, and the caller sees the entire set of possible outcomes right in the type. signUp itself remains the boundary point between business logic and HTTP transport — it accepts the Result from each call and converts errors on the spot into the appropriate HttpException, because the NestJS filter at the HTTP level expects exactly those. The convenient thing about this separation is that Result-style and throw-style no longer compete: inside services — Result; at the AuthService boundary — a concrete BadRequestException / ConflictException / ForbiddenException / InternalServerErrorException, which NestJS will turn into the right HTTP code. The specific implementation of Result is a matter of preference. I use a monad because over the long haul I find it more convenient: the compiler forces every outcome to be made explicit. Everything shown below is equally implementable through discriminated unions, any library with similar semantics, or classical try/catch — the architectural meaning doesn't change. If you want to see the industry standard for this approach in TypeScript, it's the neverthrow library — its API is what I'm using in the code. To note in advance: switching to Result on its own doesn't cure anything in the architecture — it only makes errors visible. Everything structural we've discussed stays in place. It just no longer hides behind throws deep in the call stack.

AuthService.signUp V5

async signUp(
  email: string,
  password: string,
  referralCode?: string,
  adSourceCode?: string,
  ip?: string,
  deviceId?: string,
): Promise<SignUpResponse> {
  const checkIpResult = await this.antiFraudService.checkIp(ip);
  if (checkIpResult.isErr()) {
    throw new ForbiddenException(checkIpResult.error);
  }

  const checkDeviceResult = await this.antiFraudService.checkDevice(deviceId);
  if (checkDeviceResult.isErr()) {
    throw new ForbiddenException(checkDeviceResult.error);
  }

  const checkBehaviorResult = await this.antiFraudService.checkBehavior(
    ip,
    deviceId,
  );
  if (checkBehaviorResult.isErr()) {
    throw new ForbiddenException(checkBehaviorResult.error);
  }

  const resolveAdSourceResult = adSourceCode
    ? await this.adSourceService.resolve(adSourceCode)
    : ok(undefined);

  if (resolveAdSourceResult.isErr()) {
    throw new BadRequestException(resolveAdSourceResult.error);
  }
  const adSource = resolveAdSourceResult.value;

  if (adSource) {
    const incrementAdSourceResult = await this.adSourceService.increment(
      adSource.id,
    );

    if (incrementAdSourceResult.isErr()) {
      throw new InternalServerErrorException(incrementAdSourceResult.error);
    }

    const trackExperimentResult = await this.analyticsService.trackExperiment(
      { source: adSource.code },
    );

    if (trackExperimentResult.isErr()) {
      throw new InternalServerErrorException(trackExperimentResult.error);
    }
  }

  const getReferralResult = referralCode
    ? await this.referralService.getByCode(referralCode)
    : ok(undefined);

  if (getReferralResult.isErr()) {
    throw new BadRequestException(getReferralResult.error);
  }
  const referral = getReferralResult.value;

  const processPartnerResult =
    referral && referral.influencerPartner
      ? await this.partnerService.processPartner(referral)
      : ok(undefined);

  if (processPartnerResult.isErr()) {
    throw new InternalServerErrorException(processPartnerResult.error);
  }

  const partnerResult = processPartnerResult.value;

  const validateReferralResult =
    referral && !referral.influencerPartner
      ? await this.referralService.validateReferral(referral, email)
      : ok(undefined);

  if (validateReferralResult.isErr()) {
    throw new BadRequestException(validateReferralResult.error);
  }

  const referralOwner = validateReferralResult.value;

  const findUserResult = await this.usersService.findByEmail(email);

  if (findUserResult.isErr()) {
    throw new InternalServerErrorException(findUserResult.error);
  }

  if (findUserResult.value) {
    throw new ConflictException("USER_ALREADY_EXISTS");
  }

  const createUserResult = await this.usersService.createUser({
    email,
    password,
    adSource,
    ip,
    deviceId,
  });
  if (createUserResult.isErr()) {
    if (createUserResult.error === "CREATE_USER_CONFLICT") {
      throw new ConflictException(createUserResult.error);
    }

    throw new InternalServerErrorException(createUserResult.error);
  }
  const newUser = createUserResult.value;

  if (referralOwner) {
    const giveReferralBonusResult =
      await this.bonusService.giveReferralBonus(referralOwner.id);

    if (giveReferralBonusResult.isErr()) {
      throw new InternalServerErrorException(giveReferralBonusResult.error);
    }

    const createReferralResult = await this.referralService.createReferral(
      referralOwner,
      newUser,
    );
    if (createReferralResult.isErr()) {
      throw new InternalServerErrorException(createReferralResult.error);
    }
  }

  if (partnerResult) {
    const givePartnerRewardResult =
      await this.bonusService.givePartnerReward(
        partnerResult.ownerId,
        partnerResult.reward,
      );

    if (givePartnerRewardResult.isErr()) {
      throw new InternalServerErrorException(givePartnerRewardResult.error);
    }

    const trackPartnerRewardResult =
      await this.analyticsService.trackPartnerReward(partnerResult);

    if (trackPartnerRewardResult.isErr()) {
      throw new InternalServerErrorException(trackPartnerRewardResult.error);
    }
  }

  const trackRegistrationResult =
    await this.analyticsService.trackRegistration({
      userId: newUser.id,
      source: adSource?.code,
      ip,
    });

  if (trackRegistrationResult.isErr()) {
    throw new InternalServerErrorException(trackRegistrationResult.error);
  }

  return {
    id: newUser.id,
    email: newUser.email,
  };
}

This version is what the team shows at demo. At the AuthService.signUp level, everything really is the way it was meant to be: each dependency occupies its own zone of responsibility, the orchestration has stayed thin, and you can point a finger at the code and immediately see where anti-fraud lives, where partners are, where analytics is. The architect nods, review closes in fifteen minutes. But the architectural trap doesn't lie in AuthService.signUp — and never did. To see it, you have to stop looking at the orchestrator and open one of those services we've just carefully extracted. Let's take the first one in order — UsersService.

The Users module's evolution

In parallel with sign-up growing more complex, the users module itself wasn't standing still either. The frontend needed methods for displaying and editing the profile; analytics needed counters and slices; marketing needed user attributes and segmentation; support needed administrative operations. What at the start of the article was a single small module with one table has, by this point, turned into a self-contained domain with its own set of use-cases. By the current stage, UsersService is responsible for, at minimum, the following:

fetching the user profile
updating the profile (bio, avatar, username)
updating account settings
account privacy (public / private)
fetching basic stats (number of followers and follows)
managing user preferences (language, theme, notifications)
fetching the current user (/me endpoint)

src/modules/users/
├── users.module.ts
├── users.service.ts
├── users.controller.ts
├── dto/
│   ├── get-profile.dto.ts
│   ├── update-profile.dto.ts
│   ├── update-account-settings.dto.ts
│   ├── update-privacy.dto.ts
│   ├── update-preferences.dto.ts
│   ├── get-user-stats.dto.ts
│   └── me.dto.ts
└── entities/
    ├── user.entity.ts
    ├── user-profile.entity.ts
    ├── user-settings.entity.ts
    ├── user-privacy.entity.ts
    ├── user-preferences.entity.ts
    ├── user-stats.entity.ts
    └── user-session.entity.ts

For this set of scenarios, the module has gained its own controller, in which each use-case has its own endpoint. At this stage, the controller looks like this:

@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(":id/profile")
  async getProfile(@Param() dto: GetProfileDto): Promise<UserProfileResponse> {
    return this.usersService.getProfile(dto.userId);
  }

  @Patch(":id/profile")
  async updateProfile(
    @Param() params: GetProfileDto,
    @Body() dto: UpdateProfileDto,
  ): Promise<UserProfileResponse> {
    return this.usersService.updateProfile(params.userId, dto);
  }

  @Patch(":id/settings")
  async updateAccountSettings(
    @Param() params: GetProfileDto,
    @Body() dto: UpdateAccountSettingsDto,
  ): Promise<UserAccountSettingsResponse> {
    return this.usersService.updateAccountSettings(params.userId, dto);
  }

  @Patch(":id/privacy")
  async updatePrivacy(
    @Param() params: GetProfileDto,
    @Body() dto: UpdatePrivacyDto,
  ): Promise<UserPrivacyResponse> {
    return this.usersService.updatePrivacy(params.userId, dto);
  }

  @Patch(":id/preferences")
  async updatePreferences(
    @Param() params: GetProfileDto,
    @Body() dto: UpdatePreferencesDto,
  ): Promise<UserPreferencesResponse> {
    return this.usersService.updatePreferences(params.userId, dto);
  }

  @Get(":id/stats")
  async getUserStats(
    @Param() dto: GetUserStatsDto,
  ): Promise<UserStatsResponse> {
    return this.usersService.getUserStats(dto.userId);
  }

  @Get("me")
  async getMe(@Req() req: Request): Promise<CurrentUserResponse> {
    return this.usersService.getCurrentUser(req.user.id);
  }
}

At the controller level, the structure looks exemplary: seven endpoints — seven zones of responsibility, each with its own DTO, none of them tangling with the others. A natural question arises — and what's happening at this moment to the service the controller relies on? The logical expectation is this: since the controller is cleanly split across use-cases, UsersService should mirror that structure — a separate method per scenario, a separate zone of responsibility, the same discipline inside. That's how it's set up in most textbook examples, and that's how it's recommended in the NestJS documentation. Let's open users.service.ts and see what ended up in a real project instead of the expectation.

UsersService V1

@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private readonly userRepository: Repository<User>,
    @InjectRepository(UserProfile)
    private readonly profileRepository: Repository<UserProfile>,
    @InjectRepository(UserSettings)
    private readonly settingsRepository: Repository<UserSettings>,
    @InjectRepository(UserPrivacy)
    private readonly privacyRepository: Repository<UserPrivacy>,
    @InjectRepository(UserPreferences)
    private readonly preferencesRepository: Repository<UserPreferences>,
    @InjectRepository(UserStats)
    private readonly statsRepository: Repository<UserStats>,
  ) {}

  async findByEmail(
    email: string,
  ): Promise<Result<User | undefined, FindUserErrorCode>> {
    const findUserResult = await fromAsyncThrowable(async () =>
      this.userRepository.findOne({ where: { email } }),
    )();

    if (findUserResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }

    return ok(findUserResult.value ?? undefined);
  }

  async createUser(
    data: CreateUserData,
  ): Promise<Result<User, CreateUserErrorCode>> {
    const newUser = this.userRepository.create({
      email: data.email,
      password: data.password,
      registrationIp: data.ip,
      deviceId: data.deviceId,
      adSource: data.adSource,
      isVerified: false,
    });

    const saveUserResult = await fromAsyncThrowable(async () =>
      this.userRepository.save(newUser),
    )();

    if (saveUserResult.isErr()) {
      if (isUniqueQueryError(saveUserResult.error)) {
        return err("CREATE_USER_CONFLICT");
      }
      return err("CREATE_USER_DATABASE_ERROR");
    }

    const initUserRelationsResult = await fromAsyncThrowable(async () =>
      Promise.all([
        this.profileRepository.save({ userId: newUser.id }),
        this.settingsRepository.save({ userId: newUser.id }),
        this.privacyRepository.save({ userId: newUser.id }),
        this.preferencesRepository.save({ userId: newUser.id }),
        this.statsRepository.save({ userId: newUser.id }),
      ]),
    )();

    if (initUserRelationsResult.isErr()) {
      return err("CREATE_USER_DATABASE_ERROR");
    }

    return ok(newUser);
  }

  async getProfile(userId: string): Promise<UserProfile> {
    const profile = await this.profileRepository.findOne({ where: { userId } });
    if (!profile) {
      throw new NotFoundException("USER_PROFILE_NOT_FOUND");
    }
    return profile;
  }

  async updateProfile(
    userId: string,
    dto: UpdateProfileDto,
  ): Promise<UserProfile> {
    await this.profileRepository.update({ userId }, dto);
    return this.getProfile(userId);
  }

  async updateAccountSettings(
    userId: string,
    dto: UpdateAccountSettingsDto,
  ): Promise<UserSettings> {
    await this.settingsRepository.update({ userId }, dto);

    const settings = await this.settingsRepository.findOne({
      where: { userId },
    });
    if (!settings) {
      throw new NotFoundException("USER_SETTINGS_NOT_FOUND");
    }
    return settings;
  }

  async updatePrivacy(
    userId: string,
    dto: UpdatePrivacyDto,
  ): Promise<UserPrivacy> {
    await this.privacyRepository.update({ userId }, dto);

    const privacy = await this.privacyRepository.findOne({
      where: { userId },
    });
    if (!privacy) {
      throw new NotFoundException("USER_PRIVACY_NOT_FOUND");
    }
    return privacy;
  }

  async updatePreferences(
    userId: string,
    dto: UpdatePreferencesDto,
  ): Promise<UserPreferences> {
    await this.preferencesRepository.update({ userId }, dto);

    const preferences = await this.preferencesRepository.findOne({
      where: { userId },
    });
    if (!preferences) {
      throw new NotFoundException("USER_PREFERENCES_NOT_FOUND");
    }
    return preferences;
  }

  async getUserStats(userId: string): Promise<UserStats> {
    const stats = await this.statsRepository.findOne({ where: { userId } });
    if (!stats) {
      throw new NotFoundException("USER_STATS_NOT_FOUND");
    }
    return stats;
  }

  async getCurrentUser(userId: string): Promise<CurrentUserResponse> {
    const [profile, settings, privacy, preferences, stats] = await Promise.all([
      this.profileRepository.findOne({ where: { userId } }),
      this.settingsRepository.findOne({ where: { userId } }),
      this.privacyRepository.findOne({ where: { userId } }),
      this.preferencesRepository.findOne({ where: { userId } }),
      this.statsRepository.findOne({ where: { userId } }),
    ]);

    if (!profile || !settings || !privacy || !preferences || !stats) {
      throw new NotFoundException("USER_NOT_FOUND");
    }

    return { profile, settings, privacy, preferences, stats };
  }
}

Visually, UsersService looks acceptable: types are in place, errors are handled, method names read clearly. But it's precisely at this point that the main structural signal — the reason we opened this file first — reveals itself. UsersService has a special status that distinguishes it from any other service in the system: it is not a feature service, but a data service — it doesn't answer for a business scenario, it answers for the user entity itself, which the rest of the application reaches into one way or another. And that's exactly why a queue gradually forms around it.

AuthService is already here — it was first in line, during sign-up, as we saw in signUp V4/V5. The controller is here too — it returns the user their own data. Over the next few sprints, almost every other module in the product will join that queue. Feed will want to know who the user follows and who they allow to read them. Notifications — where to send the push, whether notifications are enabled, and whether the recipient is blocked. Comments, Likes, and Follows — that the user exists, that they're not private (or that the viewer is subscribed to them), plus username and avatar for display. Search — filter results by privacy and return the profile. Media — check upload permissions. Moderation and anti-fraud — status, behavior, the history of actions. And all of these requests — every single one, without exception — will land in the same file.

UsersService V2

@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private readonly userRepository: Repository<User>,
    @InjectRepository(UserProfile)
    private readonly profileRepository: Repository<UserProfile>,
    @InjectRepository(UserSettings)
    private readonly settingsRepository: Repository<UserSettings>,
    @InjectRepository(UserPrivacy)
    private readonly privacyRepository: Repository<UserPrivacy>,
    @InjectRepository(UserPreferences)
    private readonly preferencesRepository: Repository<UserPreferences>,
    @InjectRepository(UserStats)
    private readonly statsRepository: Repository<UserStats>,
  ) {}

  async findByEmail(
    email: string,
  ): Promise<Result<User | undefined, FindUserErrorCode>> {
    const findUserResult = await fromAsyncThrowable(async () =>
      this.userRepository.findOne({ where: { email } }),
    )();
    if (findUserResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }
    return ok(findUserResult.value ?? undefined);
  }

  async createUser(
    data: CreateUserData,
  ): Promise<Result<User, CreateUserErrorCode>> {
    const newUser = this.userRepository.create({
      email: data.email,
      password: data.password,
      registrationIp: data.ip,
      deviceId: data.deviceId,
      adSource: data.adSource,
      isVerified: false,
    });

    const saveUserResult = await fromAsyncThrowable(async () =>
      this.userRepository.save(newUser),
    )();
    if (saveUserResult.isErr()) {
      if (isUniqueQueryError(saveUserResult.error)) {
        return err("CREATE_USER_CONFLICT");
      }
      return err("CREATE_USER_DATABASE_ERROR");
    }

    const initUserRelationsResult = await fromAsyncThrowable(async () =>
      Promise.all([
        this.profileRepository.save({ userId: newUser.id }),
        this.settingsRepository.save({ userId: newUser.id }),
        this.privacyRepository.save({ userId: newUser.id }),
        this.preferencesRepository.save({ userId: newUser.id }),
        this.statsRepository.save({ userId: newUser.id }),
      ]),
    )();
    if (initUserRelationsResult.isErr()) {
      return err("CREATE_USER_DATABASE_ERROR");
    }

    return ok(newUser);
  }

  async exists(userId: string): Promise<Result<boolean, FindUserErrorCode>> {
    const checkExistsResult = await fromAsyncThrowable(async () =>
      this.userRepository.exist({ where: { id: userId } }),
    )();
    if (checkExistsResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }
    return ok(checkExistsResult.value);
  }

  async getProfile(userId: string): Promise<UserProfile> {
    const profile = await this.profileRepository.findOne({ where: { userId } });
    if (!profile) {
      throw new NotFoundException("USER_PROFILE_NOT_FOUND");
    }
    return profile;
  }

  async updateProfile(
    userId: string,
    dto: UpdateProfileDto,
  ): Promise<UserProfile> {
    await this.profileRepository.update({ userId }, dto);
    return this.getProfile(userId);
  }

  async updateAccountSettings(
    userId: string,
    dto: UpdateAccountSettingsDto,
  ): Promise<UserSettings> {
    await this.settingsRepository.update({ userId }, dto);

    const settings = await this.settingsRepository.findOne({
      where: { userId },
    });
    if (!settings) {
      throw new NotFoundException("USER_SETTINGS_NOT_FOUND");
    }
    return settings;
  }

  async updatePrivacy(
    userId: string,
    dto: UpdatePrivacyDto,
  ): Promise<UserPrivacy> {
    await this.privacyRepository.update({ userId }, dto);

    const privacy = await this.privacyRepository.findOne({
      where: { userId },
    });
    if (!privacy) {
      throw new NotFoundException("USER_PRIVACY_NOT_FOUND");
    }
    return privacy;
  }

  async updatePreferences(
    userId: string,
    dto: UpdatePreferencesDto,
  ): Promise<UserPreferences> {
    await this.preferencesRepository.update({ userId }, dto);

    const preferences = await this.preferencesRepository.findOne({
      where: { userId },
    });
    if (!preferences) {
      throw new NotFoundException("USER_PREFERENCES_NOT_FOUND");
    }
    return preferences;
  }

  async getUserStats(userId: string): Promise<UserStats> {
    const stats = await this.statsRepository.findOne({ where: { userId } });
    if (!stats) {
      throw new NotFoundException("USER_STATS_NOT_FOUND");
    }
    return stats;
  }

  async getCurrentUser(userId: string): Promise<CurrentUserResponse> {
    const [profile, settings, privacy, preferences, stats] = await Promise.all([
      this.profileRepository.findOne({ where: { userId } }),
      this.settingsRepository.findOne({ where: { userId } }),
      this.privacyRepository.findOne({ where: { userId } }),
      this.preferencesRepository.findOne({ where: { userId } }),
      this.statsRepository.findOne({ where: { userId } }),
    ]);

    if (!profile || !settings || !privacy || !preferences || !stats) {
      throw new NotFoundException("USER_NOT_FOUND");
    }

    return { profile, settings, privacy, preferences, stats };
  }

  async getFollowingIds(
    userId: string,
  ): Promise<Result<string[], FindUserErrorCode>> {
    return ok([]);
  }

  async canViewContent(
    viewerId: string,
    ownerId: string,
  ): Promise<Result<boolean, FindUserErrorCode>> {
    const isPrivateResult = await this.isPrivate(ownerId);
    if (isPrivateResult.isErr()) {
      return err(isPrivateResult.error);
    }
    if (!isPrivateResult.value) {
      return ok(true);
    }

    const getFollowingResult = await this.getFollowingIds(viewerId);
    if (getFollowingResult.isErr()) {
      return err(getFollowingResult.error);
    }
    return ok(getFollowingResult.value.includes(ownerId));
  }

  async canReceiveNotification(
    userId: string,
    type: string,
  ): Promise<Result<boolean, FindUserErrorCode>> {
    const findSettingsResult = await this.findUserSettings(userId);
    if (findSettingsResult.isErr()) {
      return err(findSettingsResult.error);
    }

    const settings = findSettingsResult.value;
    if (!settings) return ok(false);

    if (type === "email") return ok(settings.emailNotifications);
    if (type === "push") return ok(settings.pushNotifications);
    return ok(false);
  }

  async getPublicUserInfo(
    userId: string,
  ): Promise<Result<UserPublicInfo, FindUserErrorCode>> {
    const findProfileResult = await fromAsyncThrowable(async () =>
      this.profileRepository.findOne({ where: { userId } }),
    )();
    if (findProfileResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }

    return ok({
      id: userId,
      username: findProfileResult.value?.username,
      avatarUrl: findProfileResult.value?.avatarUrl,
    });
  }

  async isSearchable(
    userId: string,
  ): Promise<Result<boolean, FindUserErrorCode>> {
    const findPrivacyResult = await this.findUserPrivacy(userId);
    if (findPrivacyResult.isErr()) {
      return err(findPrivacyResult.error);
    }
    return ok(!findPrivacyResult.value?.isPrivate);
  }

  async isUserBlocked(
    userId: string,
  ): Promise<Result<boolean, FindUserErrorCode>> {
    return ok(false);
  }

  async getUserStatus(
    userId: string,
  ): Promise<Result<UserStatus | undefined, FindUserErrorCode>> {
    const findUserResult = await fromAsyncThrowable(async () =>
      this.userRepository.findOne({
        where: { id: userId },
        select: ["id", "isVerified"],
      }),
    )();
    if (findUserResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }
    return ok(findUserResult.value ?? undefined);
  }

  private async findUserSettings(
    userId: string,
  ): Promise<Result<UserSettings | undefined, FindUserErrorCode>> {
    const findSettingsResult = await fromAsyncThrowable(async () =>
      this.settingsRepository.findOne({ where: { userId } }),
    )();
    if (findSettingsResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }
    return ok(findSettingsResult.value ?? undefined);
  }

  private async findUserPrivacy(
    userId: string,
  ): Promise<Result<UserPrivacy | undefined, FindUserErrorCode>> {
    const findPrivacyResult = await fromAsyncThrowable(async () =>
      this.privacyRepository.findOne({ where: { userId } }),
    )();
    if (findPrivacyResult.isErr()) {
      return err("FIND_USER_DATABASE_ERROR");
    }
    return ok(findPrivacyResult.value ?? undefined);
  }

  private async isPrivate(
    userId: string,
  ): Promise<Result<boolean, FindUserErrorCode>> {
    const findPrivacyResult = await this.findUserPrivacy(userId);
    if (findPrivacyResult.isErr()) {
      return err(findPrivacyResult.error);
    }
    return ok(!!findPrivacyResult.value?.isPrivate);
  }
}

At this point the team kicks off the same ritual that any project with a bloated service goes through at least once — and which the reader has just seen in this very article applied to another service. The decomposition that initially looked obvious and logical produced the opposite effect over time: UsersService turned into a file no one wants to open alone, and every new developer in their first week phrases the same thing: "let me rewrite this." The standard response to this state is well known to everyone — add more services. Since one class has grown disproportionately, let's split it into several smaller ones, each handed its own piece. Especially since the boundaries inside look obvious — the same use-cases the controller serves:

the user profile
account settings
privacy
preferences
stats
checks for other modules

The decomposition plan ends up identical in form to the one we did for AuthService a few pages back:

src/modules/users/
├── users.module.ts
├── users.controller.ts
│
├── services/
│   ├── users.service.ts
│   ├── user-profile.service.ts
│   ├── user-settings.service.ts
│   ├── user-privacy.service.ts
│   ├── user-preferences.service.ts
│   ├── user-stats.service.ts
│   └── user-access.service.ts
│
├── dto/
│   ├── get-profile.dto.ts
│   ├── update-profile.dto.ts
│   ├── update-account-settings.dto.ts
│   ├── update-privacy.dto.ts
│   ├── update-preferences.dto.ts
│   ├── get-user-stats.dto.ts
│   └── me.dto.ts
│
└── entities/
    ├── user.entity.ts
    ├── user-profile.entity.ts
    ├── user-settings.entity.ts
    ├── user-privacy.entity.ts
    ├── user-preferences.entity.ts
    ├── user-stats.entity.ts
    └── user-session.entity.ts

Now things seem to have gotten better:

UserProfileService is responsible for the profile
UserSettingsService is responsible for the settings
UserPrivacyService is responsible for privacy
UserPreferencesService is responsible for preferences
UserStatsService is responsible for stats
UserAccessService is responsible for access checks

It seems we've finally put things in order. Each service is responsible for its own piece, files are shorter, methods are flat, dependencies on the diagram draw as arrows in one direction. At demo, this looks like a win.

And at exactly this moment, the next ticket lands in the team — the one in which all this will start to break. No architectural upheavals — just another ordinary feature, a day's work. Let's go through it.

Feature Based Clean Architecture. Part 1: How a NestJS Application Evolves Into an Unmaintainable State

Victor Shkirov — Sun, 10 May 2026 19:04:54 +0000

An architectural doctrine for NestJS projects: a breakdown of typical codebase degradation scenarios and the structural constraints that keep them from emerging as the feature set grows.

This article is a breakdown of how a typical NestJS backend degrades as the feature set grows, and how the ideas of Clean Architecture make it possible to avoid that. I'll walk through the full cycle: show on a "before and after" example how the feature-based structure that today is pushed as the standard loses control with scale; dissect the typical degradation scenarios; estimate in money and engineer-hours what they cost the business; explain why this kind of codebase forces teams to break monoliths into microservices long before it's justified. After that, I'll propose an approach designed against degradation — and back it with a formal mathematical argument. By the end of the article, you'll have both the reasoning and the tools to apply this approach to your own systems.

As a running example, we'll take the task that comes up on System Design interviews time and time again: a backend for a Twitter-class service. The minimal toolkit is obvious — a database and an application. Questions of peak performance, sharding, and horizontal scaling we'll deliberately set aside: this article is about code structure, not throughput. Let's fix the stack right away — Node.js and the NestJS framework. Let's start by writing out the functional requirements for the system.

Sign-up and sign-in
Tweet creation
Feed
Follows (follow / unfollow)
User profile
Likes
Retweets
Comments (replies)
Search (users, tweets, hashtags)
Notifications (likes, follows, replies)
Media (images / videos)

Obviously the real Twitter is built an order of magnitude more complicated and was assembled over years by a team of hundreds of engineers — but the article's goal isn't to reproduce the product, it's to examine architectural evolution on a familiar problem domain. The list of features is fixed, the schema and the set of endpoints at this stage practically draw themselves, the stack is chosen. We open the NestJS documentation — and from the very first page the documentation suggests a baseline project structure.

src/
├── main.ts
├── app.module.ts
│
├── modules/
│   ├── auth/
│   ├── users/
│   ├── tweets/
│   ├── feed/
│   ├── likes/
│   ├── comments/
│   ├── retweets/
│   ├── follows/
│   ├── notifications/
│   ├── search/
│   └── media/
│
├── common/
│   ├── guards/
│   ├── interceptors/
│   ├── filters/
│   ├── decorators/
│   └── utils/
│
├── database/
│   ├── prisma/ or typeorm/
│   └── migrations/
│
├── config/
│   └── configuration.ts

Beyond the top-level structure, the documentation also describes a recommended composition for a single module — which files and in what order it makes sense to create. This recommendation is the same for modules of different nature: auth, tweets, and search are all assembled to the same template. I'll show it on the tweets module:

src/modules/tweets/
├── tweets.module.ts
├── tweets.controller.ts
├── tweets.service.ts
├── dto/
│   └── create-tweet.dto.ts
├── entities/
│   └── tweet.entity.ts

At first glance the layout looks tidy: clean separation, obvious rules for where things go, a low entry barrier for a new developer. In practice, though — without additional architectural discipline — within six months it turns into hard-to-maintain code. Further on we'll see exactly how: step by step, through a sequence of locally reasonable decisions. Let's start with the module that exists in nearly any product — users and authentication.

The minimal required functionality: two endpoints — sign-up and sign-in.

@Controller("auth")
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @Post("sign-up")
  async signUp(@Body() dto: SignUpDto): Promise<SignUpResponse> {
    return this.authService.signUp(dto.email, dto.password);
  }

  @Post("sign-in")
  async signIn(@Body() dto: SignInDto): Promise<SignInResponse> {
    return this.authService.signIn(dto.email, dto.password);
  }
}

As the ORM throughout the article we'll use TypeORM — the choice isn't critical for the architecture conversation, and everything below transfers easily to Prisma, MikroORM, or Drizzle. We just need a tool that's convenient for showing queries. First, let's describe the user entity.

@Entity("users")
export class User {
  @PrimaryGeneratedColumn("uuid")
  id: string;

  @Column({ unique: true })
  email: string;

  @Column()
  password: string;

  @CreateDateColumn()
  createdAt: Date;
}

By the accepted structure, code related to working with users should live in src/modules/users. Which means the logic for creating a user record in the database formally belongs to that module too. That's already decent discipline — better than putting SQL queries directly into AuthService. But at this point the developer really has two options: hit the user repository directly from AuthService, or go through UsersService. At a small scale both options work and both pass review — so let's first look at them side by side.

@Injectable()
export class AuthService {
  constructor(
    @InjectRepository(User)
    private readonly usersRepository: Repository<User>,
  ) {}

  async signUp(email: string, password: string) {
    const existing = await this.usersRepository.findOne({
      where: { email },
    });

    if (existing) {
      throw new Error("User already exists");
    }

    const user = this.usersRepository.create({
      email,
      password,
    });

    await this.usersRepository.save(user);

    return {
      id: user.id,
      email: user.email,
    };
  }

  async signIn(email: string, password: string) {
    const user = await this.usersRepository.findOne({
      where: { email },
    });

    if (!user) {
      throw new UnauthorizedException("Invalid credentials");
    }

    if (user.password !== password) {
      throw new UnauthorizedException("Invalid credentials");
    }

    return {
      id: user.id,
      email: user.email,
    };
  }
}

Going through the service

import { Injectable, UnauthorizedException } from "@nestjs/common";
import { UsersService } from "../users/users.service";

@Injectable()
export class AuthService {
  constructor(private readonly usersService: UsersService) {}

  async signUp(email: string, password: string) {
    const existing = await this.usersService.findByEmail(email);

    if (existing) {
      throw new Error("User already exists");
    }

    const user = await this.usersService.create({
      email,
      password,
    });

    return {
      id: user.id,
      email: user.email,
    };
  }

  async signIn(email: string, password: string) {
    const user = await this.usersService.findByEmail(email);

    if (!user) {
      throw new UnauthorizedException("Invalid credentials");
    }

    if (user.password !== password) {
      throw new UnauthorizedException("Invalid credentials");
    }

    return {
      id: user.id,
      email: user.email,
    };
  }
}

At the current scale both approaches look equivalent, and that is the main trap: the right choice now is determined not by how the code looks at the moment of writing, but by what will happen to it in a year. So let's fast-forward right away — imagine about a year of active development has passed. The product found its audience, the user base grew, and along with them came the people who try to abuse registration. Marketing demands tracking traffic sources and running A/B tests on users. A multi-level referral system with bonuses and limits has appeared. The users module has grown its own endpoints and new fields — in short, everything that happens in any product right when it starts bringing in money.

Let's fix exactly what list of requirements AuthService now needs to adapt to:

A referral system with checks and limits: invitation caps, protection against self-referral, protection against repeated invitations of the same email
A more complex sign-up with anti-abuse checks — by IP, by deviceId, by the fact of repeated registration from the same device
An expanded users module — new fields (traffic source, deviceId, verification flags), separate endpoints, its own scenarios
Marketing requirements — sign-up analytics, A/B tests, traffic source attribution, event export to external systems

A note on transactions. In production, sign-up requires idempotency, race protection, and careful transactional boundaries. In the article's examples, all of this is deliberately omitted — the topic is decomposition, not transactionality. And to head off the question right away: "wrap everything in one big transaction" is not the right default either. A long transactional block with calls into external analytics, bonuses, and counter recalculations would hold rows locked for seconds and crash the database under load. Correct transactional boundaries are a separate task, beyond the scope of the article.

AuthService.signUp V2

async signUp(
  email: string,
  password: string,
  referralCode?: string,
  adSourceCode?: string,
  ip?: string,
  deviceId?: string,
): Promise<SignUpResponse> {
  const existingUserByEmail = await this.usersRepository.findOne({
    where: { email },
  });
  if (existingUserByEmail) {
    throw new BadRequestException("User already exists");
  }

  const registrationsFromIp = await this.usersRepository.count({
    where: { registrationIp: ip },
  });
  if (registrationsFromIp > 5) {
    throw new BadRequestException("Too many registrations from this IP");
  }

  const existingUserByDevice = await this.usersRepository.findOne({
    where: { deviceId },
  });
  if (existingUserByDevice) {
    throw new BadRequestException("Device already used");
  }

  const adSource = adSourceCode
    ? await this.adSourceRepository.findOne({ where: { code: adSourceCode } })
    : null;
  if (adSourceCode && !adSource) {
    throw new BadRequestException("Invalid ad source");
  }

  if (adSource) {
    const experimentGroup = Math.random() > 0.5 ? "A" : "B";

    await this.adSourceRepository.increment(
      { id: adSource.id },
      "registrationsCount",
      1,
    );

    await this.analyticsRepository.save({
      type: "experiment_assignment",
      group: experimentGroup,
      source: adSource.code,
    });
  }

  const referral = referralCode
    ? await this.referralsRepository.findOne({
        where: { code: referralCode },
        relations: ["owner"],
      })
    : null;
  if (referralCode && !referral) {
    throw new BadRequestException("Invalid referral code");
  }

  const referredByUser = referral?.owner ?? null;

  if (referredByUser) {
    const referralsByOwnerCount = await this.referralsRepository.count({
      where: { owner: { id: referredByUser.id } },
    });
    if (referralsByOwnerCount > 10) {
      throw new BadRequestException("Referral limit exceeded");
    }

    const existingReferralForEmail = await this.referralsRepository.findOne({
      where: {
        owner: { id: referredByUser.id },
        invitedUser: { email },
      },
      relations: ["invitedUser"],
    });
    if (existingReferralForEmail) {
      throw new BadRequestException("Referral abuse detected");
    }

    if (referredByUser.email === email) {
      throw new BadRequestException("Self-referral not allowed");
    }
  }

  const newUser = this.usersRepository.create({
    email,
    password,
    adSource,
    registrationIp: ip,
    deviceId,
    isVerified: false,
  });
  await this.usersRepository.save(newUser);

  if (referredByUser) {
    await this.bonusRepository.save({
      userId: referredByUser.id,
      amount: 100,
      type: "referral_reward",
    });

    const parentReferral = await this.referralsRepository.findOne({
      where: { invitedUser: { id: referredByUser.id } },
      relations: ["owner"],
    });
    if (parentReferral) {
      await this.bonusRepository.save({
        userId: parentReferral.owner.id,
        amount: 50,
        type: "second_level_referral",
      });
    }

    await this.referralsRepository.save({
      owner: referredByUser,
      invitedUser: newUser,
    });
  }

  await this.analyticsRepository.save({
    type: "user_registered",
    userId: newUser.id,
    source: adSource?.code,
    ip,
  });

  return {
    id: newUser.id,
    email: newUser.email,
  };
}

At this point a defender of code like this will say: "So what? It works, the business scenario is covered end to end, one method honestly carries the registration from start to finish." And formally that's true. But if you look at what actually lives inside signUp, the picture is different: one function now simultaneously handles authentication, anti-fraud logic, marketing experiments, the referral mechanic, and analytics. It depends on five different repositories and four independent business domains. And that — not the line count — is the real problem. One more product quarter from now, any new feature — anti-bot, geo-targeting, email verification — will be stitched into the same spot, because "all the registration requirements live in signUp."

V2 went to prod and did what V1 couldn't. The referral program started bringing in traffic cheaper than paid ads, influencers noticed and started reaching out themselves. In the product and finance dashboards, the numbers came up green in the same quarter for the first time in a long while. The project is alive, the project is growing, the project is making money.

Product catches the wave and starts pushing: "guys, the market just opened, let's go faster, the competitors aren't sleeping." At this exact moment, someone on the team catches that wave personally too. He's putting it together in his head: the feature is big, visible, right before performance review; if he ships first and bug-free — he can walk into his manager and ask for the tech-lead grade, he can start going to business meetings, become that engineer the PM goes to first to ask, and only then writes the user story. The motivation is understandable, human — not bad, not good, just real.

The next batch of "we've been meaning to" lands on the table. A partner program with bloggers and streamers. Different monetization models — revenue share, bonuses, tiers. A more serious anti-fraud, with multiple scenarios and a scoring model. Extended analytics for marketing, product, and finance. Plus additional checks and limits for the referrals. Each point on its own is normal — the same logic, just a few more scenarios.

Our hero opens auth.service.ts and figures out the fastest path — everything in one service, no unnecessary refactoring, no review arguments, ship by Friday. And it's exactly this combination — product success, PM pressure, one engineer's personal motivation, and a Friday deadline — that, time after time, produces the same class of code. If you've worked in a product that went from MVP into growth, you've seen this scene at least once. Now you'll see it again — in detail.

Before looking at what eventually ends up in auth.service.ts, let's fix what's formally on the spec at this stage:

A partner program with bloggers and streamers — separate partner categories, verification, separate statuses and transitions between them
An expanded monetization model — revenue share, multi-level bonuses, partnership tiers, different accrual rules for different categories
A more complex anti-fraud — multiple scenarios (new user, referral, partner click), a scoring model, manual blocks
Extended analytics — separate data layers for marketing, product, and finance; event export to external systems
Additional checks and limits for referrals — limits by time, by user segment, by traffic source

Each item is an ordinary product request: nothing exotic, nothing architecturally provocative. And they're implemented like ordinary product requests.

AuthService.signUp V3

async signUp(
  email: string,
  password: string,
  referralCode?: string,
  adSourceCode?: string,
  ip?: string,
  deviceId?: string,
): Promise<SignUpResponse> {
  const existingUserByEmail = await this.usersRepository.findOne({
    where: { email },
  });
  if (existingUserByEmail) {
    throw new BadRequestException("User already exists");
  }

  const registrationsFromIp = await this.usersRepository.count({
    where: { registrationIp: ip },
  });
  if (registrationsFromIp > 5) {
    throw new BadRequestException("Too many registrations from this IP");
  }

  const existingUserByDevice = await this.usersRepository.findOne({
    where: { deviceId },
  });
  if (existingUserByDevice) {
    throw new BadRequestException("Device already used");
  }

  const fraudScore =
    (registrationsFromIp ?? 0) * 10 +
    (existingUserByDevice ? 50 : 0) +
    (ip?.startsWith("192.") ? 20 : 0);
  if (fraudScore > 70) {
    throw new BadRequestException("Fraud detected");
  }

  const adSource = adSourceCode
    ? await this.adSourceRepository.findOne({ where: { code: adSourceCode } })
    : null;
  if (adSourceCode && !adSource) {
    throw new BadRequestException("Invalid ad source");
  }

  if (adSource) {
    const experimentGroup = Math.random() > 0.5 ? "A" : "B";

    await this.adSourceRepository.increment(
      { id: adSource.id },
      "registrationsCount",
      1,
    );

    await this.analyticsRepository.save({
      type: "experiment_assignment",
      group: experimentGroup,
      source: adSource.code,
    });
  }

  const referral = referralCode
    ? await this.referralsRepository.findOne({
        where: { code: referralCode },
        relations: ["owner", "influencerPartner"],
      })
    : null;
  if (referralCode && !referral) {
    throw new BadRequestException("Invalid referral code");
  }

  const influencerPartner = referral?.influencerPartner ?? null;
  const referredByUser =
    referral && !influencerPartner ? referral.owner : null;

  let calculatedReward = 0;
  if (influencerPartner) {
    await this.partnerRepository.increment(
      { id: influencerPartner.id },
      "registrationsCount",
      1,
    );

    if (influencerPartner.type === "blogger") {
      const audienceSize = influencerPartner.audienceSize ?? 1000;
      const ctr = influencerPartner.ctr ?? 0.02;
      const engagementScore = audienceSize * ctr;

      calculatedReward =
        20 + engagementScore * 0.01 + (engagementScore > 1000 ? 50 : 0);

      if (engagementScore > 5000) {
        calculatedReward *= 1.5;
      }
    } else if (influencerPartner.type === "streamer") {
      const avgViewers = influencerPartner.avgViewers ?? 100;
      const streamHours = influencerPartner.streamHours ?? 2;
      const retentionFactor = Math.min(streamHours / 4, 1);

      calculatedReward =
        avgViewers * 0.5 * retentionFactor + (avgViewers > 1000 ? 100 : 0);

      if (streamHours > 6) {
        calculatedReward *= 1.2;
      }
    } else if (influencerPartner.type === "partner") {
      const revenueShare = influencerPartner.revenueShare ?? 0.1;
      const baseValue = influencerPartner.baseValue ?? 200;
      const tierMultiplier =
        influencerPartner.tier === "gold"
          ? 2
          : influencerPartner.tier === "silver"
            ? 1.5
            : 1;

      calculatedReward = baseValue * revenueShare * tierMultiplier;

      if (influencerPartner.kpiAchieved) {
        calculatedReward += 300;
      }
    }

    await this.analyticsRepository.save({
      type: "marketing_conversion",
      source: influencerPartner.type,
      reward: calculatedReward,
    });

    await this.analyticsRepository.save({
      type: "revenue_projection",
      expectedRevenue: calculatedReward * 10,
    });

    await this.analyticsRepository.save({
      type: "user_segment",
      segment:
        influencerPartner.type === "streamer" ? "gamers" : "general",
    });
  }

  if (referredByUser) {
    const referralsByOwnerCount = await this.referralsRepository.count({
      where: { owner: { id: referredByUser.id } },
    });
    if (referralsByOwnerCount > 10) {
      throw new BadRequestException("Referral limit exceeded");
    }

    const existingReferralForEmail = await this.referralsRepository.findOne({
      where: {
        owner: { id: referredByUser.id },
        invitedUser: { email },
      },
      relations: ["invitedUser"],
    });
    if (existingReferralForEmail) {
      throw new BadRequestException("Referral abuse detected");
    }

    if (referredByUser.email === email) {
      throw new BadRequestException("Self-referral not allowed");
    }
  }

  const newUser = this.usersRepository.create({
    email,
    password,
    adSource,
    registrationIp: ip,
    deviceId,
    isVerified: false,
  });
  await this.usersRepository.save(newUser);

  if (referredByUser) {
    await this.bonusRepository.save({
      userId: referredByUser.id,
      amount: 100,
      type: "referral_reward",
    });

    const parentReferral = await this.referralsRepository.findOne({
      where: { invitedUser: { id: referredByUser.id } },
      relations: ["owner"],
    });
    if (parentReferral) {
      await this.bonusRepository.save({
        userId: parentReferral.owner.id,
        amount: 50,
        type: "second_level_referral",
      });
    }

    await this.referralsRepository.save({
      owner: referredByUser,
      invitedUser: newUser,
    });
  }

  if (influencerPartner) {
    const partnerOwner = await this.usersRepository.findOne({
      where: { id: influencerPartner.ownerUserId },
    });
    if (partnerOwner) {
      await this.bonusRepository.save({
        userId: partnerOwner.id,
        amount: calculatedReward,
        type: "influencer_reward",
      });

      await this.analyticsRepository.save({
        type: "influencer_reward_paid",
        partnerId: influencerPartner.id,
        amount: calculatedReward,
      });
    }
  }

  await this.analyticsRepository.save({
    type: "user_registered",
    userId: newUser.id,
    source: adSource?.code,
    ip,
  });

  return {
    id: newUser.id,
    email: newUser.email,
  };
}

This is a case in which no separate argument is needed to recognize the code's quality as unsatisfactory — the structural problems are visible to the naked eye. Two hundred lines in one function, six parameters at the input, three branches of referral logic, three reward models for partners; behind each conditional line is a separate business scenario, and no developer apart from the author is capable of holding all of them in their head together. It's worth emphasizing that this code deliberately omits transactionality, idempotency, invariant validation, unified error handling, and consistent response codes: their addition would make the example unreadable, and the situation only more characteristic.

At this point the reader naturally thinks: "Fine, the cause is clear — AuthService is holding the logic of several independent domains in one method. So we need to set up UsersService, ReferralsService, MarketingService, FraudService, PartnerService, and split all the signUp logic across them by the principle one service — one domain; AuthService will remain only an orchestrator." This answer is the standard NestJS-community recommendation and literally the first piece of advice on any review of code like this. It sounds right, looks right, and in the moment really does deliver visible improvement.

Only it doesn't solve the problem. And in the next part we'll walk through this kind of refactoring step by step and see why "split into services properly" isn't simply moving calls from one place to another, and why any project that has no architectural rule behind "decomposition into services" will end up, a year later, in exactly the same place — only with a different set of file names.

DEV Community: Victor Shkirov

Feature Based Clean Architecture. Part 5: Scaling FBCA and a Graph-Theoretic Analysis of Dependencies

Can this be proven mathematically?

1. The DAG invariant

What this means in practice (and where forwardRef fits in)

2. The coupling bound

3. The cost of change

Under what conditions this holds

Feature Based Clean Architecture. Part 4: FBCA: Formalizing Responsibility Boundaries in a NestJS Module

The basic idea

Domain / Use Case / Infrastructure / Presentation

The old project structure

Previously the internal module was structured like this

How will we introduce Clean Architecture?

How the internal module will be structured now

Let's also start with auth

Bad usage

The right approach

Feature Based Clean Architecture. Part 3: The Architectural Risk of Cycles in NestJS: ROI of Decisions on a Five-Year Horizon

Case: private accounts and follows

And now the same thing in code

And now — the moment forwardRef starts taking revenge

Feature Based Clean Architecture. Part 2: Decomposition into Services: An Analysis of the Approach's Limits

AuthService.signUp V4

AuthService.signUp V5

The Users module's evolution

UsersService V1

UsersService V2

Feature Based Clean Architecture. Part 1: How a NestJS Application Evolves Into an Unmaintainable State

Going through the service

AuthService.signUp V2

AuthService.signUp V3

What this means in practice (and where `forwardRef` fits in)

And now — the moment `forwardRef` starts taking revenge