Forem: Francisco López

Clean Architecture in NestJS — Enforcing the Controller-Service-Repository Pattern with Static Analysis

Francisco López — Wed, 08 Apr 2026 01:29:04 +0000

A beginner-friendly guide to layered architecture and how to make sure your team actually follows it

When I started working with NestJS, one of the things that attracted me the most was how opinionated the framework felt. Modules, controllers, services, dependency injection — it gives you a clear structure from day one. But after working on a few projects, I slowly realized something: NestJS gives you the tools for clean architecture, but it won't stop you from breaking it.

I remember one project where a junior dev on my team was tasked with adding a "deactivate user" feature. Simple enough. But instead of going through the service layer, they injected PrismaService directly into the controller, wrote a database query, added an if/else to check permissions, and sent an email — all inside a @Patch() handler. It worked. The tests passed. The PR got merged because the reviewer was in a rush.

That's when I started thinking about enforcing architecture, not just documenting it.

[TL;DR] If you already know what layered architecture is and just want to enforce it, you can jump right to "Enforcing It" section.

Before we move forward, I wanted to set some expectations. This article won't be an academic deep dive into hexagonal architecture or clean architecture as defined by Uncle Bob. I will be focusing this writing on a practical pattern that works well for most NestJS projects — the Controller-Service-Repository pattern — and how to enforce it automatically using nestjs-doctor. Having said that, let's jump right into it.

The Three Layers

A useful way to think of this is like a restaurant.

The Controller is the waiter. It takes your order (HTTP request), brings it to the kitchen, and delivers the food back (HTTP response). The waiter doesn't cook. The waiter doesn't go to the market to buy ingredients. The waiter just communicates.
The Service is the chef. It receives the order, decides what to do, applies the recipe (business logic), and prepares the dish. The chef doesn't talk to customers directly. The chef doesn't go to the warehouse to grab ingredients — they ask someone else.
The Repository is the warehouse manager. It knows where everything is stored, how to fetch ingredients (data), and how to put them back. It deals with storage (the database) so nobody else has to.

In code, it looks like this:

Request  →  Controller  →  Service  →  Repository  →  Database
Response ←  Controller  ←  Service  ←  Repository  ←  Database

Each layer only talks to the one directly below it. The controller calls the service. The service calls the repository. The repository talks to the database. Never the other way around, never skipping layers.

Let's see what each one looks like in NestJS.

The Controller

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

  @Get()
  findAll() {
    return this.usersService.findAll();
  }

  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

Notice how thin this is. No database queries. No if/else logic. No email sending. The controller receives the request, delegates to the service, and returns the response. That's it.

The Service — Business Logic

@Injectable()
export class UsersService {
  constructor(private readonly usersRepository: UsersRepository) {}

  async findAll() {
    return this.usersRepository.findMany();
  }

  async create(dto: CreateUserDto) {
    const existing = await this.usersRepository.findByEmail(dto.email);
    if (existing) {
      throw new ConflictException('Email already in use');
    }
    return this.usersRepository.create(dto);
  }
}

The service contains the business rules "if the email already exists, throw an error." It doesn't know about HTTP status codes (that's ConflictException's job). It doesn't know about SQL or Prisma or Mongo — it calls the repository.

The Repository

@Injectable()
export class UsersRepository {
  constructor(private readonly prisma: PrismaService) {}

  async findMany() {
    return this.prisma.user.findMany();
  }

  async findByEmail(email: string) {
    return this.prisma.user.findFirst({ where: { email } });
  }

  async create(data: CreateUserDto) {
    return this.prisma.user.create({ data });
  }
}

The repository is the only layer that knows about the database. If you switch from Prisma to TypeORM tomorrow, you only change this file. The service and controller don't care.

What Goes Wrong When You Break the Layers

Let me show you the common mistakes I see, especially from devs who are new to NestJS.

Mistake 1: ORM in the Controller

// BAD — The waiter is cooking!
@Controller('users')
export class UsersController {
  constructor(private readonly prisma: PrismaService) {}

  @Get()
  findAll() {
    return this.prisma.user.findMany();
  }
}

Why is this bad? Because now your controller knows about Prisma, about your database schema, about how data is stored. If you need that same query in a background job or a WebSocket handler, you can't reuse it it's trapped in an HTTP endpoint.

Mistake 2: Business Logic in the Controller

