• Share this post & I’ll send you some rewards for the referrals.

In the Java/C# world, DI containers are a religion.

In Node.js, most developers just import modules directly, until testing becomes a nightmare and swapping implementations means rewriting half the app.

You don’t need dependency injection containers like InversifyJS or tsyringe.

Here’s how to do dependency injection with plain TypeScript, and why it’ll make your code instantly more testable.

Dependency Injection vs. Dependency Inversion

These terms get used interchangeably. But they're not the same.

Dependency Injection (DI) is a technique: instead of a class/function creating its own dependencies, you pass them in from the outside.

Dependency Inversion is a principle (the “D” in SOLID): high-level modules shouldn’t depend on low-level modules. Both should depend on abstractions.

Dependency Injection is how you implement Dependency Inversion.

But you can do DI without inverting anything. This is the place where most Node.js developers stop.

// Direct dependency — no injection
import { db } from './database';

export async function getUser(id: string) {
  return db.query('SELECT * FROM users WHERE id = $1', [id]);
}

This works. But you can’t test getUser without a real database.

You can’t swap PostgreSQL for an in-memory store.

And if database.ts has side effects on import, every test file that touches getUser pays that cost.

The Node.js Anti-Pattern: Import Everything Directly

Here’s what most Express apps look like:

// userService.ts
import { knex } from ‘../lib/database’;
import { sendEmail } from ‘../lib/email’;
import { logger } from ‘../lib/logger’;

export async function createUser(data: CreateUserInput) {
  const [user] = await knex(’users’).insert(data).returning(’*’);
  await sendEmail(user.email, ‘Welcome!’);
  logger.info(`User created: ${user.id}`);
  return user;
}

There are three hardcoded dependencies. And to test this function, you need:

• A running database (or mock Knex globally)

• An email service (or mock the module)

• A logger (or suppress output)

Module mocking (jest.mock, vi.mock) is the usual escape hatch, but it’s brittle because we’re mocking import paths, not the actual contracts.

For example, if you rename a file, your mocks break silently.

Module mocking is a code smell.

It tells you your code has hidden dependencies that should be explicit.

What Dependency Injection Actually Solves

Before we continue further, let’s be clear about what we’re fixing:

• Testability. When a module imports its dependencies directly, you’re forced into module-level mocking (jest.mock(), vi.mock()) to test it. These mocks are fragile, magical, and break when you rename a file. With DI, you pass plain objects, and no mocking framework is needed.

• Swappability. Imagine you have to switch from Knex to Drizzle, or from SendGrid to AWS SES. When dependencies are injected, you swap the implementation in one place. When they’re imported, you touch every file.

• Explicit dependencies. A function’s signature should tell you what it needs. If createUser secretly depends on a database, an email client, and a logger, but its signature only shows data: CreateUserDTO, that’s a lie. DI makes dependencies visible.

• Separation of concerns. Your business logic shouldn’t know (or care) whether it’s talking to Postgres or SQLite, SendGrid or a local SMTP server. DI enforces that boundary naturally.

Now, let’s see how to do dependency injection in Node.js without any frameworks.

Step 1: Constructor Injection (Manual DI)

The simplest fix: accept dependencies as parameters.

// userService.ts
interface UserRepository {
  create(data: CreateUserInput): Promise<User>;
}

interface EmailService {
  send(to: string, subject: string): Promise<void>;
}

interface Logger {
  info(message: string): void;
}

export function createUserService(
  repo: UserRepository,
  email: EmailService,
  logger: Logger
) {
  return {
    async createUser(data: CreateUserInput) {
      const user = await repo.create(data);
      await email.send(user.email, ‘Welcome!’);
      logger.info(`User created: ${user.id}`);
      return user;
    },
  };
}

Before and After DI: How You Use the Code

The real difference isn’t just how the service is defined, but how it’s consumed.

Before DI, we use direct imports (hidden dependencies):

// Somewhere in your route handler or controller
import { createUser } from ‘./userService’;

// Just call it. What does it need? Who knows.
// Knex? Email service? Logger? You can’t tell from here.
const user = await createUser({ email: ‘alice@example.com’, name: ‘Alice’ });

Dependencies are invisible.

The function looks simple, but it’s secretly reaching into the module graph for a database client, an email service, and a logger.

You only discover this when something breaks or when you try to test it.

After DI, we use Factory + DI (explicit dependencies):

// In your composition root or setup code
import { createUserService } from ‘./userService’;
import { createUserRepo } from ‘./repos/userRepo’;
import { createEmailService } from ‘./infra/email’;
import { createLogger } from ‘./infra/logger’;

// Dependencies are explicit at creation time
const userService = createUserService(
  createUserRepo(knex),
  createEmailService({ apiKey: process.env.SENDGRID_KEY! }),
  createLogger({ level: ‘info’ })
);

// Now use it — the service is fully configured
const user = await userService.createUser({ email: ‘alice@example.com’, name: ‘Alice’ });

Yes, the setup is more verbose. But now you can see every dependency. The function signature tells the truth.

When you read the composition root, you know exactly what each service needs, no grepping through imports, no surprises.

Step 2: The Composition Root

If every service takes its dependencies as arguments, where do you actually wire everything together?

At the composition root, the entry point of your application. This is the one place that knows about all the concrete implementations.

// composition-root.ts
import Knex from ‘knex’;
import { createKnexDatabase } from ‘./infra/knexDatabase’;
import { createUserService } from ‘./services/userService’;
import { createOrderService } from ‘./services/orderService’;
import { createEmailService } from ‘./infra/email’;
import { createLogger } from ‘./infra/logger’;

export function createApp() {
  // Infrastructure
  const knex = Knex({
    client: ‘pg’,
    connection: process.env.DATABASE_URL,
  });
  const db = createKnexDatabase(knex);
  const email = createEmailService({ apiKey: process.env.SENDGRID_KEY! });
  const logger = createLogger({ level: ‘info’ });

  // Repositories
  const userRepo = createUserRepo(db);
  const orderRepo = createOrderRepo(db);

  // Services
  const userService = createUserService(userRepo, email, logger);
  const orderService = createOrderService(orderRepo, userService, logger);

  return { userService, orderService, knex };
}

// server.ts
import express from ‘express’;
import { createApp } from ‘./composition-root’;

const app = express();
const { userService, orderService } = createApp();

app.post(’/users’, async (req, res) => {
  const user = await userService.createUser(req.body);
  res.status(201).json(user);
});

Everything flows downward from one place. No global singletons. No magical auto-wiring. Just functions calling functions.

When to Reach for a Container?

Manual DI works beautifully for small-to-medium apps.

But when you have 20-30+ services with complex dependency graphs, the composition root becomes hard to read and follow.

I’ve personally used tsyringe. It’s a lightweight container, easy to use and configure.

tsyringe uses decorators and reflect-metadata to inspect constructor parameters and auto-wire dependencies.

It supports singleton, transient, and scoped lifecycles, with strong TypeScript support.

To be honest, I didn’t have any trouble with it.

Here is a simple example:

import ‘reflect-metadata’;
import { container, injectable, inject, singleton } from ‘tsyringe’;
import Knex from ‘knex’;

@singleton()
class KnexDatabase implements Database {
  private knex = Knex({ client: ‘pg’, connection: process.env.DATABASE_URL });

  users = {
    create: async (data: CreateUserInput) => {
      const [user] = await this.knex(’users’).insert(data).returning(’*’);
      return user;
    },
    findById: async (id: string) => {
      return this.knex(’users’).where({ id }).first() ?? null;
    },
  };
}

container.register(’Database’, { useClass: KnexDatabase });

@injectable()
class UserService {
  constructor(@inject(’Database’) private db: Database) {}

  async createUser(data: CreateUserInput) {
    return this.db.users.create(data);
  }
}

// Resolve with all dependencies auto-wired
const userService = container.resolve(UserService);

If you’re not sure whether you need a container, start simple without an additional framework.

You can easily add it later if needed.

The Testing Payoff

Here’s why all this matters. Let’s compare full test files side by side.

Before: Testing with Module Mocking

import { describe, it, expect, vi, beforeEach } from ‘vitest’;

// Mock every dependency by file path — get any path wrong and it silently breaks
vi.mock(’../lib/database’, () => ({
  knex: vi.fn().mockReturnValue({
    insert: vi.fn().mockReturnValue({
      returning: vi.fn().mockResolvedValue([{ id: ‘1’, email: ‘test@example.com’ }]),
    }),
  }),
}));

vi.mock(’../lib/email’, () => ({
  sendEmail: vi.fn(),
}));

vi.mock(’../lib/logger’, () => ({
  logger: {
    info: vi.fn(),
  },
}));

// Now import the function AFTER the mocks (order matters!)
import { createUser } from ‘./userService’;
import { knex } from ‘../lib/database’;
import { sendEmail } from ‘../lib/email’;

describe(’createUser’, () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it(’creates a user and sends a welcome email’, async () => {
    const user = await createUser({ email: ‘test@example.com’, name: ‘Test’ });

    expect(user.id).toBe(’1’);
    expect(sendEmail).toHaveBeenCalledWith(’test@example.com’, ‘Welcome!’);
  });
});

Problems everywhere:

• Path-coupled: rename ../lib/database to ../db/database and the mock breaks silently — the test passes but uses the real module

• Import order matters: vi.mock calls are hoisted, but if you get it wrong, debugging is miserable

• Type-unsafe: you’re casting to any because the mock system doesn’t know your interfaces

• Framework-locked: switch from Vitest to Node’s built-in test runner? Rewrite every mock

After: Testing with DI

import { describe, it, expect } from ‘vitest’;
import { createUserService } from ‘./userService’;

describe(’createUser’, () => {
  it(’creates a user and sends a welcome email’, async () => {
    // Plain objects that satisfy the interface — no mock framework needed
    const fakeRepo = {
      create: async (data: any) => ({ id: ‘1’, email: data.email }),
    };
    const fakeEmail = {
      send: async () => {},
    };
    const fakeLogger = {
      info: () => {},
    };

    // Track calls manually if needed (or use vi.fn() — your choice, not a requirement)
    const emailCalls: any[] = [];
    fakeEmail.send = async (to: string, subject: string) => {
      emailCalls.push({ to, subject });
    };

    const service = createUserService(fakeRepo, fakeEmail, fakeLogger);
    const user = await service.createUser({ email: ‘test@example.com’, name: ‘Test’ });

    expect(user.id).toBe(’1’);
    expect(emailCalls).toEqual([{ to: ‘test@example.com’, subject: ‘Welcome!’ }]);
  });

  it(’logs user creation’, async () => {
    const logs: string[] = [];
    const service = createUserService(
      { create: async (data: any) => ({ id: ‘42’, email: data.email }) },
      { send: async () => {} },
      { info: (msg: string) => logs.push(msg) }
    );

    await service.createUser({ email: ‘test@example.com’, name: ‘Test’ });

    expect(logs).toEqual([’User created: 42’]);
  });
});

The difference:

• No mocking framework required: plain objects that match the interface

• Type-safe: TypeScript checks your fakes against the real interfaces

• No import order tricks: just functions and objects

• Portable: works with Vitest, Jest, Node’s test runner, or even a plain script

• Each test is self-contained: no shared mutable mock state leaks between tests

📌 Key Takeaways

1. Dependency Injection isn’t a framework feature — it’s passing arguments to functions. You already know how to do it.

2. Module mocking is a smell. If you need vi.mock() to test something, remember that something has hidden dependencies.

3. Start with manual DI. Factory functions + a composition root covers 90% of Node.js apps.

4. Graduate to a container (tsyringe) when your dependency graph gets complex. Not because it’s “proper”, but because it saves maintenance.

5. The real value is testability. DI makes unit testing trivial, integration testing focused, and your architecture honest about its dependencies.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

• Share this post & I’ll send you some rewards for the referrals.

Open most Node.js projects, and you see this:

src/
├── controllers/
├── services/
├── models/
├── middleware/
├── utils/
└── routes/

What does this app do?

You see that it’s an Express app. But that’s all the structure tells you.

Is it an e-commerce platform? A healthcare system? A social network?

You’d have to open files and read code to find out.

That’s the problem.

What Is Screaming Architecture?

Uncle Bob coined the term:

Your project structure should scream what the application does, not what framework it uses.

For example, a healthcare app should look like this:

src/
├── patients/
├── appointments/
├── prescriptions/
├── billing/
└── shared/

You open the folder and immediately know: this is a healthcare system.

The domain is front and center.

Express, REST, GraphQL, Prisma, React, those are implementation details, tucked inside each feature.

And this is not just about aesthetics.

When folders map to business capabilities, you get:

• Discoverability: New developers find code faster.

• Ownership: Teams own features, not layers.

• Change isolation: Modifying “appointments” doesn’t require touching 5 different layer folders.

• Deletion: You can remove an entire feature by deleting one folder.

• Low/High Coupling: Low coupling between features and High coupling for a single feature.

Or we could also look at it in another way to see more clearly how a single feature maps across different technical layers:

The Colocation Principle

In the React world, we must strive to:

Keep things as close as possible to where they're used.

Consider the following hierarchy:

1. If only one component uses it → put it in that component’s file

2. If only components in one folder use it → put it in that folder

3. If multiple folders use it → move it up to the nearest shared parent

4. If the whole app uses it → put it in shared/ or lib/

This is the same idea as screaming architecture, applied at a granular level.

Don't prematurely extract.

Don't create utils/ and helpers/ folders that become junk drawers.

Combining Both: Feature-First Structure

Here’s what a feature-first Node.js project looks like when you combine screaming architecture with colocation:

src/
├── patients/
│   ├── patient.controller.ts
│   ├── patient.service.ts
│   ├── patient.repository.ts
│   ├── patient.types.ts
│   ├── patient.validation.ts
│   ├── patient.routes.ts
│   └── __tests__/
│       ├── patient.service.test.ts
│       └── patient.controller.test.ts
├── appointments/
│   ├── appointment.controller.ts
│   ├── appointment.service.ts
│   ├── appointment.repository.ts
│   ├── appointment.types.ts
│   ├── appointment.validation.ts
│   ├── appointment.routes.ts
│   └── __tests__/
│       └── appointment.service.test.ts
├── shared/
│   ├── middleware/
│   │   ├── auth.middleware.ts
│   │   └── error-handler.ts
│   ├── database/
│   │   └── prisma.ts
│   └── types/
│       └── common.ts
├── app.ts
└── server.ts

Every feature is self-contained.

Tests live next to the code they test.

Shared infrastructure sits in shared/, but only things that are genuinely shared across features.

The Same Principle in React

src/
├── features/
│   ├── patients/
│   │   ├── PatientList.tsx
│   │   ├── PatientDetail.tsx
│   │   ├── usePatients.ts
│   │   ├── patient.types.ts
│   │   └── patient.api.ts
│   ├── appointments/
│   │   ├── AppointmentCalendar.tsx
│   │   ├── BookAppointment.tsx
│   │   ├── useAppointments.ts
│   │   └── appointment.api.ts
├── shared/
│   ├── components/
│   │   ├── Button.tsx
│   │   └── Modal.tsx
│   ├── hooks/
│   │   └── useAuth.ts
│   └── lib/
│       └── api-client.ts
├── App.tsx
└── main.tsx

Same idea.

Features own their components, hooks, types, and API calls.

shared/ contains only genuinely reusable pieces.

When Layers Still Make Sense

Layers aren’t always wrong. They work when:

• Your app is small (< 10 files). Feature folders are overhead for a simple CRUD API.

• You’re building a library. Internal structure matters less than the public API.

• Your team is one person. You already know where everything is.

The pragmatic hybrid: features at the top level, layers within each feature.

Each feature has its own controller, service, repository, but they’re colocated, not scattered.

Enforcing Boundaries

Structure without enforcement is just a suggestion.

Here's how to make it stick:

ESLint (with eslint-plugin-boundaries)

// .eslintrc.js
module.exports = {
  plugins: ['boundaries'],
  settings: {
    'boundaries/elements': [
      { type: 'patients', pattern: 'src/patients/*' },
      { type: 'appointments', pattern: 'src/appointments/*' },
      { type: 'shared', pattern: 'src/shared/*' },
    ],
  },
  rules: {
    'boundaries/element-types': [2, {
      default: 'disallow',
      rules: [
        { from: 'patients', allow: ['shared'] },
        { from: 'appointments', allow: ['shared', 'patients'] },
      ],
    }],
  },
};

TypeScript Project References

// src/shared/tsconfig.json — every referenced project needs composite: true
{
  "compilerOptions": {
    "composite": true,
    "rootDir": ".",
    "outDir": "../../dist/shared"
  }
}

// src/patients/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "rootDir": ".",
    "outDir": "../../dist/patients"
  },
  "references": [
    { "path": "../shared" }
  ]
}

Each feature is a TypeScript project.

It can only reference what's listed in references.

The compiler enforces boundaries at build time.

📌 Key Takeaways

1. Your folder structure is documentation. It should tell a new developer what the app does in 5 seconds.

2. Organize by feature, not by layer. Controllers, services, and models for the same feature belong together.

3. Colocate aggressively. Tests, types, and utilities live next to the code that uses them. Move things to shared/ only when two or more features need them.

4. Migrate incrementally. One feature at a time, one PR at a time. No big-bang restructures.

5. Enforce with tooling. ESLint boundaries, TypeScript project references, or Nx module boundaries. Structure without enforcement decays.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

Those engineers ship less, talk more, think further ahead, and treat AI like a power tool, not a replacement for judgment.

• Share this post & I’ll send you some rewards for the referrals.

Imagine spending six weeks building a sleek, real-time notification system that nobody actually requested.

You nailed down the “right architecture”, covered the codebase with tests, and perfected the documentation.

Then comes the week before launch. Your PM demos the masterpiece, and suddenly part of your customers refuse to use it while the other asks why a certain bug still exists.

Stories like this project remind me of the difference between being efficient and being effective.

Efficient engineers do things right.

Effective engineers do the right things.

After 8+ years of shipping software, hiring engineers, and watching teams succeed and fail, I’ve distilled what makes engineers genuinely effective into four disciplines.

And none of them is about writing clever code.

BrightData: Connect Your AI To The Internet’s Data - Sponsor

Bright Data’s Web MCP solves web access for LLMs and AI agents, allowing them to effectively search, extract, and navigate the web without getting blocked. It helps to:

• Search the web in real-time

• Extract data from any website

• Navigate and interact with pages

• Bypass blocks and restrictions

It comes with a generous free tier - 5,000 MCP requests every month - for free!

Try For Free

1. Solve the Right Problems; Not Just Any Problem

Traits: Care about the user. Understand team strategy. Prioritize ruthlessly.

The most expensive line of code is the one that solves the wrong problem.

I’ve seen teams spending time into plubming, like managing a custom-built deployment pipeline, instead of leveraging $50/month SaaS.

Here is the uncomfortable part: most engineers aren’t trained to say no.

We’re rewarded for building. Promotions come from shipping. Saying “we shouldn’t build this” doesn’t show up in a pull request.

But caring about users, I mean actually caring, not only claiming that on a performance review, means understanding their real problems deeply enough to know which solutions are worth pursuing and which are engineering vanity projects.

And you can’t make that judgment in a vacuum.

You need to understand your team’s strategy:

• What are we trying to accomplish this quarter?

• How does my work connect to revenue, retention, or reliability?

Engineers who can answer those questions prioritize themselves.

Engineers who can’t are always waiting to be told what to do next.

So next time, before writing any line of code, force yourself through these three questions:

• Who suffers if this doesn’t ship? If the answer is “nobody, really,” put it in the icebox.

• What’s the cheapest version that tests the hypothesis? A spreadsheet, a Figma prototype, or a hardcoded endpoint can often answer the question a six-week feature build was supposed to answer.

• What am I not doing by doing this? Opportunity cost is invisible until you’ve missed a deadline on the thing that actually mattered.

Of course, we can’t do some of these things by ourselves. That’s why we have Product Managers who are the point of contact to the end users and our organization.

Our job as Effective Engineers is to advocate for users, do extensive user research, and prioritize user needs.

2. Keep It Simple; Leave It Better

Traits: Simplicity over cleverness. Quality as a discipline. The Boy Scout Rule.

I’ve reviewed pull requests where the author used three levels of abstraction to avoid repeating four lines of code.

The DRY principle is good. But taken to its extreme, it produces code that’s “elegant” but unreadable to everyone except the person who wrote it, and often to them too, three months later.

Simplicity isn’t the absence of thought. It’s the result of deep thought.

It means you’ve understood the problem well enough to solve it without over-engineering.

The engineers I respect most write code that a new team member can read on their first day and say, “Okay, I see what this does”.

But simplicity alone isn’t enough.

The effective engineers also leave things better than they found them.

Every PR is an opportunity: fix a flaky test, update a stale README, delete dead code, or rename a confusing variable.

None of these show up in a sprint demo.

All of them compound into a codebase that’s a joy to work with versus one that slowly rots.

So the next time you write and ship code, try to:

• Set a complexity budget. If a solution requires more than one new abstraction, pressure-test whether that abstraction earns its keep. Often it doesn’t.

• Timebox polish. I allocate roughly 10-15% of every feature’s time for cleanup, not gold-plating, but genuine improvement to the code I touched and the code around it.

• Measure quality that matters. Track things like time-to-first-meaningful-PR-review for new hires, or incident rate per deploy. These tell you more about codebase health than test coverage percentages.

You have to be comfortable with invisible contributions.

The payoff comes in months, not days: fewer incidents, faster onboarding, less time debugging code nobody understands.

3. Earn Trust; Communicate Relentlessly

Traits: Build trust and social capital. Communicate effectively. Operate with autonomy.

Early in my career, I thought trust was a soft-skills thing, something you got for free by being “nice”.

That’s not how it works.

Trust is an engineering asset.

It’s the reason one engineer can get a risky refactor approved in a single meeting while another spends two sprints writing a design doc that still gets rejected.

Think about it mechanically: engineers who’ve built trust get more autonomy.

More autonomy means they can take bigger swings.

Bigger swings, when they land, build more trust. It compounds like interest.

And the inverse is just as powerful: one blown deadline or one surprise production incident you didn’t communicate about can set you back months of accumulated credibility.

Communication is the engine that drives all of this.

Not “being good at presentations”, I mean the boring, daily discipline of keeping people informed. Status updates nobody asked for. A Slack message before you merge something risky. Flagging a blocker on Day 1 instead of Day 5.

The engineers who do this consistently become the ones everyone wants on their project.

Here are a few things you could try:

• Estimate honestly, then pad 20%. On one project, I started adding explicit “risk buffers” to my estimates, and my on-time delivery rate went from roughly 60% to over 85% in two quarters.

• Communicate bad news early. If a project is slipping, saying so on Day 3 builds trust. Saying so on Day 13 destroys it. I’ve never seen anyone punished for early transparency. I’ve seen plenty punished for late surprises.

• Review others’ code generously. Fast, thoughtful code reviews are one of the highest-leverage trust-building activities in engineering. They signal “I respect your time and your work”. They also build social capital, the kind of relationship equity that means people answer your Slack messages in minutes instead of hours.

• Invest in relationships outside your team. Grab coffee with the infrastructure team. Understand what the data team is struggling with. Cross-team relationships pay dividends when you need a favor, a quick answer, or buy-in on a proposal.

Building trust slowly means you won't be the hero on Day 1. You might watch a louder, faster colleague get more visibility early on. The patience required is real.

And there's an uncomfortable truth: trust is context-dependent.

Switching teams or companies resets the meter. You have to be willing to re-invest every time.

4. Think Long-Term; Adapt Constantly

Traits: Second-order thinking. Comfort with new challenges. Wielding AI as a force multiplier.

Junior engineers think about whether their code works. Mid-level engineers think about whether their code is maintainable. Senior engineers think about what their code causes, downstream, six months from now, in systems they don't own.

And here's the thing that's changed in the last two years:

Long-term thinking now includes your relationship with AI tooling.

The engineers who treat GitHub Copilot, Claude, or Cursor as magic black boxes are building on sand.

The ones who understand what these tools are good at (boilerplate, scaffolding, routine refactors), what they're bad at (nuanced architecture decisions, security edge cases, understanding your specific business context), and how to verify their output, are the engineers who are genuinely 2-3x more productive.

But only because they bring the judgment the AI lacks.

Treat AI-generated code like a pull request from a confident but context-blind junior.

Review every line. Question every assumption. The speed is real, but so are the subtle bugs.

Being comfortable with new challenges has always mattered. Now it's existential.

The landscape shifts every six months.

The engineers who thrive aren't the ones who memorize every new framework.

They're the ones who've built strong enough fundamentals that they can pick up any tool quickly and evaluate it critically.

Second-order thinking is slow.

Learning new tools takes time away from shipping.

There's a real risk of analysis paralysis, and an equally real risk of chasing every new AI tool instead of mastering the one you have.

The discipline is knowing when the blast radius is large enough to warrant the extra thought, and when to just ship.

You can learn a new framework in a weekend.

You can learn a new AI tool in an afternoon.

These four disciplines take years. Start now.

See you next time! 🙌

PS: My friend Marko Denic has recently launched his new FREE e-book: The Technical Decision Framework. It’s about a framework for the choices that shape your codebase.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

Press the Like button if you found this post helpful

• Share this post & I’ll send you some rewards for the referrals.

Imagine a team launches a new product. Traffic grows. Everything’s fine.

Then one day, a query takes 8 seconds instead of 80ms. Engineers start adding indexes. Caching layers. Read replicas.

None of it helps enough.

The problem wasn't performance. It was bad database design. And by the time they realized it, they had 200 million rows in production and a Slack channel dedicated to database incidents.

Database decisions are long-term bets.

Get them wrong early, and you'll spend years firefighting.

Get them right, and your system scales quietly while you build features.

Your Schema Will Outlive Your Code. Plan Accordingly.

A careless column type. A missing foreign key constraint. An unnecessary denormalization because “it might be faster”.

These choices feel small when you're building v1. But databases are permanent in ways code isn't.

You can refactor a service in a weekend.

A schema migration on a table with 500 million rows in PostgreSQL?

That's a multi-month project involving table locks, replica lag monitoring, and very careful coordination with the ops team, who definitely don't want to hear from you at 2 AM.

The teams that win long-term treat table design with the same respect they give code architecture. Maybe more, because you can't just roll back a schema change when 50 million user records depend on it.

Start With Reality, Not With Tables.

Most engineers rush straight to CREATE TABLE before understanding what they're actually modeling.

Don't do this.

Spend real time mapping the business domain.

What entities exist in the real world? What relationships matter to the business? What constraints does reality enforce that your database should mirror?

If you’re building a job board, understand that a job posting isn’t just a row. It has a lifecycle: draft, published, filled, and expired. It belongs to a company. It attracts applications. Each application connects a candidate to a posting.

The database should enforce what the domain requires.

If your schema allows states that can't exist in reality, eventually someone will put your data into one of those states.

Normalization Is Your Friend (Until It Isn’t)

Normalization means organizing data to eliminate redundancy and dependency issues.

Third normal form (3NF) is the target - every column depends on the primary key, the whole key, and nothing but the key.

In practice, this means that a user's data is in one table, addresses in another, and orders in a third. Then, we join them when needed.

This prevents update anomalies. We change a user’s email once, not in seventeen places. We can also safely delete an order without losing customer data.

But over-normalization can destroy read performance.

If your application shows “user profile with last 10 orders” on every page load, and that requires five joins across normalized tables, you’re paying a cost.

A good rule of thumb is:

Let query patterns guide your final design.

Start normalized.

Denormalize deliberately when you have real performance data.

To mitigate the above-mentioned problem, we might want to add a materialized view that flattens this query and then refresh it on writing.

Or we can do something else, depending on the business case and needs.

Denormalization is a tool. Use it when the tradeoff is clear.

Indexes: The Contract You Make With Future You

An index is a data structure that makes lookups fast by avoiding full table scans.

Without an index on users.email, a query like WHERE email = 'user@example.com' checks every row. With an index, it jumps directly to the match.

But indexes aren’t free.

Every index slows down writes. The database must update the index on every INSERT, UPDATE, or DELETE. Indexes consume disk space. And poorly chosen indexes bloat over time, requiring maintenance.

The strategy I follow:

• Index foreign keys and columns used in WHERE, JOIN, and ORDER BY clauses

• Avoid indexing columns with low cardinality (e.g., boolean flags)

• Use composite indexes when queries filter on multiple columns together

• Monitor and rebuild indexes periodically to prevent fragmentation

Hint: Use pg_stat_user_indexes to monitor index usage in PostgreSQL.

Index deliberately.

Measure the impact using EPLAIN ANALYZE.

Remove what doesn't serve you.

Constraints Are The Best Documentation You’ll Ever Write

Foreign keys. NOT NULL. UNIQUE. CHECK constraints.

These aren’t optional guardrails. They’re how you encode business rules into the database itself.

A foreign key constraint ensures referential integrity. If orders.user_id references users.id, you can’t have an orphaned order pointing to a deleted user.