// BAD — The waiter is deciding the recipe!
@Controller('orders')
export class OrdersController {
  @Post()
  async create(@Body() dto: CreateOrderDto) {
    const items = await this.prisma.product.findMany({
      where: { id: { in: dto.productIds } },
    });

    let total = 0;
    for (const item of items) {
      if (item.stock <= 0) {
        throw new BadRequestException(`${item.name} is out of stock`);
      }
      total += item.price * dto.quantities[item.id];
    }

    if (total > 10000) {
      // send approval email
      await this.mailer.send(dto.managerEmail, 'Approval needed', ...);
    }

    return this.prisma.order.create({ data: { total, items: ... } });
  }
}

This handler is doing everything — fetching products, checking stock, calculating totals, sending emails, creating the order. Long story short, it's a mess. You can't test the business logic without making HTTP requests. You can't reuse the stock check from another part of your app.

Mistake 3: Repository in the Controller

// BAD — The waiter is going to the warehouse!
@Controller('users')
export class UsersController {
  constructor(private readonly usersRepository: UsersRepository) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersRepository.findById(id);
  }
}

This one is more subtle. You have a proper repository, which is good! But the controller is calling it directly, skipping the service layer. Today it's a simple find-by-id, but tomorrow someone adds authorization logic directly in the controller because "there's no service to put it in."

Enforcing It

Knowing the pattern is one thing. Making sure your entire team follows it — especially under deadline pressure — is another. This is where nestjs-doctor comes in.

Install and Run

npm install --save-dev nestjs-doctor
npx nestjs-doctor

You'll see something like this:

  82 / 100  Good

  ✗ Controller 'OrdersController' injects ORM service 'PrismaService' directly. (2)
    Inject a service that wraps the ORM instead of using it in controllers.

  ✗ Controller 'OrdersController' contains business logic: found loop and 3 branches. (1)
    Extract branches, loops, and complex calculations into a service method.

  ⚠ Constructor parameter 'prismaService' should be readonly. (5)
    Add the 'readonly' modifier to the constructor parameter.

Custom Rules

A custom rule is a .ts file with two parts: meta (what the rule is) and check (what it detects). Let's create one.

Example: Services Must End With "Service"

Maybe your team requires consistent naming — all @Injectable() classes in the service layer should end with Service.

// nestjs-doctor-rules/require-service-suffix.ts

export const requireServiceSuffix = {
  meta: {
    id: "require-service-suffix",
    description: "Injectable classes that are not repositories must end with 'Service'",
    help: "Rename the class to end with 'Service' (e.g., UsersService).",
    category: "architecture",
    severity: "warning",
  },

  check(context) {
    for (const cls of context.sourceFile.getClasses()) {
      if (!cls.getDecorator("Injectable")) continue;

      const name = cls.getName() ?? "";

      // Skip repositories, guards, pipes, filters, interceptors
      if (/Repository|Repo|Guard|Pipe|Filter|Interceptor|Gateway|Resolver/.test(name)) continue;

      if (!name.endsWith("Service")) {
        context.report({
          filePath: context.filePath,
          message: `Injectable '${name}' should end with 'Service'.`,
          line: cls.getStartLineNumber(),
          column: 1,
        });
      }
    }
  },
};

Example: Repositories Must Not Import Other Repositories

In a clean architecture, repositories are independent data access objects. They shouldn't depend on each other — that kind of orchestration belongs in the service layer.

// nestjs-doctor-rules/no-cross-repository-imports.ts

export const noCrossRepositoryImports = {
  meta: {
    id: "no-cross-repository-imports",
    description: "Repositories must not inject other repositories",
    help: "Move the cross-repository logic to a service that orchestrates both.",
    category: "architecture",
    severity: "error",
  },

  check(context) {
    for (const cls of context.sourceFile.getClasses()) {
      const name = cls.getName() ?? "";
      if (!name.endsWith("Repository") && !name.endsWith("Repo")) continue;

      const ctor = cls.getConstructors()[0];
      if (!ctor) continue;

      for (const param of ctor.getParameters()) {
        const typeName = param.getTypeNode()?.getText() ?? "";
        if (typeName.endsWith("Repository") || typeName.endsWith("Repo")) {
          context.report({
            filePath: context.filePath,
            message: `Repository '${name}' injects '${typeName}' — repositories should not depend on each other.`,
            line: param.getStartLineNumber(),
            column: 1,
          });
        }
      }
    }
  },
};

Example: Flag God Services (Too Many Dependencies)

A service with 10 dependencies is probably doing too much. This rule uses project scope to access the full provider map:

// nestjs-doctor-rules/no-god-services.ts