A NOT NULL constraint guarantees a value exists. No defensive null checks in application code.

A CHECK constraint validates data at write time. Age must be positive. Status must be one of five valid values.

This matters because constraints catch bugs before they corrupt data.

Constraints add minor write overhead, maybe 1-2%, or sometimes less. But they give you guaranteed correctness.

If your database allows invalid data, eventually you’ll have invalid data.

Performance Is A Design Choice, Not a Tuning Exercise

I’ve seen teams spend weeks chasing query plans, adding caches, and tuning connection pools.

Most of the time, the real problem is the schema.

A single redesign could fix the issue forever: moving a frequently-joined column into the main table, splitting a bloated table into hot and cold storage, adding a covering index, and partitioning by time range.

Here's what makes database design genuinely hard: you don't know the full business context at the start. Requirements evolve. Query patterns change.

The answer isn’t perfection upfront. It’s about designing for change.

Keep things simple. Use clear naming conventions. Avoid premature optimization. And critically, don't be afraid to migrate the schema when you learn something new about your domain or your access patterns.

A well-designed schema can handle 10x growth with minor adjustments. A poorly designed one requires rewrites.

What I Wish Someone Had Told Me

If I could give my younger self advice, I'd say this:

Practice designing schemas for real systems. Pick LinkedIn, Twitter, or Airbnb. Map the entities. Draw the relationships. Think through the queries. Do it on paper before you touch a database.

Learn SQL deeply. Not just SELECT and JOIN. Window functions. CTEs. Query plans. Execution order. Understand what the database does with your query.

Start simple, but extensible. Don't build for scale you don't have. But leave room to grow. Design your schema so that adding columns or splitting tables doesn't require a full rewrite.

Measure everything. You can't optimize what you don't measure. Track query times. Index usage. Table sizes. Slow query logs.

The best engineers I know treat database design like architecture. They think through the consequences of their decisions. They plan for failure modes. They build systems that last, not just systems that work.

And they're never ashamed to run a migration when they learn something new.

Because databases don't forget your mistakes, but they do forgive your improvements.

Follow me on LinkedIn | Twitter(X) | Threads

Thank you for supporting this newsletter.

Consider sharing this post with your friends and get rewards.

You are the best! 🙏

Share

If you enjoy The T-Shaped Dev, it would mean the world to me if you invited friends to subscribe and read with us. If you refer friends, you will receive benefits that give you special access to The T-Shaped Dev.

How to participate

1. Share The T-Shaped Dev. When you use the referral link below, or the “Share” button on any post, you'll get credit for any new subscribers. Simply send the link in a text, email, or share it on social media with friends.

Refer a friend

2. Earn benefits. When more friends use your referral link to subscribe (free or paid), you’ll receive special benefits.

• Get Pull Request Checklist for 1 referrals

• Get Brag List (Work Log) Template for 2 referrals

• Get Technical Design Document Template for 3 referrals

Refer just 3 people & I'll send you some rewards. 🎁

Refer a friend

Imagine you’re using one AI tool for everything - designing, planning, coding, reviewing, etc.

After a while, you start to see some pitfalls in the LLMs output.

While many LLMs are doing okay for general-purpose tasks, they tend to fall short when it comes to highly specialized tasks.

That’s why it is important to use different types of AI agents, each optimized for a different task.

For example, let’s say you have a UI problem. You would ask for help from the Front-End guy, not the Back-End guy, even though the Back-End guy has some knowledge of the front-end too.

We should apply the same logic and approach to using LLMs as well.

Use the right agent for the right task so we can craft better software.

In the previous article, we covered the systematic AI code review workflow: Plan, Generate, Validate.

Now, let’s map the right tools to each phase:

• Plan → use Advisors (think through decisions)

• Generate → use Generators (write code fast)

• Validate → use Reviewers (catch issues automatically)

Each phase needs a different type of AI agent. Let’s understand what makes each one specialized and what traps to avoid when using.

The Three Types of AI Agents

Each AI agent is trained and optimized for specific tasks.

Using a generator for security review is like using a hammer to tighten a screw.

It’s technically possible, but we would use the wrong tool for the job.

Here is the breakdown:

• Advisors (Claude, ChatGPT)

  • Purpose: understanding and decision making

  • Optimized for: explaining concepts, evaluating trade-offs, designing, researching, refactoring strategy

  • Blind to: your specific codebase, real-time feedback, automated integration

• Generators (Cursor, Copilot)

  • Purpose: fast code implementation

  • Optimized for: speed, autocomplete, pattern matching

  • Blind to: security vulnerabilities, architectural implications, edge cases

• Reviewers (CodeRabbit and similar)

  • Purpose: quality assurance and bug detection

  • Optimized for: security, bugs, performance, consistency

  • Blind to: design decisions, why code exists, future requirements

If you’re wondering when to use each, use these questions to navigate your judgment:

• Need to make a design decision? → use Advisor

• Need to write code fast? → use Generator

• Need to validate code quality? → use Reviewer

Your role is to select the tool, knowing which agent to use and when.
You have to validate, reason, and do problem-solving.

Now, let’s dig deeper into each AI agent.

Note: Some IDEs, like Cursor, have different modes built in, like Agent, Plan, Debug, Ask, so you could use one IDE, switch the mode, and have a different type of AI agent. However, you still have to know how to use each of those tools.

The Advisor: When Decisions Matter

Advisors don’t write your code or review it automatically.

They help you think through problems, break down complex tasks into an executable plan, understand trade-offs, and make better decisions before you start implementing a specific approach.

Advisors excel at explaining the “why” behind code, not just what it does, but the reasoning and trade-offs that led to that implementation.

✅ With Advisors, you should prefer:

• Using before making major architectural decisions

• Understanding existing and/or unfamiliar code

• Exploring different approaches and strategies and their trade-offs

• Providing context about your project, current choices, and structure

• Learning new patterns and concepts

⛔ With Advisors, you should avoid:

• Writing code (generators are faster)

• Using them for bug detection (reviewers are better)

• Expecting it to know your codebase or internal team’s dynamics

• Following advice blindly without understanding

So,

Advisors help you make better decisions.

Use them before you start coding, not after.

The Generator: When Speed Matters

The Generators excel at writing code quickly.

They’re autocomplete on steroids, trained on millions of code examples to predict what you’re trying to write.

✅ With Generators, you should prefer:

• Using for daily coding, boilerplate, CRUD operations, etc

• Scaffolding tests

• Writing type definitions and interfaces

• Writing code to follow existing patterns and conventions

• Iterating on suggestions and do not always accept the first try

⛔ With Generators, you should avoid:

• Trusting it for security-critical code without review

• Assuming it validates business logic

• Assuming it writes proper type definitions of your domain models

• Using it to make architectural decisions

• Skipping review because “AI wrote it”

So,

Generators are for speed.
Always validate the output with a review and your reasoning.

Use them after you have a concrete plan in mind.

The Reviewer: When Quality Matters

Reviewers are specialized for finding issues in existing code.

An example of a Reviewer is CodeRabbit.

They don’t generate. They analyze, detect patterns and conventions, and flag problems.

✅ With Reviewers like CodeRabbit, you should prefer:

• Using on every PR before merging

• Addressing security and bug findings immediately

• Using suggestions as learning opportunities (you could ask Advisors to help)

• Configuring rules and guidelines for your specific tech stack and codebase

⛔ With Reviewers like CodeRabbit, you should avoid:

• Skipping review because the code “looks fine”

• Dismissing warnings or applying suggestions without understanding them

• Using it to write new code (wrong tool)

• Expecting it to validate business logic

So,

Reviewers help us catch things which generators miss.

They act as our QA and Security guy.

Use them while or after you generate code. Then you fix and repeat.

Now that we understand each agent’s specialty.

Here is how to use them together effectively:

• Making a decision? → Advisor (understand trade-offs first, make a plan)

• Writing code? → Generator (fast implementation)

• Code written? → Reviewer (catch issues automatically)

• Issues found? → Generator (quick fixes) → Reviewer (validate)

And remember:

⚠️ Your role is to select the tool and always validate and understand the output!

When Agents Disagree

Sometimes, different agents might suggest conflicting approaches.

Here is how I resolve them:

• For architecture, I weigh the Advisor’s opinion carefully, but also consider the current context, business needs, and constraints.

• For implementation details, I follow the generated code from the Generator because it knows the codebase best and the already established patterns.

• For security issues, I trust the Reviewer’s suggestions (like CodeRabbit) because security is non-negotiable.

In the end, the final decision is yours because you know all the specific domain and business context, needs, and constraints.

AI shouldn’t be your excuse for making wrong and unjustified decisions.

You are the Software Engineer who navigates and drives the AI, not the other way around.

You’re the final decision maker!

📌 TL;DR

• Using one AI tool for everything means missing what other specialized tools catch.

• Prefer to use a different AI agent, each optimized for different tasks

• We have generally three types of AI agents: advisors (Claude/ChatGPT), generators (Cursor/Copilot), and reviewers (CodeRabbit).

• Match the tool to the tasks, advisors for decisions, generators for speed, reviewers for safety.

So try out these three agent types in your daily coding workflow and let me know how you found them.

I promise this way of working will improve your code.

Hope this was helpful.

See you next time! 🙌

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 29.5K+ subscribers this week 🙏

Once upon a time, a developer spent an afternoon building a user registration API with AI assistance.

API endpoints, proper validation, clean error handling—everything compiled perfectly and worked flawlessly in staging.

The PR was approved and merged into production.

Hours later, the security team sent an urgent Slack message.

The newly introduced endpoint was vulnerable to SQL injection through unvalidated query parameters.

One line of code. One blind spot.

One security vulnerability that an automated review would have caught instantly.

That’s the current reality of AI and Vibe coding without a systematic workflow:

It’s not a productivity, it’s a technical debt at AI speed.

To mitigate this, we need a new system to handle the massive code generation facilitated by AI.

In today’s article, I’ll share a systematic AI code review workflow to adapt to the new AI and Vibe coding era.

Why You Need a Loop

Most developers follow this pattern:

1. Generate code with AI

2. Push to production

3. Hope for the best

The problem with this approach is that AI optimizes for “working”, not “correct” code.

It writes code that compiles and runs, but might have security vulnerabilities, performance issues, edge case failures, and inconsistent error handling.

Imagine the following scenario: You ask your LLM to generate an Express API endpoint for user registration. The code works perfectly:

app.post(’/api/register’, async (req, res) => {
  const { email, password, username } = req.body;
  
  const user = await db.query(
    `INSERT INTO users (email, password, username) VALUES (’${email}’, ‘${password}’, ‘${username}’) RETURNING *`
  );
  
  res.json({ success: true, user });
});

However, there are a few major problems. SQL injection vulnerability. No password hashing. No input validation. No error handling, etc. You get the point.

The main point is that the code “works”, but it’s a security nightmare.

This is where the three-phase loop comes in:

Plan → Generate → Review → Ship
         ↑            ↓
         └── Fix ─────┘

The key principle is:

Separate generation from validation.

You might use:

• Generation AI, like Cursor, Claude, or Copilot, optimizes for speed and functionality.

• Review AI, like CodeRabbit, optimizes for security, performance, and quality.

• You act as an orchestrator of both.

This way, each phase catches different types of issues.

Let’s dive in.

Phase 1: Plan Before You Generate

Good AI output starts with good input.

Planning before you generate any code creates better results.

Why planning matters:

• clear specs = better AI output

• prevents “works but unmaintainable” code

• creates a checklist for validation

• saves hours of debugging later

You might use Cursor Plan mode, or any other LLM like Claude or ChatGPT, to come up with a detailed action plan.

I personally try to fill out the following template before moving to the code generation:

Feature: [Name]
Purpose: [One sentence]
Inputs: [List with types and validation rules]
Outputs: [Success and error cases]
Edge cases: [What could go wrong?]
Security considerations: [What must be protected?]

Feel free to edit it based on your current context, problem, and task.

This approach helps me be more confident that I’ve outlined all the important requirements and considerations before moving to the next phase.

If we follow the example from above related to the user registration endpoint for an Express API, we might prompt the following:

I need a user registration endpoint for an Express API. Users provide email, password, and username. Help me design the endpoint that handles validation errors, duplicate emails, and weak passwords. What else should I consider for security, validation, and error handling?

Based on the given output, summarize the findings into the above-mentioned template, so you can share it in the prompt in a structured format when starting to generate code.

Phase 2: Generate With Context

Once you’ve gone through the planning and have a structured and summarized plan, you’re ready to generate.

Since you already defined a plan, you can create focused and high-quality prompts.

Generation best practices:

• Generate one endpoint, component, or feature at a time. Don’t generate the entire service. The smaller and more focused the task, the better the outcome.

• Use separate prompts/chats per task. Maintain the context window. Keep it as small as possible. This also reduces the costs.

• Copy relevant sections from your plan directly into the prompt.

• Iterate 2-3 times rather than expecting perfection on the first try.

• Specify your exact tech stack, code style, and structure. Provide examples from the codebase if relevant.

AI generation is a conversation, not a one-shot command!

During the code generation phase, you want to manually check:

• Does it follow your tech stack conventions?

• Are the types and interfaces correct?

• Does it match your project structure?

• Are dependencies the ones you actually use?

If something looks off, create a new chat and refine your prompt with more specific guidance.

In the LLM world, if the first prompt is not okay, it’s hard to change it later.
Better create a new chat with a clean context and an improved prompt.

Coming back to the example from above related to the user registration endpoint for an Express API, we might prompt the following:

Create an Express TypeScript POST endpoint at /api/register for user registration.

Requirements:
- Accept email (string), password (string), username (string) in request body
- Validate email format (RFC 5322)
- Validate password: minimum 8 characters with at least one number
- Validate username: 3-20 alphanumeric characters only
- Hash password with bcrypt (12 rounds) before storing
- Use parameterized database queries to prevent SQL injection
- Handle duplicate email (return 409 with generic message)
- Handle validation errors (return 400 with field-specific errors)
- Handle database errors gracefully
- Return 201 with user object (exclude password) on success

Use Zod for input validation and proper TypeScript types throughout.

Even though we’ve outlined a detailed plan and have a solid code, we might still miss important stuff.

For example, “Are there any missed edge cases?”, “Performance implications?”, “Is the validation comprehensive enough?”, etc.

This is exactly why we need the review phase.

We want to get a higher confidence in what we ship and double-check that we haven’t missed important considerations.

Phase 3: Review and Validate

We have a working code. Now, it’s time to validate it with a second AI perspective specialized for review.

Why bother reviewing AI-generated code?

• AI generators have blind spots. They optimize for “working”, not “correct” code.

• Different AI models catch different issues and blind spots.

• Automated reviews find problems in seconds.

• Ensures consistency across your codebase.

An example of such an AI code review tool is CodeRabbit.

What CodeRabbit catches:

• Security: SQL injections, XSS vulnerabilities, exposed secrets, etc.

• Bugs: race conditions, incorrect error handling, etc.

• Performance: missing db indexes, N+1 queries, etc.

• Best practices: inconsistent error handling, missing type safety, etc.

Put simply, CodeRabbit complements human reviewers, adding a lot of context based on your repo and general engineering practices.

📌 TL;DR

This systematic AI code review workflow isn’t optional; it’s how you maintain quality at AI speed:

• Plan before you generate (upfront thinking saves hours).

• Generate with context (good prompts = good code).

• Review with specialized AI (e.g., CodeRabbit catches what generators miss).

Hope this was helpful.

See you next time! 🙌

P.S. If you’re into Web Development, I recommend you subscribe to Marko Denic’s newsletter, which is full of many tips and tricks.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 29.3K+ subscribers this week 🙏

A while ago, I worked for a client who had a diverse portfolio of digital products.

They’ve struggled to develop new features, reuse business logic and functionality across products, and also scale the engineering team.

By digging deeper into the case, I’ve found they have:

• bad architecture, which doesn’t support their growth

• years of accumulated technical debt

The root cause turned out to be a 2-Tier Architecture that had outlived its purpose.

In today’s article, I’ll share how I tackled this challenge by migrating their system from a Two-Tier Architecture to a Three-Tier Architecture, introducing a scalable, robust GraphQL API.

IcePanel is a collaborative diagramming and modelling tool for designing software architecture. Create interactive, layered views for different stakeholders from a single source of truth.

Try for free

Before we dive into the actual migration journey, let’s ensure we understand what a 2-Tier and a 3-Tier architecture are.

What is Two-Tier Architecture?

2-Tier Architecture is a simple setup in which your application talks directly to a database.

You have a presentation layer (the front-end) and a data layer (the database).

That’s it. No middle layer.

Think of it like a simple website or app that sends requests directly to the database, retrieves the data, and displays it to users.

What is Three-Tier Architecture?

3-Tier Architecture adds an essential middle layer between your front-end and database. Now you have:

1. Presentation Layer - the front-end (what users see).

2. Business Logic Layer - the API (where the magic happens).

3. Data Layer - the database (where data lives).

The middle layer handles all the business logic, security, and data processing.

The main difference between a 2-Tier and a 3-Tier architecture is the separation of concerns.

In a Two-Tier architecture, your front-end must know too much about your data, whereas in a Three-Tier architecture, the business logic layer acts as a smart middleman.

This smart middleman protects your data and enables the whole system to be more flexible.

The Starting Architecture (Two-Tier)

Now, let me show you what the client’s system looked like before the migration.

They had three main services, all sharing one MySQL database:

• Portal - The customer-facing web portal. The front-end was React, but the back-end was built with CakePHP 2 (an outdated PHP framework).

• Admin - The internal management web portal of the company. Everyone in the company used it to run the business, from operations to finance. Also built with CakePHP 2.

• API - A small REST API with just three methods for customers. Again, Cake PHP 2.

All three services are connected directly to the same MySQL database.

The database was the integration point for everything.

This setup created several serious problems.

The Top Technical Challenges

• Duplicated logic - The same business logic and rules were duplicated in multiple services.

• Database as an integration point - Having multiple services write to the same database is risky. There is no single source of truth for business logic and data validation. Also, it is very hard to update or migrate the database when having multiple clients.

• Technical debt - CakePHP 2 reached end of life. There was a need to modernize the tech stack by using well-adapted technologies.

• Hard to scale the engineering team - This was hard to find developers to work on front-end and back-end with the present technologies. There was a need to enable full-stack developers.

• Slow feature development - With the challenges mentioned above, feature development was slow, hindering the business's growth.

To address these challenges, we introduced a new middle layer—a GraphQL API.

The Final Architecture (Three-Tier)

The GraphQL API became the heart of the system.

It sits between all front-ends and the database.

The Main Architectural Improvements

The new architecture solved our major pain points:

• Centralized business logic - All business-related logic lives in one place now. The GraphQL API is the single source of truth for all features.

• Single database owner - Only the GraphQL API can access the database. This makes the system safer and easier to refactor.

• Modern tech stack - We built the API using Node.js, a technology already used by the company. Apart from that, GraphQL provides flexible, efficient data fetching to accommodate the needs of different API clients.

• Full-stack friendly - Having the same core technology, JavaScript, on the front-end and back-end, enabled the company to hire Full-Stack JavaScript developers.

• Ready for microservices - To ensure the system's future flexibility and the company’s growth, the API was designed as a Modular Monolith, so that, when needed, internal modules could be extracted into separate services.

The Migration Approach

We didn’t rebuild everything overnight.

This was too risky from both a business and an engineering perspective.

The business must continue operating while the groundwork is being done under the hood.

That’s why we took an iterative approach:

• Phase 1: Build the GraphQL API - We created the new API layer, starting with the most critical business logic, shared across multiple services.

• Phase 2: Migrate Portal - The Portal front-end started using the GraphQL API. We moved features one by one and tested thoroughly.

• Phase 3: Update Admin - We upgraded Admin to a modern version of CakePHP. Then we gradually moved its logic to the GraphQL API, starting with shared functionality.

• Phase 4: Rewrite REST API - The customer-facing REST API had only three methods, so we rewrote it in Node.js to align with the new stack.

• Phase 5: Migrate Admin to React - We started migrating the Admin to React, instead of CakePHP, prioritizing newly incoming feature requests.

📌 TL;DR

• 2-Tier Architecture is when multiple clients or services directly communicate with the Database.

• 3-Tier Architecture is when multiple clients or services communicate with a middle layer, usually an API, which then communicates with the actual DB.

• Having three clients communicating with a DB means duplicated business logic everywhere.

• Having a middle layer, in this case a GraphQL API, means a single user communicates with the DB, removing duplicate business logic.

• Centralizing business logic in the GraphQL API eliminated duplicate code, made onboarding new teammates easier, enabled quicker feature delivery, and created a system ready to scale into microservices when needed.

Hope this was helpful.

See you next time! 🙌

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28.7K+ subscribers this week 🙏

You’ve tried everything you can think of, but the issue persists…

Debugging doesn’t have to be this painful.

It’s a skill you can develop with the right strategies and tools.

It’s something you can learn and get better at.

Mastering debugging can save you time, energy, frustrations, and money as well as improve your code quality.

In today’s article, I’ll share ten practical debugging techniques I use daily that have saved me countless hours.

I’ll also show you some modern tools that could make these strategies even more effective.

Being effective while debugging is crucial.

It’s really important to get it right so you find the root cause of the issue, fix it asap, and then make your customers happy.

Over the years, as a Software Engineer, I’ve found that good debugging is not only about the processes and systems you employ, but also about your mindset and tooling.

I’ve played around with various tools both at my daily job and side projects.

Recently, I tried out Multiplayer, a new session replay platform that captures both the front-end and back-end traces.

I believe we can make debugging much simpler with the help of Multiplayer, effective, and easier to do.

Part 1: Set Yourself Up For Success

1. Reproduce the Error Consistently

You can’t fix what you can’t see.

The foundation of effective debugging is consistently reproducing the bug.

Start by writing step-by-step instructions that make the bug appear every time.

For example, map out how a user request flows through the whole system, so you build a clear mental model.

This is especially useful in the context of microservice architecture, where a single user request might hit several services.

Finding the bug in the ground schema is hard if you don’t have a good understanding of the flow.

Nowadays, there are tools that record session replays, so you can leverage them to see the flow from the front-end to the back-end instead of doing it manually.

An example of such a tool is Multiplayer, which captures full-stack session recordings.

2. Reproduce the Error Quickly

Once you know how to reproduce a bug, make it fast.

Configure your development environment to jump straight to the problematic area.

This helps to quickly test various hypotheses and solutions.

Every second you save between reproducing the bug and testing a fix compounds over the course of dozens of debugging iterations.

3. Capture the Full Context

Debugging an issue in a complex system —from front-end to back-end —is hard.

It requires acquiring as much information and context as needed.

Imagine a user reporting a problem—“the page crashed”—but you miss information like why they clicked, what data they had loaded, or the system's state.

So, before digging into the problem, try to collect as much context as possible—ask your product manager, write an email to a client, check recordings, logs, etc.

You might also consider using a tool like Multiplayer, which silently captures user sessions so you can collect all the context related to a single issue.

Part 2: Active Debugging Techniques

4. Isolate the Problem

Large codebases make finding bugs like finding a needle in a haystack.

You need to narrow down the scope quickly.

Use a binary search approach: divide your code into working and non-working parts.

Comment out half of the suspicious code. Does the bug occur? If yes, the problem is in the other half. If no, it’s in the code you commented out.

You might also use breakpoints like a binary search to quickly jump to different points in your code.

Repeat this process until you’ve nailed the problematic area.

The main goal is to minimize the scope from “somewhere in this 1000-line file” to “somewhere in these 20 lines”.

5. Use Your Debugger

Debuggers are invaluable tools that provide real-time insights into your program’s execution.

You can set breakpoints, inspect variables, step through the code line by line, and examine the call stack.

The main benefit is that you can easily see the exact flow of your program and spot anomalies as they happen.

If you’re using tools for recording session replays, you could bring those recordings directly into your IDE.

I’ve personally tried Multiplayer and it worked like a charm.

6. Rubber Duck It

Rubber duck debugging is simple but extremely powerful.

The main idea is that you explain your code line by line to an object (🦆), a colleague, or even yourself.

You describe what you expect to happen at each step.

The act of explaining forces you to slow down and verify your assumptions.

There is a big difference in how we think about the code when we read and when we speak loudly about it.

I’ve caught the bug many times in the middle of the explanation.

7. Form And Test Hypotheses

To achieve good results while debugging, you must adopt a more scientific, methodological approach and avoid any random changes.

Do the following

• Form a hypothesis about the root cause (ex, “I think the API is returning null when the user has no preferences…”).

• Experiment to verify it (add logging, set breakpoints, etc).

• Observe the result (confirm or reject the hypothesis).

• Fix the code based on what you learned.

• Verify the fix actually solves the problem.

• Repeat the cycle again with a new hypothesis if needed.

This systematic approach prevents you from going in circles and helps you build an understanding of your codebase.

Part 3: When You’re Stuck

8. Document Your Progress

When a bug is particularly hard, write down what you’ve tried.

Keep a running list of your experiments, hypothesis, and their results.

This prevents you from doing the same thing twice and expecting different results.

Documentation also makes it easier for others to help you.

You can easily ping a colleague, share your progress, and learnings so far.

You might also consider a tool like Multiplayer to annotate session replays with sketches and comments.

9. Take Strategic Breaks

This might sound counterintuitive, but stepping away from your laptop is sometimes the fastest way to solve a bug.

Taking a 15-minute walk allows your mind to rest and your subconscious to process the problem.

I can’t count how many times the solution to a difficult bug popped into my head while taking a walk, being at the toilet, or just making a drink.

There’s something about disengaging from the problem that allows your brain to make new connections.

10. Leverage AI Smartly

AI coding tools can be powerful debugging partners, especially if you give them the right information.

The right context is the key.

Try providing as much information about the bug as possible to your AI IDE and see how it could reason about it.

Of course, it’s not always correct, but you can quickly test and verify certain hypotheses.

Then, you could focus on the ones your AI coding tool hasn’t thought about.

It’s also helpful if you could share screenshots or session recordings to provide context.

I’ve personally tried Multiplayer’s integration.

I’ve used it to feed my AI assistant with a full-stack session recording, so it can see the full context of a problem.

After that, I wrote specific prompts and dug deeper into the problem.

AI is not a magic solution, but it’s a valuable debugging partner when given complete information.

Multiplayer provides Full Stack Session Recordings.

Here’s how it helps with debugging and fixing bugs:

• Capture full-stack session recordings.

• Annotate your replays with sketches and comments.

• Bring full-stack session recordings directly into your IDE.

• Give your AI coding tools all the context they need.

Access 1-month Free Trial

📌 TL;DR

• Reproduce the error consistently.

• Set up your environment to quickly reproduce the bug.

• Capture the full context and information.

• Isolate the problem.

• Use your debugger.

• Rubber duck the problem.

• Form and test hypotheses.

• Document your progress.

• Take strategic breaks.

• Leverage AI smartly.

Hope this was helpful.

See you next time!

Today’s action step: Take a look at your debugging process and see how you can apply at least one of the mentioned techniques.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28.5K+ subscribers this week 🙏

In Node.js, error handling relies on try-catch blocks and exceptions.

While this is a common way in Node.js apps, it creates an unpredictable control flow and hidden failure points.

A few years ago, I discovered the Result Pattern approach for handling errors, and it completely changed the way I look at error handling in Node.js applications.

The Result Pattern approach makes errors explicit, type-safe, and part of your function signatures.

In today’s article, I’ll dig deeper into the error handling and how to use the Result Pattern to better manage it.

Problems With Using Exceptions For Flow Control

Most Node.js applications rely on exceptions for error handling.

You throw errors when something goes wrong, and catch them somewhere up the call stack.

This favors the so-called fail-fast principle because you terminate the method execution immediately once you throw an exception.

With this approach, you make the caller responsible for handling the exception.

The problem is that the client of the method must know which exceptions to handle, which is not obvious from the method’s signature.

This makes exceptions invisible and creates an opportunity for bugs related to improper error handling of these exceptions.

Code becomes unpredictable since you’re not sure if the method throws an exception or not.

Here is a simplified example of creating an order:

Use Exceptions For Exceptional Situations

A good rule of thumb is to use exceptions for unexpected errors and exceptional situations.

You basically have two types of errors:

• Errors you know how to handle

• Errors you don’t know how to handle

You can use exceptions for the errors you don’t know how to handle. And you should catch and handle them at the lowest level possible.

For the errors you know how to handle, you could use the Result Pattern and handle the errors in a more functional way.

Make these types of errors explicit since you already know about them.

This way is more explicit and clearly shows that the method can fail.

The drawback is that the caller of the method has to check whether the operation succeeded or failed.

Using The Result Pattern For Better Error-Handling

The Result Pattern makes errors explicit and type-safe.

Instead of throwing exceptions, methods return a Result object that contains the success data or error information.

You can think of the Result as a container that holds one of two things:

• Success: Your data is inside.