export const noGodServices = {
  meta: {
    id: "no-god-services",
    description: "Services with too many dependencies should be split",
    help: "Extract related dependencies into smaller, focused services.",
    category: "architecture",
    severity: "warning",
    scope: "project",
  },

  check(context) {
    const MAX = 8;
    for (const [name, provider] of context.providers) {
      if (provider.dependencies.length > MAX) {
        context.report({
          filePath: provider.filePath,
          message: `'${name}' has ${provider.dependencies.length} dependencies (max ${MAX}).`,
          line: provider.classDeclaration.getStartLineNumber(),
          column: 1,
        });
      }
    }
  },
};

Wiring Custom Rules

Tell nestjs-doctor where to find them. In your nestjs-doctor.config.json:

{
  "customRulesDir": "./nestjs-doctor-rules"
}

Run again and your rules show up with a custom/ prefix:

⚠ Injectable 'UserHelper' should end with 'Service'. (1)
✗ Repository 'OrdersRepository' injects 'UsersRepository'. (1)

The Shortcut — Let AI Write the Rules For You

I know what you might be thinking — "I don't want to learn the ts-morph AST API just to write a linting rule." Fair enough. Here's the thing: you don't have to.

If you use an AI coding agent — Claude Code, Cursor, Windsurf, Codex, Gemini CLI, or others — you can install a skill that generates custom rules from plain English:

npx nestjs-doctor --init

This installs two skills into your agent. The one we care about is /nestjs-doctor-create-rule. Now just describe what you want:

/nestjs-doctor-create-rule repositories must not inject other repositories

The agent will assess feasibility, generate the rule file, create the directory, update your config, and verify it loads. All from a single prompt.

Here are some more prompts you can try:

/nestjs-doctor-create-rule every controller must have @ApiTags for swagger docs

/nestjs-doctor-create-rule services should not have more than 8 constructor dependencies

/nestjs-doctor-create-rule ban imports from "moment" — suggest dayjs instead

/nestjs-doctor-create-rule POST and PUT handlers must use @UsePipes(ValidationPipe)

/nestjs-doctor-create-rule flag injectable classes that don't follow the naming convention

The skill knows the full custom rule API — what fields meta needs, how context.sourceFile works, when to use scope: "project" for cross-file analysis, and all the validation requirements. It handles the boilerplate so you focus on what to enforce, not how to traverse an AST.

Adding It to CI

Once your rules are in place — both built-in and custom — add nestjs-doctor to your CI pipeline:

npx nestjs-doctor --min-score 85

The --min-score flag makes the command exit with a non-zero code if the health score drops below 85. PRs that break the architecture get blocked before they're merged. No more "I'll fix it later."

Sum Up

The Controller-Service-Repository pattern is simple to understand but hard to maintain across a team. Let's recap:

Controllers are waiters — they take orders and deliver responses. No cooking (business logic), no warehouse trips (database queries).
Services are chefs — they apply the recipes (business rules). They don't talk to customers (HTTP) or manage storage (database) directly.
Repositories are warehouse managers — they handle data storage. They don't depend on each other.
nestjs-doctor enforces these layers automatically with built-in rules for the common violations.
Custom rules let you encode your team's specific conventions — naming, dependency limits, import restrictions — in code that runs on every scan.
AI skills let you generate those custom rules from plain-English prompts, so you don't need to learn the AST API.

There is no silver bullet, but having automated checks that block architectural violations in CI is the closest thing. Architecture decisions that live only in documentation will be violated. Architecture decisions enforced by tooling won't.

Resources

[Implementation] https://github.com/RoloBits/nestjs-doctor
[Docs] Custom Rules: https://nestjs.doctor/docs/custom-rules

Your Phone Already Has the Hardware to Prove a Photo Is Real. Nothing Uses It.

Francisco López — Mon, 16 Feb 2026 18:22:01 +0000

Your Phone Already Has the Hardware to Prove a Photo Is Real. Nothing Uses It.

#opensource #mobile #security #reactnative

The Problem Is Already Here

In 2025 Adobe's Content Authenticity Initiative reported that 97% of organizations have encountered AI-generated content being used against them. Deepfakes, synthetic product photos, fabricated evidence.

Meanwhile every phone in your pocket has a tamper-resistant cryptographic chip sitting idle. Secure Enclave on iOS. StrongBox or TEE on Android. Hardware designed to sign things in a way that can't be extracted or faked.

Nobody is connecting these two facts.

C2PA: The Standard Nobody Talks About

C2PA is an open standard from Adobe, Microsoft, Intel and others. It works like HTTPS but for media files. A cryptographic manifest gets embedded directly into the JPEG containing:

What device captured it
When and where
Every edit made after capture
A signature that breaks if a single pixel changes