• Error (or Failure): Information about what went wrong.

The key change here is that errors become values, not exceptions.

You can handle them like any other data in your program.

Here is an example of what the Result object might look like:

Applying the Result Pattern

Now that we have the IResult interface and utility methods, we could refactor the above-mentioned example by switching from using exceptions to the Result Pattern.

You can notice a few things as improvements:

• No more throwing exceptions.

• The return type of the method is explicit - using the IResult return type.

• It is clear what errors the method can return.

Another advantage of using the Result Pattern is that it simplifies the testing. It’s much easier to mock the Result object than to throw and handle exceptions.

As we said earlier, one drawback of the Result Pattern is its verbosity, as it might introduce more code compared to exceptions.

📌 TL;DR

• Exceptions are for exceptional situations.

• Use exceptions for errors you don’t know how to handle.

• Use the Result Pattern for errors you know how to handle, making the error handling more explicit and obvious.

• The Result Pattern allows you to handle errors more elegantly in a functional way, express the intent that the method could fail, and encapsulate the error inside.

So try out the Result Pattern and let me know how you found it.

I promise it will improve your code.

Hope this was helpful.

See you next time!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28K+ subscribers this week 🙏

You’re changing your current environment, including your teammates, office, and so on.

You’re also not sure how it would impact your career.

So yes, it’s a bit nerve-racking.

Till now, I’ve changed more than four tech companies, ranging from startups to big tech unicorns.

I’ve seen different onboarding plans and ways to kick off your “first impression” in your new workplace.

One of the biggest lessons I’ve learned for myself is:

Don’t rely on your company’s onboarding plan. Create one for yourself!

Regardless of the company's size and seasonality, there are many flaws.

It’s hard to create the “complete” plan for every new joiner.

That’s why it’s crucial to take ownership of your onboarding plan.

The effort you put in now will pay dividends for months.

A strong start makes you appear to be someone who cares.

This sense of ownership shows professionalism.

In today’s article, I’ll share ten lessons I’ve learned in my career on how to successfully onboard in your new company.

I also shared and applied these lessons with all the people I managed to onboard as an Onboarding Buddy.

I saw the work, so that’s why I’m sharing these lessons with you.

Before Day 1: Set Yourself Up For Success

If you have a long notice period, reach out to your future manager or team before you start.

Ask what you can do to prepare before your first working day.

When I did that at my last company, they sent me a Udemy course on microservices architecture - a core part of their tech stack.

On Day 1, I showed up already speaking “their language”.

This shows two things: you actually prepare and you signal you are proactive.

Also, start a work log or brag document from Day 1.

Write down what you’re working on, problems you solved, your wins, and impact.

This becomes invaluable for 1:1s, performance reviews, and promotion discussions.

You can read more about it here:

Week 1-4: Learn Fast, Contribute Faster

Ship Code Early

I truly believe in getting your hands dirty immediately.

Aim to ship something in the first week, even in the first few days.

You might fix a bug, add a small feature, improve something in the codebase, or even add a formatting or linting rule.

I’ve worked in both frontend and backend, so when I joined my last company, I looked for bugs I could fix in both areas.

In my first week, I managed to raise the bar high by making an impact by starting to deliver.

During my first retro, the team said like I’d been there for months, not days.

There’s usually a “capacity penalty” when someone new joins.

You reduce this penalty by contributing quickly.

Another tip here is to:

Maintain your focus while exploring the codebase.

Don’t try to understand the entire codebase from the beginning.

Pick one area and start from there.

Start Reviewing Code Immediately

You might not understand the business domain yet, but you can still add value.

You can still share tips and tricks on code reviews related to software design, architecture, and engineering practices, like readability, testing, etc.

This shows that you care.

You also build your credibility as an expert in a particular field.

As you learn more about the product, you can begin to question requirements and suggest more effective approaches.

Ask Questions; Ask Even More

Your questions reveal what you care about. Ask good ones!

For example:

• How do we make money?

• How do we handle payments?

• What are our team’s responsibilities?

• etc.

Ask your buddy, your mentor, your team, or people outside your team.

And try not to eat lunch alone.

I’m an introvert, so this was hard for me.

However, I tried to eat at least twice a week with people outside my team.

This way, I met more smart people, heard different perspectives, and learned about challenges across the company.

Align on Expectations

On your 1:1s with your manager, sit down and clarify your goals:

• What does success look like in my first month?

• What about the next three months?

• How to progress further in the career ladder?

Get specific.

Vague goals lead to vague results.

A good starting point is to create your 30-60-90 plan in a document.

This document maps out a new hire’s expectations from the perspective of the onboarding Team within the first 90 days of his new role.

🎁 Notion Template: Work Log (aka Brag List) Template For Software Engineers

Use this template to create your own work log (brag list) and list of accomplishments.

I want this!

Paid subscribers, you can get it here:

I want this FREE!

Month 2-3: Build Your Network and Increase Impact

Map The Organization

This is especially helpful for Senior+ roles.

The main idea here is to get to know the different teams, their responsibilities, and their core domains.

Since you’re new to the company, you have the perfect excuse to message someone from this team and ask what they’re working on:

“Hi, I’m new here, and I heard about your team lately. I’d love to learn what you work on and how our teams might interact…”

This is incredibly easy as a new person, and gets much harder later. Use this window.

Understand The Business, Not Just The Code

Learning the tech stack is one challenge.

Understanding the business and product domain is another.

The best engineers combine technical knowledge with business context.

If you don’t understand the product well, you can’t build the right solution.

If the product doesn’t work, the code doesn’t matter.

Talk to product managers and more experienced engineers.

Try to understand the business.

And try to work on high-impact things.

This isn’t always possible—sometimes you have to fix boring bugs—but communicate with your manager about your impact.

Use Your Fresh Perspective

You see things that others have become blind to.

Something that doesn’t make sense to you probably doesn’t make sense at all.

Others just got used to it.

When you spot something that could be improved, document it.
Better yet, fix it yourself if you can.

Seek opportunities to make a positive impact.

Apply your fresh perspectives not only to the code, but also to the current processes, including onboarding.

Accept The Entropy

Accept that many things won’t make sense at first, especially if you’re going from a small to → big company.

This is completely normal.

Give it time. It gets clearer.

📌 TL;DR

• Reach out to your manager before you start. Ask for materials to prepare.

• Start your brag document from day 1.

• Contribute code in week 1.

• Start code reviews immediately.

• Ask questions.

• Try to eat lunch with people from different teams.

• Align on goals with your manager.

• Map important teams.

• Learn the business, not just the code.

• Apply your fresh perspective.

Hope this was helpful.

See you next time!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 28K+ subscribers this week 🙏

Some time ago, I had an interview, which I almost failed.

The interviewer asked me questions like Promises and Event Loop.

I knew what they were, but I failed to clearly elaborate and explain them.

If you can’t explain it simply, do you understand it really well?

After the interview, I understood that some knowledge was missing.

I decided to dig deeper into JavaScript and fill my understanding and knowledge gaps.

I read many books and articles and took many notes along the way.

Every time I have a JavaScript interview, I review my notes to refresh my knowledge and prepare.

In today’s article, I’ll delve deeper into asynchronous programming in JavaScript, covering Promises, Async/Await, and the Event Loop.

This is part 4 of the “Ace Your Next JavaScript Interview” series.

If you missed the previous articles, see the bottom of this post.

Let’s dive in!

CodeRabbit: Free AI Code Reviews in CLI - Sponsor

CodeRabbit CLI is an AI code review tool that runs directly in your terminal. It provides intelligent code analysis, catches issues early, and integrates seamlessly with AI coding agents like Claude Code, Codex CLI, Cursor CLI, and Gemini to ensure your code is production-ready before it ships.

• Enables pre-commit reviews of both staged and unstaged changes, creating a multi-layered review process.

• Fits into existing Git workflows. Review uncommitted changes, staged files, specific commits, or entire branches without disrupting your current development process.

• Reviews specific files, directories, uncommitted changes, staged changes, or entire commits based on your needs.

• Supports programming languages including JavaScript, TypeScript, and more.

• Offers free AI code reviews with rate limits so developers can experience senior-level reviews at no cost.

• Flags hallucinations, code smells, security issues, and performance problems.

• Supports guidelines for other AI generators, AST Grep rules, and path-based instructions.

Get Started Today

Promises

A Promise is an object that allows us to take action when a future event happens.

It’s a placeholder for a value that will be available at some point in the future.

Imagine ordering food at a restaurant—you get a receipt (Promise) that represents your order, even though your meal is not ready yet.

Promises have three possible states:

• pending - the operation is still in progress

• fulfilled - the operation completed successfully

• rejected - the operation failed

Upon creation, the Promise takes a function that will be passed two arguments - a resolution callback and a rejection callback.

Most of the time, you’ll be consuming Promises rather than creating them.

The then() method is available on the Promise object and will run with the value passed to the resolve() function.

The catch() method runs if the reject() function was called.

One of the most powerful features of Promises is chaining.

If a then() handler returns another Promise, you can chain additional then() calls.

Async/Await

While Promises are powerful, the syntax can become hard to read and follow with complex chains.

The async/await keywords provide a syntax sugar over the Promises that will make your code read as if it were synchronous.

There are a few key points about async/await:

• You can only use await inside functions marked with async.

• Async functions always return a Promise.

• Use try/catch blocks for error handling instead of .catch().

• The code executed asynchronously despite looking synchronous.

Event Loop

Here is where things get really interesting.

JavaScript is single-threaded, meaning it can only do one thing at a time.

So how does it handle asynchronous operations without blocking the entire program?

The answer is its execution flow, which is based on an event loop.

On a high level, the engine runs an endless loop that checks if there are tasks waiting for it in a queue.

If there are, it executes them and continues to wait for more.

Any code that can’t run immediately is queued, and the execution continues until it exhausts the call stack.

setTimeout(() => {
  console.log('Later');
}, 1000);

console.log('Now');

// Output:
// Now
// Later (after 1 second)

Even with a zero timeout, the callback still runs after the synchronous code:

setTimeout(() => {
  console.log('Later');
}, 0);

console.log('Now');

// Output:
// Now
// Later (after 1 second)

The Event Loop manages two main areas:

• Call Stack - where your currently executing code lives.

• Task Queue - where asynchronous callbacks wait to be executed.

The Event Loop only processes the task queue when the call stack is empty.

setTimeout(() => {
  console.log('Later');
}, 0);

// This loop keeps the call stack busy
for (let i = 0; i < 100000; i++) {
  console.log(i);
}

// Output:
// 0
// 1
// 2
// ...
// 99999
// Later

The loop keeps adding items to the call stack and the event loop never gets a chance to reach the task queue.

When asynchronous calls are queued using the same method, for example, setTimeout, their execution order follows the order in which they were added.

setTimeout(() => {
  console.log('Later');
}, 0);

setTimeout(() => {
  console.log('Even Later');
}, 0)

// Output:
// Later
// Even Later

But if we queue a Promise and a call to setTimeout, the Promise will be the first to run.

setTimeout(() => {
  console.log('Later');
}, 0);

Promise.resolve().then(() => {
  console.log('Also Later');
});

// Output:
// Also Later
// Later

This is because promises and timeouts are put on two separate queues that have different priorities:

• Macrotask Queue (aka task queue) - setTimeout, setInterval, DOM events, etc.

• Microtask Queue (aka jobs queue) - Promise callbacks, queueMicrotask(), etc.

The event loop prioritizes the execution of pending microtasks.

Then the event loop will handle the next pending macrotask.

Immediately after every macrotask runs, the event loop will run all pending microtasks before continuing with the macrotasks again.

Here is a nice visualization I found on the Internet:

Let’s see one final code example to check your understanding:

console.log("start");

setTimeout(() => console.log("timeout"), 0);

Promise.resolve().then(() => console.log("Promise.resolve"));

new Promise((resolve, reject) => {
    resolve();
    console.log("executor");
}).then(() => console.log("promise"));

console.log("synchronous");

To see the answer, see the comments.

📌 TL;DR

• Promises give you a clean way to handle future values and chain async operations.

• Async/Await is a syntax sugar over Promises, giving you a simple mental model and making your code more readable.

• The Event Loop is a fundamental aspect of async programming in JavaScript.

• Event Loop handles async operations efficiently in JavaScript.

Hope this was helpful.

See you next time!

Ace Your Next JavaScript Interview Series

1. Scope, Hoisting, and Closures

2. Values, References, Coercion, and Equality

3. this, new, Prototypes, and Classes

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.7K+ subscribers this week 🙏

Over the last few years, I have managed to work with various software architectures, ranging from monoliths to microservices and their variations.

Each architecture had its own set of unique challenges, problems, and advantages.

And there is one architecture that really stood out—the Modular Monolith architecture.

Modular monoliths blend the simplicity and robustness of traditional monolithic applications with the flexibility and scalability of microservices.

I’d say that modular monoliths bring the best of both worlds.

The modular monolith architecture allows you to work in a unified codebase with clearly defined boundaries and independent modules.

This way, you can have high development velocity without the complexity of distributed systems.

In today’s article, I’ll share more about modular monolith architecture and why you should know about it.

CodeRabbit: Free AI Code Reviews in VS Code - Sponsor

CodeRabbit brings real-time, AI-powered code reviews straight into VS Code, Cursor, and Windsurf. It lets you:

• Get contextual feedback on every commit, not just at the PR stage

• Catch bugs, security flaws, and performance issues as you code

• Apply AI-driven suggestions instantly to implement code changes

• Do code reviews in your IDE for free and in your PR for a paid subscription

Install in VS Code for FREE

What is a Modular Monolith?

A modular monolith is a single deployable application that’s internally organized into well-defined and loosely-coupled modules.

The modules are split into logical boundaries, grouping related functionality together.

These modules communicate through well-defined, public APIs, events, or messages, instead of directly calling each other’s functionality.

These approaches promote modularity and separation of concerns, and improve the cohesion of the system.

You can think of modular monoliths as a microservices architecture packaged into one deployment unit.

This way, you get the organizational benefits of the service boundaries without the distributed system overhead.

Even if you want to scale one of the modules due to high traffic or other factors, you can easily extract the module and deploy it independently.

Modular monoliths give you this kind of flexibility.

What is a Modular Architecture?

To design a modular monolith, we must understand what a modular architecture is.

The core principles of modular architecture include:

• Separations of Concerns - Each module is independent, handling a specific business domain or business capability.

• Loose Coupling - Modules depend on interfaces, not implementations.

• High Cohesion - Related functionality stays together within modules.

• Explicit Interfaces - Clear contracts define how modules interact.

This means that each module:

• Must be independent.

• Must provide the required functionality.

• Must expose a well-defined interface to other modules.

The end goal is not to have 100% independent modules because this would mean that modules are not integrated together.

The main idea is to have loosely coupled modules and keep the number of dependencies low.

We can use a few techniques to keep the modules independent, like data isolation and linting rules, for example.

If we see that two modules communicate too much with each other, you might have incorrectly defined boundaries.

Then, you could consider merging the two modules together.

Remember:

A module is a grouping of related functionalities together that are accessed through a well-defined interface.

And once you have a modular architecture, you can easily extract modules into separate services.

Start With a Modular Monolith

In recent years, developers have favored the microservices architecture.

Yes, it provides many benefits like better scalability, clear service boundaries, independence, and much more.

But, it does come with a big cost - complexity.

I’d say that most teams and companies would be better off starting with a monolith application.

As Martin Fowler says:

You shouldn't start a new project with microservices, even if you're sure your application will be big enough to make it worthwhile.

And even better, consider starting with a modular monolith.

When you’re building a new system, you’re making countless architectural decisions with incomplete information.

You don’t fully understand your users patterns, scaling needs, domain boundaries, etc.

Starting with microservices in these early days will lock you into these often incorrect assumptions.

Even big players like Shopify and Google bet on modular monoliths.

You can read this paper from Google about “Towards Modern Development of Cloud Applications”.

In this paper, Goggle identifies five main challenges with microservices:

• Performance - Sending data between services over the network slows everything down, especially when you split your app into too many pieces.

• Correctness - Most big failures happen when different versions of services try to talk to each other and mess up.

• Management - Have to manage multiple different applications, each with its release schedule.

• Frozen APIs - Once you create an API between services, it’s really hard to change it without breaking everything else.

• Development Velocity - When you need to make changes across multiple services, you can’t just deploy them all at once - you have to coordinate carefully.

As you see, the cost of starting with microservices is high.

So starting with a modular monolith sounds compelling.

I also recommend reading about the fallacies of distributed computing if you’re unfamiliar with them.

Remember:

You can easily migrate from a modular monolith architecture to a microservices architecture because each module is well defined, isolated, and separated.

Benefits of a Modular Monolith

Modular monoliths have multiple benefits.

Here are the ones I consider the most important:

• Simplified deployment - You build, test, and deploy one application instead of multiple services across different environments.

• Improved performance - Communication between modules happens through fast in-memory calls, instead of slow network requests.

• Enhanced development velocity - You have a single codebase to manage which simplifies the debugging and the overall development process.

• Easier transaction management - Managing transactions in a distributed systems is very challenging. With modular monoliths you use a single database and transactions are much simpler.

• Lower operational complexity - Modular monoliths reduce the operational overhead that comes with managing and deploying a distributed microservice system.

• Easier transition to microservices - Well-defined module boundaries make it straightforward to extract individual services and use microservices.

Monolith vs. Modular Monolith vs. Microservices

The biggest difference between modular monoliths and microservices is how they’re deployed.

Microservices use physical boundaries between services, while modular monoliths use logical boundaries.

With microservices, you have a clear strategy for modularity and structuring bounded contexts.

But, you can achieve this without building a distributed system.

The main problem is when people try to enforce code boundaries using microservices.

Instead, you can build a modular monolith to get almost the same benefits.

Modular monoliths give you high cohesion, low coupling, data encapsulation, focus on business functionalities, and more.

Microservices also give you independent deployments, independent scalability, and the ability to use a different tech stack per service.

You can think of the difference as a well-organized apartment (modular monolith) vs. a neighborhood of separate houses (microservices) - both have clear boundaries, but one is much simpler to maintain.

Choose microservices for the benefits, not because your monolithic codebase is a mess.
— Simon Brown

📌 TL;DR

• Modular monoliths offer a compelling way to structure applications.

• Modular monoliths offer most of the benefits of microservices without the complexity of distributed systems.

• Modular monoliths offer a smooth way to transition to microservices if needed.

• The main difference between microservices and modular monoliths is how they are deployed.

Hope this was helpful.

See you next week!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.7K+ subscribers this week 🙏

Code review is a process that allows others to review your code changes.

The person who submits the code changes is referred to as the “Author”, while those reviewing the changes are referred to as “Reviewers”.

The primary purpose of code reviews is to:

Enhance the quality of the released solution and improve collaboration and knowledge transfer within the team.

However, doing code reviews right is not an easy task.

There are many problems related to code reviews, like wasted human effort and time, wrong focus → wrong results, communication breakdown, criticism, decreased developer productivity, and team velocity.

In today’s article, I’d like to share several code review guidelines, both for Authors and Reviewers, that I've seen working in teams and companies.

Let’s dive in!

The Hidden Cost of Broken Code Reviews

1. Reviews Become Time Sinks

• The average PR takes 2-4 days from submission to merge.

• Teams spend 8-12 hours per week on code reviews instead of building features.

2. Wrong Focus → Wrong Results

• Developers spend 50% of review time on formatting, naming conventions, and style preferences.

• Meanwhile, logic bugs, security vulnerabilities, and performance issues slide past because reviewers are mentally exhausted from nitpicking.

3. Communication Breakdown

• Authors write vague PR descriptions.

• Reviewers give unclear feedback and/or criticize the author.

• Nobody knows if an issue is critical or optional.

• Simple fixes turn into multi-day discussions.

• The cost isn’t just velocity—it’s team morale, code quality, and customer trust when bugs reach production.

Code reviews are expensive since there are many people involved in this activity.

That’s why I’m happy to partner with CodeRabbit on this newsletter.

With the help of CodeRabbit, I believe we can make them cheaper by automating the process, fixing the obvious problems, and focusing on the right things.

Try CodeRabbit

Best Practices for Authors:

• Review your own code changes and PR first before sharing with others.

  • Remove debug statements and commented code.

  • Check for obvious bugs or typos.

  • Consider using CodeRabbit for giving instant feedback.

    

• Ensure consistent naming and formatting.

  • Especially if your company follows a style guide.

• Test your code changes.

  • Both manually and with automated tests.

• Know what each new line does.

  • This is very crucial in the era of vibe coding.

• Automate the easy stuff.

  • Add formatters, linters, and rules to prevent nitpicking.

  • Consider using CodeRabbit for finding potential issues.

    

• Keep your code changes and PR small.

  • Research shows that review quality drops dramatically with the increasing number of files, lines, and changes. Ex: 400+ lines.

  • If your feature needs more code, break it into logical steps that can be reviewed independently.

• Write a clear PR description. Try to answer the questions:

  • What - “Add rate limiting to login endpoint...”

  • Why - “Prevent brute force attacks…”

  • How - “Implement rate limiting algorithms, block IPs…”

  • Testing - “Tested with 100 concurrent requests and verified…”

  • For visual changes, include relevant screenshots and/or videos that showcase the changes.

  • For bug fixes, outline the Before and After behaviors, and how you fixed them.

  • Consider using CodeRabbit for generating a summary of the changes.

    

• Document the non-obvious changes.

  • Try to answer questions with the code itself.

• Respond graciously to critiques.

  • Remember, it’s not about you, it’s about the code.

• If you’re confused, ask clarifying questions.

  • Don’t guess, ask questions instead.

  • Ex: "When you say 'this could be cleaner, ' do you mean splitting this function or renaming the variables?"

• Be patient when your reviewer is wrong.

  • Reviewers might be wrong due to a lack of context or experience, so try to provide it and help them understand your perspective.

• Minimize the lag between rounds of review.

  • Acknowledge feedback within 4 hours, even if you can’t fix everything immediately.

  • Quick responses show respect for your reviewer’s time.

• Consider doing a pair programming session with the reviewer if needed.

  • Peer code reviews work as a two-way transfer of knowledge when conducted carefully.

  • Both the reviewer and the author can learn new things, either for the project or in general.

Best Practices for Reviewers:

• Review PRs within 24 hours of submission.

  • This not only unblocks the author to merge their code but also speeds up the development process.

• Prioritize your review using this framework:

  • Correctness: Does the code work as intended?

  • Organization: Is it well-structured, maintainable, and follows the style guides?

  • Readability: Can the team and future me understand and modify this later?

  • Reliability: Is the solution fault-tolerant?

  • Scalability: Can the solution grow to accommodate higher future load?

  • Edge cases: What could go wrong in production?

• Prioritize your feedback:

  • Critical (must fix) - logic errors and bugs; security vulnerabilities; breaking changes; performance bottlenecks.

  • Important (should fix) - poor code organization; missing error handling; inadequate tests.

  • Suggestions (optional) - alternative implementations; style improvements; minor optimizations.

• Don’t make it personal! Review the code, not the author.

• Learn to give better feedback. Ask, don’t tell!

  

  • When you add a comment, have a strong WHY and a suggestion.

  • Mark more comments as NIT and don’t block PRs.

• Praise the good things.

  • Engineers, and people in general, tend to criticize when doing any kind of review, while forgetting to mention any good.

  • For the reviewer to be able to learn from the author, he should pay attention to the clever code as well, and it is a good habit to notice it.

• Consider doing a pair programming session with the reviewer if needed.

  • Sometimes, it’s better to sit together and resolve all issues instead of going through multiple rounds of reviews.

• When critical issues are resolved and code is “good enough” → Approve it.

• Code review is part of your job.

  • If you're not doing code reviews regularly, you are letting your teammates down.

CodeRabbit is an AI code review tool to reduce developer workload.

Here’s how it helps with code review flow:

• Do routine checks and reduce the time spent on reviews from days to minutes. Thus, improving developer velocity.

• Do consistent reviews without getting tired or biased. Thus, it reduces the risk of missing important issues due to human mistakes.

• Provide mentorship to junior engineers through detailed feedback.

Put simply, CodeRabbit complements human reviewers. It serves 1+ million repositories and has reviewed over 10 million pull requests. And it remains the most installed app on GitHub and GitLab.

📌 TL;DR

• Guidelines for Authors:

  • Review your own code changes and PR first.

  • Ensure consistent naming and formatting.

  • Test your code changes.

  • Know what each new line does.

  • Automate the easy stuff.

  • Keep your code changes and PR small.

  • Write a clear PR description.

  • Document the non-obvious changes.

  • Respond graciously to critiques.

  • If you’re confused, ask clarifying questions.

  • Be patient when your reviewer is wrong.

  • Minimize the lag between rounds of review.

• Guidelines for Reviewers:

  • Review PRs within 24 hours of submission.

  • Prioritize your review using a framework and quality attributes.

  • Prioritize your feedback.

  • Don’t make it personal! Review the code, not the author.

  • Learn to give better feedback. Ask, don’t tell!

  • Praise the good things.

  • When critical issues are resolved and code is “good enough” → Approve it.

  • Core reviews are part of your job.

Hope this was helpful.

See you next week!

Today’s action step: Take a look at your code review process and highlight areas for improvement. Try to follow or incorporate one of the mentioned tips in your daily routine.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.5K+ subscribers this week 🙏

Clean Code is code that is easy to read, maintain, test, and understand.

Clean Functions are the foundation of Clean Code.

Master clean functions and you’ll naturally write better software.

In today’s article, I’ll share 8 practical tips for writing clean functions that I follow daily in my projects and work.

Let’s dive in!

Cut Code Review Time & Bugs in Half - Sponsor

CodeRabbit is your AI-powered code review co-pilot.

It provides instant, contextual feedback on every PR, along with one-click fix suggestions. It has reviewed over 10 million PRs and is used in 1 million repositories.

Besides, it’s free to use for open-source repos; 70K+ open-source projects already use it.

CodeRabbit lets you instantly spot:

• Logic & syntax bugs

• Security issues (XSS, SQL injection, CSRF)

• Concurrency problems (deadlocks, race conditions)

• Code smells & readability concerns

• Best practice violations (SOLID, DRY, KISS)

• Weak test coverage & performance bottlenecks

Write clean, secure, and performant code with CodeRabbit.

Try CodeRabbit Now

#1: Keep Your Functions Small And Focused

Functions that do multiple things are hard to follow, understand, test, debug, and even reuse.

When something breaks, it’s very hard to pinpoint the exact part that failed.

When requirements change, and they do change regularly, you risk breaking the whole function and unrelated functionality.

In the Clean Code book, Uncle Bob says:

The first rule of functions is that they should be small.
The second rule of functions is that they should be smaller than that.

So each function should have one clear responsibility.

Sometimes a function might be just 5 lines of code, while other times it might be 50 lines of code to fulfill a single responsibility.

If you can describe what your function does with “and”, it probably does too much.

There’s no universal rule to draw the line.

Trust your experience and your judgment based on the context you have.

Be pragmatic. Don’t be dogmatic.

#2: Name Functions to Reveal Intent

Function names like process() or handle() force readers to examine the implementation to understand what the function does.

This slows down code reading and increases the cognitive load.

Function names should clearly state what they do with action verbs.

A good function name should answer:
“What action does this perform?” and “What does it return?”

You can also follow these tips:

• Use terms and language based on the specific domain, so your functions are more tailored to the business context.

• Follow the already established naming conventions.

• Use verbs and verb phrases for actions (calculate, validate, send).

• Use question words for boolean functions (is, has, can).

• Be consistent with the naming, so you don’t use two words for the same thing.

#3: Return Early to Avoid Nesting

Deeply nested functions create a “pyramid of doom”, which is hard to follow, debug, and understand.

Your brain has to track multiple logical branches simultaneously.

The main business logic gets “hidden”, making it hard to find.

To fix this, you can use the early return principle.

You can handle edge cases and invalid inputs using guard clauses.

This removes the many levels of branches, keeping the “happy path” obvious, clear, and easy to follow.

#4: Limit Function Parameters

Functions with many parameters are a cognitive load.

You can’t remember parameter order, and it’s easy to pass the wrong values.

To improve this, group related parameters into objects.

This reduces cognitive load and makes parameter order irrelevant.

#5: Write Pure Functions When Possible

Functions with side effects are unpredictable.

They might work differently based on a global state, making them hard to test and debug.

You can’t reason about them in isolation.

They also cause mysterious bugs in unrelated parts of the system.

To mitigate this problem, strive to write functions that depend only on their inputs and produce no side effects.

Pure functions are predictable, testable, and can be safely called from anywhere.

And we can also run them in parallel.

#6: Avoid Boolean Parameters

Boolean parameters make function calls unclear and hard to extend.

When you see processOrder(order, true), you can’t tell what true means without checking the function definition.

Boolean flags also often indicate that a function is doing two different things.

A better approach is to use objects, enums, or separate functions instead of single boolean flags.

This makes your code self-documenting and easier to extend.