Leica, Sony and Nikon already ship C2PA in some cameras. But on mobile, where 90%+ of photos are taken? Almost nothing.

Enter `attestation-photo-mobile`

I built attestation-photo-mobile to close that gap.

It's a React Native package. You bring your own camera lib, take a photo, and pass the path. The package does the rest: hashes the image, signs it with hardware-backed keys, and embeds a full C2PA manifest before the file ever touches disk.

How It Works

The architecture has three layers:

Native layer (Swift/Kotlin): Handles hardware keystore access. Provisions an ECDSA P-256 key inside Secure Enclave or StrongBox. This key never leaves the hardware.
Rust layer (c2pa-rs): Builds the JUMBF manifest, computes the asset hash, constructs the C2PA claim. I tried doing this in pure JS first. Don't.
React Native bridge: Exposes a single signPhoto(path) function and a useAttestedCapture hook that handles key provisioning, location prefetch, and error wrapping.

Usage

import { useAttestedCapture, saveToGallery } from '@rolobits/attestation-photo-mobile';

function CaptureScreen() {
  const { signPhoto, isReady } = useAttestedCapture({
    includeLocation: true,
    appName: "My App",
    nonce: "server-challenge-token",
  });

  const onCapture = async (photoPath) => {
    // Sign and embed C2PA manifest
    const signed = await signPhoto(photoPath);

    // signed.trustLevel -> "secure_enclave" | "strongbox" | "tee"
    // signed.embeddedManifest -> true
    // signed.signature -> SHA-256 hex of original asset

    await saveToGallery({ filePath: signed.path });
  };
}

The output JPEG can be verified with any C2PA tool. Upload it to verify.contentauthenticity.org or run:

cargo install c2patool
c2patool verify output.jpg

What Gets Blocked

The SDK runs device integrity checks before signing. Jailbroken or rooted devices get E_COMPROMISED_DEVICE. No Secure Enclave or StrongBox? E_NO_TRUSTED_HARDWARE. You can control this with requireTrustedHardware: true|false.

Where This Actually Matters

This isn't a solution looking for a problem. These are scenarios where someone has a financial incentive to submit fake photos:

Insurance claims: Snap damage photos in-app. Each one is hardware-signed with device, location, timestamp. The adjuster's backend verifies the manifest automatically.
Marketplace listings: Verified photos for cars, real estate, rentals. Buyers know the images aren't AI-generated or recycled from 2019.
Field inspections: Construction sites, equipment audits. Timestamped proof of conditions for compliance.
KYC: Selfie-based identity verification where the photo is provably from a real device, not a generated face fed through a virtual camera.

This is a v1. Here's what's missing:

Self-signed certificates. The signing key has no CA chain. Verifiers will show a valid signature but "unknown signer." This means tamper detection works today but attribution doesn't. CA integration is the next priority.

👉 GitHub: RoloBits/attestation-photo-mobile

Stop Using CAPTCHA. Start Measuring Entropy.

Francisco López — Mon, 09 Feb 2026 00:26:05 +0000

Stop Using CAPTCHA. Start Measuring Entropy.

In late 2024, researchers at ETH Zurich quietly published an obituary for the web as we know it. They didn't call it that, of course. They called it "Breaking reCAPTCHAv2."

Their findings were stark: modern AI models (specifically YOLO-based vision models) can now solve Google's image CAPTCHAs with 100% accuracy.

Read that again. 100%.

The Turing Test hasn't just been passed; it’s been automated, containerized, and scaled. The "I am not a robot" checkbox is now effectively a "Welcome" mat for bots.

According to the 2025 Imperva Bad Bot Report, automated traffic has officially surpassed human traffic, accounting for 51% of all internet activity. We are effectively the minority on our own network.

If we want to save the web from becoming a "Dead Internet" of bots talking to bots, we need to stop asking users to identify traffic lights and start listening to their heartbeat.

The Hypothesis: Identity vs. Humanity

The current knee-jerk reaction is "Proof of Personhood" (scanning your ID or face to use the web). I believe this is a dystopian overcorrection.

We don't need to know who you are (Identity). We just need to know what you are (Biology).

Identity is static data (Names, IDs).
Humanity is dynamic behavior (Reaction times, hesitation, errors).

Humans are messy. We are beautifully, consistently imperfect. When you type, you don't hit keys at a perfect 150ms interval. You "rollover" keys. You pause to think. You speed up on common bigrams like "th" or "er."

This is your Keystroke Dynamics signature. It is a behavioral biometric that is incredibly hard for bots to fake convincingly without slowing them down to useless human speeds.