#7: Return Results, Not Exceptions

Using exceptions for expected failures makes error handling invisible and easy to forget.

Callers don’t know what can go wrong just by looking at the function signature.

This leads to unhandled edge cases and application crashes.

To fix this, apply the Result Pattern and make errors part of your return type.

This forces callers to handle error cases and makes your function’s behaviour predictable and explicit.

A good rule of thumb is:

Use Result Pattern for expected errors to make them explicit.

Use Exceptions for unexpected errors and exceptional situations.

#8: Replace Magic Numbers and Strings

A common code smell is the use of magic numbers and strings.

These hardcoded values create a maintenance nightmare.

When business requirements and rules change, it’s very hard to find every occurrence of these numbers or strings.

Another big problem with these magic numbers and strings is the lack of meaning.

To fix this problem, extract the numbers into constants and the strings into enums.

📌 TL;DR

That’s all for today, 8 tips to write clean functions:

• #1: Keep Your Functions Small And Focused

• #2: Name Functions to Reveal Intent

• #3: Return Early to Avoid Nesting

• #4: Limit Function Parameters

• #5: Write Pure Functions When Possible

• #6: Avoid Boolean Parameters

• #7: Return Results, Not Exceptions

• #8: Replace Magic Numbers and Strings

Hope this was helpful.

See you next week!

Today’s action step: Take a look at your project and see if you’re making some of the mistakes I highlighted here. Try to fix them using the clean code tips I shared with you.

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.4K+ subscribers this week 🙏

When I see people who are not sold on TypeScript, I show them code like this:

The moment you reference a property from an object, you are using a type.

You rely on the object to have a specific structure.

It’s better to make it obvious and describe it.

Yes, writing TypeScript takes a bit more effort, but that work pays off in the future, especially with the maturity of the project.

Remember: We ship faster when we break fewer things. TypeScript helps you do that.

In today’s article, I’d outline several benefits of why you have to use TypeScript in your projects.

CodeRabbit: Cut Code Review Time & Bugs in Half - Sponsor

Code reviews are critical but time-consuming. CodeRabbit acts as your AI co-pilot, providing instant Code review comments and potential impacts of every pull request.

Beyond just flagging issues, CodeRabbit provides one-click fix suggestions and lets you define custom code quality rules using AST Grep patterns, catching subtle issues that traditional static analysis tools might miss.

CodeRabbit has so far reviewed more than 10 million PRs, installed on 1 million repositories, and used by 70 thousand Open-source projects. CodeRabbit is free for all open-source repos.

Get Started Today

1. Design Better Systems with Type-Driven Development

A good way to use TypeScript is to start by defining your domain types, not implementation.

When you describe your data in your system clearly, you can see gaps in your understanding before writing any logic.

This is the so-called “type-driven development” where you start with the types, which makes the blueprint of the feature.

For example, imagine a Product type that requires at least one price.

With this structure, you can’t create a Product without a price.

By outlining that with types, we make illegal states unrepresentable, removing an entire set of bugs.

Those types also serve as a living documentation and source of truth of the current system’s state.

2. Productivity Benefits: Auto-Completion & Error Detection

TypeScript’s compiler and IDE support give you immediate feedback.

If you mistype a property or call a method with the wrong type, the editor warns you before you hit “run”.

Optional properties and return types are checked too.

For example, if a function is supposed to return a string but may return undefined, the compiler points that out.

This kind of feedback reduces the time spent debugging and hunting down runtime errors.

Another great advantage is the auto-completion.

Because your editor knows the types of your variables, it can suggest valid methods and properties.

This significantly improves the Developer Experience, speeding up the coding process.

3. Long-Term Code Quality And Team Benefits

Large codebases and growing teams amplify the cost of mistakes.

TypeScript acts as a safety net that scales with your organization.

When you change a contract, TypeScript highlights every place you need to update.

When LinkedIn evaluated TypeScript adoption, they found that even a small conversion would catch about a quarter of all the JavaScript errors in their apps.

TypeScript makes implicit contracts explicit:

• Function signatures document expected inputs and outputs

• Interface changes highlight all affected code

• Refactoring becomes mechanical rather than error-prone

Clear type information makes code easier to understand, navigate, maintain, and debug.

This increases the capacity to add new features and fix bugs.

In short, investing in types now pays off through faster development later.

4. Trade-Offs And Downsides

Using TypeScript does add complexity.

You have to learn the syntax, maintain type definitions, and configure a tsconfig file.

There are also some packages that lack good types.

In recent years, however, tooling and package support have improved tremendously.

Most developers can rely on type inference instead of writing complex generic types.

You also don’t need 100% perfect types to get 99.9% of the value.

There are escape hatches, such as using any or unknown in a limited scope.

As long as you are careful, you can retain almost all the benefits while avoiding diminishing returns.

📌 TL;DR

• TypeScript adds types to JavaScript, helping you catch mistakes before they reach your users.

• Embrace “type-driven development” by outlining your types and data structures before writing any logic. This helps to reveal blind spots and misunderstandings.

• TypeScript enables auto-completion and instant feedback, improving the Developer Experience and speeding up coding.

• Better code quality and teamwork.

• If the type system gets in your way, cheat by using any or unknown. It’s not necessary to have 100% perfect types.

• Using TypeScript may slow you down now, but the investment is worth it. It results in cleaner, more reliable software that can evolve without chaos.

That's all for today. I hope this was helpful. ✌️

How Can I Help You Further?

Learn how to build clean, maintainable, and testable React Applications! 🚀

Check the book out!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 27.3K+ subscribers this week 🙏

And most probably you’re doing it through an IDE.

In my case, I use VS Code or Cursor, which is a fork of VS Code.

It’s beneficial if your IDE works for you, not against you.

Tuning your IDE by adding helpful extensions can boost your productivity.

In today’s article, I’ll cover some of my favorite VS Code extensions I use daily to speed up my work.

PS. These extensions are general-purpose, regardless of the language.

1. Code Spell Checker

Code Spell Checker is a basic spell checker which works pretty well with code.

It helps to catch common spelling errors, typos, and mixing alphabets from different languages.

For example, imagine using `a` and `а`.

They look the same but the IDE and your code won’t treat them the same way.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

2. EditorConfig for VS Code

This plugin attempts to override user/workspace settings with settings found in `.editorconfig` files.

It’s very helpful when you work on projects with different settings that are different than the ones you have by default in your IDE.

For example, in my personal projects, I use two spaces as indentation but as consultant I’ve worked on many legacy projects with four spaces as indentation.

Using the `.editorconfig` file in such projects made my life much easier.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

3. GitLens — Git supercharged

GitLens enhances your workflows with powerful Git functionality like in-editor blame annotations, hovers, CodeLens, and more—all fully customizable within VS Code.

It’s a must-have extensions if you’re using Git, in my opinion.

One of its coolest features is to see by whom a line was edited and directly jump to the Pull Request or Merge Request to further inspect it.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

4. VS Code Icons

It brings real icons to your VS Code.

It makes it much clear what files and folders you have in your project and what are their types.

So navigation throughout the project becomes a bit easier.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

5. Error Lens

ErrorLens turbo-charges language diagnostic features by making diagnostics stand out more prominently, highlighting the entire line wherever a diagnostic is generated by the language and also prints the message inline.

It’s really handy to see immediate clear feedback from your changes which speeds up the feedback loop and code iterations.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

6. Indent Rainbow

It’s a simple extension to make indentation more readable.

This extension colorizes the indentation in front of your text, alternating four different colors on each step.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

7. MarkdownLint

In my experience, I use markdown files in repositories for documentation.

Getting my markdown files correct is a must.

VS Code has basic Markdown support out-of-the-box (e.g, Markdown preview), please see the official documentation for more information.

However, we don’t have a linting for the markdown files to ensure consistency and

MarkdownLint plugin helps with linting and style checking for your markdown files.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

8. Path Intellisense

This plugin autocompletes filenames.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

9. GitHub Copilot Chat

Using a LLM and a chatbot for coding has become the de facto standard.

So if you’re not using one already, you’re falling behind.

In VS Code, you can use GitHub Copilot for FREE.

Of course, it has some limitations, but still you can take advantage of it.

You can find the extension both directly in the IDE Extensions Tab or in the Marketplace (link).

If you’re using Cursor, you won’t need it, since it has its own autosuggestion and AI functionality.

📌 TL;DR

• Code Spell Checker

• EditorConfig for VS Code

• GitLens — Git supercharged

• VS Code Icons

• Error Lens

• Indent Rainbow

• MarkdownLint

• Path Intellisense

• GitHub Copilot Chat

That's all for today. I hope this was helpful. ✌️

How I can help you further?

Learn how to build clean, maintainable, and testable React Applications! 🚀

Check the book out!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 26.9K+ subscribers this week 🙏

You can also hit the like ❤️ button at the bottom to help support me or share this with a friend. It helps me a lot! 🙏

It defines what data your clients can request, how they will receive it, and how they can modify it.

Good schema design makes your API easy to use, predictable, and maintainable.

In the past, I’ve designed several production-ready GraphQL schemas that lasted in time.

I saw and learned what worked well and what didn’t.

In today’s article, I’ll discuss the key principles, rules, patterns, and design considerations that worked well for me in the past.

1. General Principles

1.1 YAGNI (You Aren’t Gonna Need It)

Keep your API minimal.

Expose fields and use cases only when needed.

Deprecate the fields that are not being used anymore.

Fewer fields means less surface are for bugs, simpler documentation, and easier client development.

1.2 Completeness

Keep your schema minimal, yet complete.

Clients should be able to achieve their use cases completely.

A complete schema saves clients from multiple APIs, requests, and keeps data fetching efficient.

1.3 Embed Domain Knowledge

Encode as mush as possible and as clearly as possible the domain knowledge in the schema.

Your names should match the domain knowledge and language.

Domain-Driven schemas are much easier to deal with, especially for newer developers to understand the business domain.

1.4 No Implementation Details

The API should focus on the Domain and Client use cases.

Implementation details must be hidden.

2. Naming Conventions

2.1 camelCase For Fields & Inputs

Field names and inputs should use camelCase.

Same as we do in JavaScript.

type User {  
  firstName: String!  
  lastName: String!  
}

2.2 PascalCase For Types & Enums

Type names should use pascalCase.

This matches how classes are defined in JavaScript.

type OrderDetail { ... }  
enum PaymentMethod { CREDIT_CARD, PAYPAL }

2.3 ALL_CAPS For Enum Values

Enum values should use ALL_CAPS, because they are similar to constants.

enum Role { ADMIN, EDITOR, VIEWER }

2.4 Use Create/Update/Delete In Mutations

Use Create/Update/Delete in mutations instead of they synonyms, unless you have a specific reason to use another verb.

type Mutation {  
  createUser(input: CreateUserInput!): CreateUserPayload  
  deletePost(input: DeletePostInput!): DeletePostPayload  
}

2.5 Avoid Abbreviations

Prefer to be explicit about names.

3. Fields And Mutations

3.1 Default Values

Use default values to make an API more predictable and communicate intent.

type Query {
  # ⛔ Bad
  products(first: Int!, orderBy: ProductsOrdering)

  # ✅ Good
  products(first: Int!, orderBy: ProductsOrdering = CREATED_AT)
}

3.2 Explicit Side-Effects

Avoid implicit and surprise side-effects in fields and mutations.

The name should convey what it does at runtime.

3.3 Mutation Naming: verbEntity

Name mutations using verbEntity (and not entityVerb).

# ⛔ Bad
userInvite

# ✅ Good
inviteUser

3.4 Single-Purpose Fields

Do one thing, and do it well.

Prefer specific solutions rather than overly clever and generic fields.

3.5 Beyond CRUD

Think beyond CRUD.

Use action or behavior specific fields and mutations to help clients use your API.

# ⛔ Bad
updatePost(input: {..., archived: true }) {
  ... 
}

# ✅ Good
archivePost(input: { postID: "abc" }) {
  ... 
}

3.6 Input & Payload Types

Use Input and Payload types for mutations.

Use specific object types for mutation inputs and outputs.

Use *Input suffix for input and *Payload suffix for the result.

type Mutation {
  # ⛔ Bad
  createProduct(name: String!): Product

  # ✅ Good
  createProduct(input: CreateProductInput!): CreateProductPayload
}

3.7 Don’t Reuse Types Across Mutations

Don’t reuse input and payload types across multiple mutations.

This prevents accidental coupling.

3.8 Use Non-Null With Care

Use Non-Null mostly on scalar fields and use them with care on associations.

Non-Nullable mean that the field must never be null.

If it is null for any reason, GraphQL will return error without the data.

type User {
  # Prefer nullable associations, especially if backed by external services
  profilePicture: ProfilePicture

  # Scalars are usually safer
  name: String!
}

You can read more about nullability here.

3.9 Prefer Required Arguments

Prefer a strong schema rather than runtime checks.

Use more specific fields if needed.

type Query {
  # ⛔ Bad
  userByNameOrID(id: ID, name: String): User

  # ✅ Good
  userByName(name: String!): User
  userByID(id: ID!): User
}

4. Error Handling

4.1 GraphQL Errors For Global Issues

Use GraphQL Errors for developer-facing global errors.

Example where to use such errors: internal (unexpected) server errors, timeouts, auth, schema validation, etc.

4.2 Error Extensions

Use GraphQL Error extensions to encode additional information.

Always provide a unique “code”.

This helps the client to decide what to do based on the “code”, instead of the error message.

{
  "errors": [
    {
      "message": "The current user does not have permissions for: ...",
      "extensions": { 
        "code": "UNAUTHORIZED"
      }
    }
  ]
}

4.3 User-Facing Errors in Schema

Use user errors, or errors-in-schema, for user-facing errors.

Use the schema instead of top-level errors for errors that are meant to be displayed to the user.

{
  "errors": [
    {
      "message": "Invalid input arguments.",
      "extensions": { 
        "code": "BAD_USER_INPUT",
        "errors": [
          { "field": "email", "message": "Email already registered" }
        ]
      }
    }
  ]
}

5. Identification

5.1 Global IDs

Every type that implements the Node interface must define a unique and global ID.

Those IDs are opaque so that it is clear they are not intended to be decoded on the client.

5.2 Rich ID Encoding

Encode enough information in IDs for global fetching.

Prefer encoding more that not enough for evolution.

This might mean including the parent object id, the shard key, etc.

📌 TL;DR

• General Principles

  • YAGNI (You Aren’t Gonna Need It)

  • Completeness

  • Embed Domain Knowledge

  • No Implementation Details