Enter `isHumanCadence`

I built isHumanCadence as a Proof of Concept (PoC) to test this hypothesis.

It is a lightweight, privacy-focused library that analyzes the timing of keystrokes—not the content. It runs entirely in the browser, sends no data to a server, and doesn't know what you typed, only how you typed it.

How It Works (The Technical Deep Dive)

Bots are deterministic. Even when programmed with Math.random() delays, they tend to follow a uniform or Gaussian distribution that is statistically "too clean."

isHumanCadence measures four primary biological constraints:

Dwell Time: The duration a key is physically depressed. Humans rarely tap keys for exactly 50ms every time.
Flight Time: The time between releasing one key and pressing the next.
Rollover Rate: The overlap where Key B is pressed before Key A is released. This is a high-signal human trait; simple bots often type strictly sequentially (Key A down -> Key A up -> Key B down).
Entropy: The statistical variance of the timing deltas.

The "Secret Sauce": Hysteresis

One major challenge with heuristic analysis is "flickering." A user might type one word rhythmically (High Human Score) and then pause abruptly to think (Score drops). You don't want the UI to flash "BOT DETECTED" instantly.

I implemented a Schmitt Trigger (Hysteresis) to stabilize the classification. We use different thresholds for entering and exiting states:

To become Human: Score must exceed 0.70.
To drop to Unknown: Score must fall below 0.60.
To become Bot: Score must fall below 0.35.

This creates a "dead zone" where the state remains stable, preventing false positives during natural cognitive pauses.

Implementation

The library attaches non-intrusive listeners to the target input field. It uses performance.now() for sub-millisecond precision.

1. Install the package:

npm install @rolobits/is-human-cadence

2. Attach it to an input:

import { createCadence } from '@rolobits/is-human-cadence';

// Select any textarea or input on your page
// We use a broad selector here to ensure we find *something*
const input = document.querySelector('textarea, input');

if (input) {
  const cadence = createCadence(input, {
    // Wait for 20 keystrokes before making a confident judgment
    minSamples: 20, 

    onScore: (result) => {
      console.log(`Score: ${result.score}`); // 0.0 (Bot) -> 1.0 (Human)
      console.log(`Status: ${result.classification}`); // 'bot' | 'human' | 'unknown'
    }
  });

  // Start listening
  cadence.start();
  console.log("isHumanCadence: Listening for keystrokes...");
} else {
  console.warn("isHumanCadence: No input element found on this page.");
}

The Reality Check: A Proof of Concept

Right now, this library detects standard scripts and even sophisticated bots using randomized delays. But "Generative Keystrokes" are the next frontier. Eventually, AI agents will be trained on massive datasets of human typing patterns to spoof these very metrics. They will learn to "stumble" on purpose.

Furthermore, client-side security is inherently trustless. If the browser can measure it, a determined attacker can eventually spoof the environment to fake it.

This package is not a silver bullet. It is a conversation starter.

Join

The web is drowning in AI noise. If we want to keep a space for human connection, we need to build filters that recognize us not by our passwords, but by our rhythm.

👉 GitHub: RoloBits/isHumanCadence

Forem: Francisco López

Clean Architecture in NestJS — Enforcing the Controller-Service-Repository Pattern with Static Analysis

The Three Layers

The Controller

The Service — Business Logic

The Repository

What Goes Wrong When You Break the Layers

Mistake 1: ORM in the Controller

Mistake 2: Business Logic in the Controller

Mistake 3: Repository in the Controller

Enforcing It

Install and Run

Custom Rules

Example: Services Must End With "Service"

Example: Repositories Must Not Import Other Repositories

Example: Flag God Services (Too Many Dependencies)

Wiring Custom Rules

The Shortcut — Let AI Write the Rules For You

Adding It to CI

Sum Up

Resources

Your Phone Already Has the Hardware to Prove a Photo Is Real. Nothing Uses It.

Your Phone Already Has the Hardware to Prove a Photo Is Real. Nothing Uses It.

The Problem Is Already Here

C2PA: The Standard Nobody Talks About

Enter attestation-photo-mobile

How It Works

Usage

What Gets Blocked

Where This Actually Matters

Stop Using CAPTCHA. Start Measuring Entropy.

Stop Using CAPTCHA. Start Measuring Entropy.

The Hypothesis: Identity vs. Humanity

Enter isHumanCadence

How It Works (The Technical Deep Dive)

The "Secret Sauce": Hysteresis

Implementation

The Reality Check: A Proof of Concept

Join

Enter `attestation-photo-mobile`

Enter `isHumanCadence`