• Naming Conventions

  • camelCase For Fields & Inputs

  • PascalCase For Types & Enums

  • ALL_CAPS For Enum Values

  • Use Create/Update/Delete In Mutations

  • Avoid Abbreviations

• Fields And Mutations

  • Use Default Values

  • Prefer Explicit Side-Effects

  • Mutation Naming: verbEntity

  • Prefer Single-Purpose Fields

  • Think Beyond CRUD

  • Input & Payload Types

  • Don’t Reuse Types Across Mutations

  • Use Non-Null With Care

  • Prefer Required Arguments

• Error Handling

  • GraphQL Errors For Global Issues

  • Error Extensions

  • User-Facing Errors in Schema

• Identification

  • Use Global IDs

  • Rich ID Encoding

That's all for today. I hope this was helpful. ✌️

How I can help you further?

Learn how to build clean, maintainable, and testable React Applications! 🚀

Check the book out!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 26.8K+ subscribers this week 🙏

You can also hit the like ❤️ button at the bottom to help support me or share this with a friend. It helps me a lot! 🙏

We often read about SOLID principles, Clean Code, and other best practices.

These practices help us write code that is easy to change and extend.

Yet in real life, many projects and codebases fall into the opposite trap.

Let’s call this pattern the “F.L.U.I.D” code.

This code is Fragile, Lax, Untested, Insecure, and Disorganized.

Understanding these anti-patterns helps us identify problems early on and take corrective action to get the project back on track.

What Is F.L.U.I.D. Code?

FLUID is an acronym for five key ways a code can go wrong.

1. Fragile

2. Lax

3. Untested

4. Insecure

5. Disorganized

When code exhibits one of these traits, it often drags in the others.

For example, a fragile module that breaks easily will also be hard to test and secure.

By recognizing the aspects of FLUID code teams can learn to spot bad traits of the code and change the trajectory.

Fragile Code

Fragile code is code that is easily broken by unrelated changes or updates.

A small tweak in one module can trigger many bugs in other modules and features.

Fragile code breaks in unexpected ways.

When teams are dealing with fragile code, they start to lose confidence in the codebase.

They spend more time firefighting bugs and tracing problems, instead of building features and delivering value.

Teams become reluctant to touch or change a piece of code because of the fear of not breaking something else.

And this is contagious if not spotted on time and acted upon it.

⛔ Fragile Code might come from:

• tight coupling between modules

• large functions with many responsibilities

• no clear boundaries or interfaces

• lack of tests

✅ How to start fighting Fragile Code:

• extract responsibilities into small, focused, and manageable functions

• define clear interfaces and public methods

• start writing tests (even simple ones) to prevent regressions

Lax Coding Standards

Inconsistent style across the codebase makes the code harder to read, follow, maintain, and even review.

When everyone has their own conventions and way of writing code, the codebase becomes a frankenstein.

It becomes a nightmare to onboard new team members and merge pieces of code and functionality.

⛔ Lax Coding Standards might come from:

• no agreed upon style guide

• lack of automated tooling (formatters, linters, etc)

• weak or absent code review process

✅ How to start fighting Lax Coding Standards:

• adopt a common style guide or create one for your team and company

• enforce formatting with tools like ESLint, Prettier, etc.

• include style check in your CI pipeline

Untested Code

Without tests, you don’t know if a change breaks an existing behavior or not.

You can’t be confident if product work as expected after your changes.

You might wait for customers to complain but this strategy might cost the company a lot - loosing existing customers and money.

There are also teams that apply “test in production” behavior but this strategy can’t give you strong confidence and could also lead to many outages.

⛔ Untested Code might come from:

• tight deadlines and pressure to ship

• no testing culture and rules or skills gap

• legacy code without a testing framework

✅ How to start fighting Untested Code:

• start small and simple - add a few tests to cover core flows and scenarios

• integrate a testing framework (like Jest, Vitest, etc)

• require tests for new features or bug fixes before merging

Insecure Code

Security flaws can let attackers steal data and shut down the whole system.

A single vulnerability inside the codebase might cost millions of dollars to the company - from legal fines to reputation damage and losing customers.

Imagine a login endpoint which fails to sanitize user input, allowing SQL injection.

This can let the attacker dumb the entire database in seconds.

Investing in security early on saves time and money in the long term.

⛔ Insecure Code might come from:

• skipping input validation

• implementing your own auth instead of using proven libraries

• no static analysis or security audits

✅ How to start fighting Insecure Code:

• validate and sanitize all input

• use battle tested libraries for encryption and authentication

• automate security scans (ex: Snyk)

Disorganized Codebase

A messy project is hard to navigate and reason about.

Developers waste time searching for files and features or tracing down duplicate code.

Then can even wonder where to put the new functionality.

Imagine a developer trying to build a new feature but can’t find whether an existing utility function is present or not.

So he decides to build his own, wasting time and effort.

This type of mindset can lead to enormous technical debt which will be very hard to pay down with the time going.

New hires might also get lost inside the codebase.

Clear and organized codebase improves the overall team efficiency and onboarding speed of new colleagues.

⛔ Disorganized Code might come from:

• no agreed upon folder or module structure

• large “god classes” with thousands of lines

• copy-pasted code, instead of shared utility functions or modules

✅ How to start fighting Disorganized Code:

• define a clear project layout (ex: Bounded Contexts, feature-based modules, page-based folders, etc)

• enforce module boundaries and single responsibilities

• regularly review and pay down tech debt, remove dead or duplicate code

The Vicious Cycle of F.L.U.I.D. Code

Each FLUID trait in the code fuels the others.

Fragile code is hard to test, so it remains untested.

Untested code hides security holes, so it remains insecure.

Insecure code requires quick patches leading to lax coding standards.

And lax coding standards might lead to chaotic and disorganized codebase.

Over time, a once clean codebase becomes a FLUID trap.

📌 TL;DR

• FLUID - anti clean code pattern; Fluid, Lax, Untested, Insecure, Disorganized.

• Fragile Code - small changes break other features, causing many bugs; teams start to fear making changes in the code.

• Lax Coding Standards - no shared style guide; poor code reviews and many merge conflicts.

• Untested Code - no automated tests; might lead to production regressions.

• Insecure Code - skips input validation and sanitization; security breaches.

• Disorganized Code - no clear project structure; duplicate code; confusion in team members.

That's all for today. I hope this was helpful. ✌️

Credits to Kristijan Kralj who inspired me about FLUID code.

How I can help you further?

Learn how to build clean, maintainable, and testable React Applications! 🚀

Check the book out!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 26.5K+ subscribers this week 🙏

You can also hit the like ❤️ button at the bottom to help support me or share this with a friend. It helps me a lot! 🙏

This is part 3 of the “Ace Your Next JavaScript Interview” series where I cover the fundamentals of JavaScript, sharing my notes which I use to review and prepare for interviews.

In today’s article, I’ll cover other JavaScript concepts, such as `this`, `new`, Prototypes, and Classes.

If you missed the previous articles, you can check part 1 and part 2:

Outlier (powered by Scale AI) - Sponsor

Outlier provides premium freelance coding opportunities for frontend developers.

• up to $50 per hour (USD) based on expertise and location

  • some other countries it is up to $30 per hour (USD) due to location

• weekly payouts via PayPal & AirTM—no waiting weeks to get paid

• performance bonuses available on select projects

Explore how frontend developers are shaping AI's future (and getting paid for it).

Explore Outlier

The `this` Keyword

In object-oriented languages like C# or Java, the `this` keyword refers to the current object of a method or a constructor.

So each time you use `this` inside a method of a object, it will always refer to the same object.

However, in JavaScript, the `this` keyword implementation is slightly different, which sometimes causes many problems and bugs, if not understood well.

Let explore some examples.

Example 1: Method Call

const hero = {
  name: 'Aria',
  greet() {
    console.log(`${this.name} says hi`);
  }
};

hero.greet(); // Aria says hi

In this case, everything works as expected.

However, the value of `this` is not determined by the function that uses it.

Example 2: Detached Method

const { greet } = hero;

greet(); //  says hi

In this case, we get an empty value for `this.name` because the value of `this` depends on the call-site.

It doesn’t refer to the function in which it’s used or to it’s scope.

It refers to the object on which the function is being executed.

In the example above, I’ve run the code inside the browser, where `this` refers to the `window` object and it doesn’t have a `name` property.

💡 Pro tip: Always ask: “What object sits on the left side of the dot when the function is being called?”

We can say that `this` is not an author-time binding but a runtime binding.

It is contextual based on the conditions of the function’s invocation.

Apart from the mentioned example from above, there’re some other ways of how to manipulate the value of `this`.

Let’s explore them as well just for completeness.

Example 3: Arrow Functions

Arrow functions don’t get their own this.

Instead, they capture it from the surrounding scope.

const knight = {
  name: 'Lancelot',
  salute: () => console.log(this.name)
};

knight.salute(); // undefined

Example 4: Explicit Binding

We can explicitly set the value of `this` when we call a method.

This is called `binding` because we bind a specific value to `this`.

function introduce() {
  console.log(`I am ${this.name}`);
}

const elf = { name: 'Legolas' };

introduce.call(elf); // I am Legolas

As you see, in JavaScript, we can use `this` inside functions, not only classes.

The `new` Keyword

In object-oriented languages like C# or Java, the `new` keyword is used to create a new instance of class.

However, in JavaScript, the behavior of the `new` keyword is slightly different, no matter there’re classes in the language.

In OO languages, using the `new` keyword will result in calling the constructor method of the class.

In JavaScript, we can simply use a function to create a new object.

function Hero(name) {
    this.name = name;
}

const hero = new Hero("Gandalf");

console.log(hero.name); // "Gandalf"

When we use the `new` keyword before a function, it will create a new object and bind the `this` inside the function to the newly created object.

Then, it will return the new object, if the function doesn’t return anything.

If the function returns an object, the above is not valid.

function Person(name) {
  this.name = name;
  return { nickname: `The ${this.name}` };
}

const p = new Person("T-Shaped Dev");

console.log(p.nickname); // "The T-Shaped Dev"
console.log(p.name); // undefined

Note: Arrow functions can’t be used as constructors. They throw if you use `new`.

Note On Using `this` And `new`

If you don’t want the headache of using `this` and `new`, you might prefer a more functional approach.

You can use closures to deal with `this` and factory functions to deal with `new`.

For instance:

// Functional factory + Closure approach
function createCounter(start = 0) {
  let count = start;

  function increment() {
    count += 1;
    console.log(count);
  }

  function reset() {
    count = 0;
    console.log(count);
  }

  return { increment, reset };
}

const c2 = createCounter(5);

c2.increment(); // 6
c2.reset();     // 0

Prototypes

Objects in JavaScript have a `prototype` property which references another object.

So in JavaScript, we can build an inheritance object hierarchy through using Prototypes.

The other way of building such hierarchies is through Classes which are a syntax sugar over Prototypes.

Whenever you read a property of an object, it will first try to find it in the object itself.

If not found inside the object, it will look for it into the `prototype`.

If it’s not found there as well, it will check the prototype’s prototype and so on until it reaches the Object.prototype.

const hero = {
  salute: () => console.log('Salute!')
};

const knight = {
  name: 'Knight',
  __proto__: hero
};

knight.salute();

In this case, we set the `__proto__` property explicitly for the specific object.

To set up the inheritance chain, we can do it in the constructor function so every created object has the correct prototype.

function Hero(name) {
    this.name = name;
    this.salute = function () {
        console.log(`${this.name}, Salute!`);
    }
}

function Knight(name) {
    this.name = name;
}

// create a reference for the prototype
Knight.prototype = new Hero();

const knight = new Knight("Lancelot");

knight.salute(); // Lancelot, Salute!

By setting the `prototype` object to the constructor function, we ensure that all objects created through the `new` keyword will set up properly.

Note: There are some other quirks around Prototypes in JavaScript, but I’ve found the shared notes above to be fundamental.

Classes

ES6 introduced Classes which are a syntax sugar over Prototypes.

Nowadays, using Prototypes is discouraged because of the high complexity around setting up big inheritance hierarchies.

It’s most common to use Classes also because of the familiarity of people with other OO languages.

class Hero {
  constructor(name) {
    this.name = name;
    this.salute = function () {
      console.log(`${this.name}, Salute!`);
    };
  }
}

class Knight extends Hero {
  constructor(name) {
    super(name)
  }
}

const knight = new Knight("Lancelot");

knight.salute(); // Lancelot, Salute!

Composition

Inheritance is a powerful tool to extend entities and create more complex object but it’s not ideal for all use cases.

Creating complex inheritance hierarchies is not trivial and most of the time we might end up with unnecessary complexity.

Personally, I think that the best way to create complex objects in JavaScript is through composition.

This way, we create objects with only what they need, they combine them to create a more complex ones.

function canAttack(state) {
  return {
    attack: () => console.log(`${state.name} slashes!`)
  };
}

function canHeal(state) {
  return {
    heal: () => console.log(`${state.name} heals!`)
  };
}

function createPaladin(name) {
  const state = { name };
  return {
    ...canAttack(state),
    ...canHeal(state),
    name
  };
}

const paladin = createPaladin('Theron');

paladin.attack(); // Theron slashes!
paladin.heal();   // Theron heals!

Performance Considerations About Inheritance

It’s important to mention that if performance is critical to the app then defining a function to the prototype might be a better option, instead of creating a fresh new copy every time.

This means that the function will be created once and will leave on the shared prototype.

function FastFighter(name) {
  this.name = name;

  // per-instance method
  this.attack = () => console.log(`${this.name} strikes fast!`);
}

// vs.

FastFighter.prototype.attack = function() {
  console.log(`${this.name} strikes fast!`);
};

This can be helpful in some scenarios but might lead to problems if not used properly because we deal with references, instead of actual copies.

📌 TL;DR

• `this` is set by the call-site, not where a function lives.

• `new` creates a fresh new object, binds `this`, and returns it.

• Prototypes forms a chain, so objects can inherit missing properties.

• Classes are a syntax sugar over Prototypes.

• Prefer composition to mix small behaviors, instead of deep and large hierarchies.

• We can share code through using prototype methods, boosting performance.

That's all for today. I hope this was helpful. ✌️

How I can help you further?

Become a better and more skilled React Engineer! 🚀

Check the book out!

👋 Let’s connect

You can find me on LinkedIn, Twitter(X), Bluesky, or Threads.

I share daily practical tips to level up your skills and become a better engineer.

Thank you for being a great supporter, reader, and for your help in growing to 26.3K+ subscribers this week 🙏

You can also hit the like ❤️ button at the bottom to help support me or share this with a friend. It helps me a lot! 🙏