DEV Community: behnam rahimpour

How I Monitor My Career Performance

behnam rahimpour — Sat, 25 Oct 2025 19:19:54 +0000

Overview

This article is the result of several years of reading, experimenting, and trying to build a system that helps me stay on track with my goals, habits, and long-term roadmap.

I’ll share my mindset, the tools I use, and how I put everything together into a system that actually works for me.

Before we start, it’s important to say — there’s no one-size-fits-all system. Everyone’s personality, lifestyle, and situation are different. What works for me might not work for you exactly, but maybe it’ll give you a few ideas to use for your own system.

At the end of the day, our life is like a system. If we don’t design it intentionally — for our habits, goals, and progress — things get messy fast. Building a system increases your chances of success in literally anything you aim for.

The Chain of Efforts Rule

For me, one of the biggest keys to success is what I call the Chain of Efforts rule.

It basically means:

Success isn’t one big event — it’s the result of small, boring daily efforts that you keep doing for a long time without breaking the chain.

This idea is talked about beautifully in The Slight Edge book, which I totally recommend.

That’s why I’ve built my personal system around this concept — creating and monitoring a structure that helps me keep my daily chain of efforts strong.

Why Monitoring Matters

Think about it — any system, whether it’s a software, rocket, or business, needs constant monitoring.

A rocket that’s off by just one degree can end up kilometers away from its target.

It’s the same with our goals and habits — even small misalignments can take us in the wrong direction over time.

So if we don’t monitor our roadmap and daily actions, we might be working hard... but toward the wrong target.

How I Build My Roadmap and Habits

Once I choose a specific goal, I break it down into smaller, clearer timeframes:

5-year vision
3-year milestone
1-year goal
This season
This month
This week

At each level, I describe the goal as if it’s already achieved. This helps me visualize success and build the steps backward.

Once the roadmap is clear, I figure out which daily habits will help me move forward toward those goals.

Creating the Right Habits

If you’re new to this, I really recommend starting with Atomic Habits — it’s a classic for a reason.

But the key thing is this:

Your habits should be realistic enough to stick with daily, but meaningful enough to push you toward your next goal.

Don't forget that we need to do our habits for a long run and our brain hates sudden, hard activities, so start small, make it consistent, and let it grow naturally over time to shape the habit.

That’s how I build the “chain of efforts” we talked about earlier.

Monitoring the Roadmap and Goals

After breaking down your goals and setting your habits, it’s time to track your progress.

At every checkpoint (monthly, seasonal, yearly), I review:

What percentage of goals I’ve achieved
What worked well
Where I struggled
What I can improve next time

This reflection part is critical — it’s where you actually learn and adjust your system. Because we always need to update our system and habits through the time based on our new visions, ideas and philosophy of living.

My Favorite Tool for Goal Monitoring: Obsidian

There are a lot of goal-tracking tools out there, but if you’re a bit techy and like flexibility, Obsidian is amazing.

You can download it here.

At first glance, it’s just a note-taking app for Markdown files.

But what makes it powerful is its plugin ecosystem — you can turn it into almost anything you want.

My Key Plugins

Dataview – to pull data and stats from notes
Charts – to visualize progress using the data
Kanban – to organize tasks visually in boards

My Folder Structure

Here’s how I’ve structured folder and files inside of Obsidian:
.
└── Goals/
├── Week Goals/
│ ├── 2025-06-01 (FIN).md
│ ├── 2025-06-08 (FIN).md
│ └── 2025-06-16.md
├── What to be/
│ ├── 2030-01-01 (5 years).md
│ └── 2035-01-10 (10 years).md
├── 2025-03-31 End of March.md
├── 2025-04-30 End of April.md
├── 2025-05-29 End of Spring.md
├── 2025-08-29 End of Summer.md
├── 2025-11-28 End of Fall.md
└── 2025-02-27 End of Winter.md

Each goal file includes goals for one aspect of my life (career, health, learning, etc.), plus a dynamic progress percentage that updates automatically with Dataview and a small JavaScript snippet.

In my “Statistics” file, I gather the results from all the smaller goals and visualize them using the Charts plugin — it’s super motivating to see progress in one place.

For weekly goals, I use the same structure — and mark completed weeks as (FIN). Those get picked up by the weekly statistics automatically.

You can find my example scripts in this gist link
You can freely use and modify my code to fit your own workflow.
Just copy each code and put in related file like this:

Bonus tip: I also use the Kanban plugin to connect roadmap items with related goals and tasks. It helps me see everything more clearly without extra tools.

Also for syncing obsidian data I use synthing and I'm share the folders between pc and mobile. But you can use many other ways or apps like this to share obsidian and document folder between your pc and other platforms or use other community plugins.

Tracking Habits

You can use Obsidian for habits too, but personally, I prefer a dedicated app for simplicity.

My favorite is Habit Tracker on Android (you can find it here).

It gives you clean weekly and daily statistics — perfect for seeing your “chain of efforts” visually.

And for doing habits or focused work sessions, I use the Pomodoro technique.

My go-to app is Focus To-Do — simple, synced, and effective.

Conclusion

A lot of people focus on making effort, but I’ve learned that the real power comes from building a system that helps you make those efforts wisely and consistently.

Your system doesn’t have to be perfect — it just has to be yours.

I hope sharing mine gives you some new ideas to experiment with and build your own version.

I’d love to hear from you:

👉 What kind of systems do you use to monitor your goals or career progress?

👉 How could I improve mine?

If this article helped you or gave you new ideas, I’d really appreciate your interaction — it helps me share this with more people.

Thanks for reading — and don’t break the chain 💪

A Practical Guide to GraphQL N+1 Solutions in NestJS

behnam rahimpour — Sat, 23 Aug 2025 19:41:38 +0000

Overview

At Comfortel, we developed a large-scale admin panel to manage a complex system with tightly coupled domains and bounded contexts. We used a GraphQL gateway to abstract the intricate communications between these domains.

Initially, the team was pleased with this abstraction, as many are when first adopting GraphQL. However, as in all software development—and indeed, in life—every decision is a trade-off. Our choice of abstraction soon led to new challenges in performance and scalability, primarily the infamous N+1 problem.

This case study details our problem-solving approach, the design of our implementation based on our technologies with Nestjs as our Gateway, and the final results.

What is the N+1 problem (why GraphQL often triggers it)

What it is: N+1 happens when we fetch a list of N parent records, then for each parent we issue an additional query to fetch nested data. That becomes 1 (for the list) + N extra queries. With deeper nesting it multiplies quickly (e.g., per-nested item queries).
Why GraphQL triggers it: GraphQL resolvers are field-based. Without batching, each field on each returned parent can cause its own data fetch. For lists, this leads to an explosion in calls to databases/brokers if left unoptimized.
Concrete example (Places → Members → Users)
- Query: list 50 places, and for each place resolve members, and for each member resolve their user.
- Naive calls:
- 1 call: list places (DB/broker)
- +50 calls: for each place, fetch members
- +Σ calls: for each place's members fetch user. If average 10 members per place, +500 calls.
- Total naive example with 50 places and 10 members per place: 1 + 50 + 500 = 551 calls per request.
- Complexity: O(P + P + P·M) ≈ O(P·M). With additional nested levels, this compounds.

Solutions

Apollo Connectors batching (schema-level change)
- Batch resolver calls at the Graph schema layer using Connectors.
- Requires updating the GraphQL schema with @connect mappings.
- Docs: Apollo Connectors: Batch Requests
- Example (IDs batched via query params):

type Product
  @connect(
    source: "ecom"
    http: { GET: "/products", queryParams: "id: $batch.id" }
    selection: "id name"
    batch: { maxSize: 10 }
  ) {
  id: ID!
  name: String
}

DataLoader (application-level wrapper)
- Batch and cache per-request fetches in application resolvers using a DataLoader abstraction.
- No schema changes required. Fits where we control resolver implementation.

Solution Choice

We are operating at the application level; therefore, DataLoader is a better fit for us than schema-level connectors. based on the time and efficiency of our goal.

Coding Design

Context-based DataLoader Management

Our requirements

Reusability: a shared, domain-scoped batching layer that can be reused across resolvers.
Automatic nested batching: convert N+1 per nested field into 1 batched request per nested layer:
- 1 request for the parent list
- 1 request for each nested entity layer (e.g., members, ancestors, parents)
Request-scoped caching: Each GraphQL request gets its own DataLoader instances to prevent cache pollution between requests and remove duplicated nested entities ids.

Why Context-based approach?
We need to initialize DataLoader in each GraphQL request separately to handle caches of DataLoader for each request separately. As each domain batch loader can be used in many other domains and managing dependencies, normal injecting and initializing DataLoader causes cache issues of singleton instances between requests. Therefore, we use the context callback of GraphQL with forRootAsync and initialize DataLoader in each incoming GraphQL request.

Encapsulation Strategy
To encapsulate the details of managing DataLoaders and their initialization and their modules, we created BatchLoadService and BatchLoadModule. This allows us to manage injection and initialization of domain batch loaders from a centralized location.

To achieve this with dataloader we rely on two tools:

load: this method, resolves a single key to a single result (or a list, but keyed by one id) via batching.
loadMany: resolve multiple keys at once (e.g., a list of ids) via batching.

Scenarios and how to apply the tools

Parent entity with one nested entity
- a) If parent exposes nested entity id: use load with the nested id.
- Example: get Members by member ids. and the return type will be array of members.
- b) If parent does NOT expose nested entity id: use load with parent id (the batch function fetches by parent ids).
- Example service: get Members by place ids. and the return type again will be array of members.
Parent entity with list of nested entities
- a) If parent exposes nested ids list: use loadMany with nested ids.
- Example: get ancestors by ancestor_ids. and the return type will be array of ancestor ids.
- b) If parent does NOT expose nested ids list: use load with parent id; the batch function returns an array per parent.
- Example service: get Members by place ids and return an array per place and the return type will be array of array of members.
- Note: the batch function must return results in the exact order of requested keys (array of arrays aligned to parent order).

Directory design (per-domain batch layer)

Keep a reusable batching class per domain to consolidate all batchable methods for that domain, and export typed loaders for use in resolvers across domains.

src/
  infrastructure/
    common/
      batch-load/
        batch-load.module.ts        # Centralized batch loader management
        batch-load.service.ts       # Service to initialize all loaders
        batch-load.interface.ts     # Common interfaces and types
  application/
    place/
      place.batch-load.ts        # Place-specific batching (e.g., by place ids)
    service/
      service.batch-load.ts      # Example for service domain (pattern mirrors place)

Class diagram (PUML)

Implementation guideline

GraphQL Module Configuration

The GraphQL module is configured with forRootAsync to initialize DataLoaders per request from context property:

GraphQLModule.forRootAsync<ApolloDriverConfig>({
  driver: ApolloDriver,
  imports: [BatchLoadModule],
  useFactory: (batchLoadService: BatchLoadService) => ({
    autoSchemaFile: join(process.cwd(), "dist/schema.gql"),
    graphiql: true,
    context: () => ({ batchRequest: batchLoadService.initLoaders() }),
    buildSchemaOptions: {
      numberScalarMode: "integer",
    },
    formatError(formattedError) {
      return config().formatGraphQLError(formattedError);
    },
  }),
  inject: [BatchLoadService],
}),

As you see for each request from context we initialize our dataloader.

BatchLoad Module Structure

@Module({
  providers: [BatchLoadService, MemberBatchLoad, PlaceBatchLoad],
  imports: [PlaceModule, UserPlaceModule],
  exports: [BatchLoadService],
})
export default class BatchLoadModule {}

Adding New Domain Batch Loaders

Create the batch loader class implementing the BatchLoad interface:

@Injectable()
export default class NewDomainBatchLoad implements BatchLoad {
  constructor(private readonly newDomainService: NewDomainService) {}

  initLoaders() {
    return {
      loadByIds: this.loadByIds(),
      // ... other loaders
    };
  }

  private loadByIds() {
    return new DataLoader(async (ids: readonly string[]): Promise<NewDomain[]> => {
      const items = await this.newDomainService.findByIds(ids as string[]);
      const resultMap = this.makeFrequencyCounter(items);
      return ids.map((id) => resultMap[id] ?? null);
    });
  }

  private makeFrequencyCounter(items: NewDomain[]) {
    return items.reduce((acc, item) => {
      acc[item._id] = item;
      return acc;
    }, {} as Record<string, NewDomain>);
  }
}

Add to BatchLoadService:

@Injectable()
export default class BatchLoadService {
  constructor(
    private readonly placeBatchLoad: PlaceBatchLoad,
    private readonly memberBatchLoad: MemberBatchLoad,
    private readonly newDomainBatchLoad: NewDomainBatchLoad, // Add this
  ) {}

  initLoaders() {
    return {
      place: this.placeBatchLoad.initLoaders(),
      member: this.memberBatchLoad.initLoaders(),
      newDomain: this.newDomainBatchLoad.initLoaders(), // Add this
    };
  }
}

Add to BatchLoadModule:

@Module({
  providers: [
    BatchLoadService, 
    MemberBatchLoad, 
    PlaceBatchLoad,
    NewDomainBatchLoad, // Add this
  ],
  imports: [PlaceModule, UserPlaceModule, NewDomainModule], // Add required modules
  exports: [BatchLoadService],
})
export default class BatchLoadModule {}

Resolver Usage

Resolvers now get batch loaders from the GraphQL context instead of dependency injection:

@ResolveField(() => PlaceObject, { nullable: true })
parent(@Parent() place: Place, @Context("batchRequest") batchRequest: BatchLoadContext) {
  if (!place.parent_id) return undefined;
  return batchRequest.place.listByPlaceIds.load(place.parent_id);
}

@ResolveField(() => [PlaceObject], { nullable: "itemsAndList" })
ancestors(@Parent() place: Place, @Context("batchRequest") batchRequest: BatchLoadContext) {
  if (!place.ancestor_ids) return [];
  return batchRequest.place.listByPlaceIds.loadMany(place.ancestor_ids ?? []);
}

@ResolveFieldSafe(() => PaginatedMemberObject, {
  nullable: "itemsAndList",
  name: "members",
})
members(@Parent() place: Place, @Context("batchRequest") batchRequest: BatchLoadContext) {
  return batchRequest.member.nestedListByPlaceIds.load(place._id);
}

Key Implementation Details

Members batch loader (parent id → list of nested entities)
- Tool used: load with parent place id, returning an array per key, keeping order.

private nestedListByPlaceIds() {
  return new DataLoader(async (placeIds: readonly string[]): Promise<Member[][]> => {
    const [members] = await this.membersService.getMembersByPlaceIds(placeIds as string[]);
    const resultFrequencyCounter = this.makeMembersFrequencyCounter(members);
    return placeIds.map((id) => resultFrequencyCounter[id] ?? []);
  });
}

Place batch loader (single id for parent, list of ids for ancestors):
- Tool used for single id: load by place id (e.g., parent), and for lists: loadMany for ancestors.
- The reducer builds a frequency counter to ensure O(N) combine and preserve order.

private listByPlaceIds() {
  return new DataLoader(async (placeIds: readonly string[]): Promise<(Place | null)[]> => {
    const places = await this.placesService.findByIds(placeIds as string[]);
    const resultFrequencyCounter = this.makePlacesFrequencyCounter(places);
    return placeIds.map((id) => resultFrequencyCounter[id] ?? null);
  });
}

The key principle with DataLoader: the batch function must return results in the same order as the keys. To avoid O(N²) lookup, we build a frequency counter map keyed by id and then map results back in order of input keys. This gives O(N) combine time for each batch.

Results and complexity comparison

Legacy approach:
- Calls ≈ 1 (places) + P (members by place) + P·M (users by member) = O(P·M)
- Example with 50 places and 10 members per place → 551 calls
Batched approach with DataLoader:
- Calls ≈ 1 (places) + 1 (all members for all places) + 1 (all users for all members) = O(1) per nested layer
- Example with 50 places and 10 members per place → 3 calls
Impact: Dramatically fewer DB/broker requests, lower latency, and significantly reduced load on downstream services, with clear, reusable batching primitives per domain.

Last consideration: Handling Large Lists

We now gather all nested entity IDs efficiently. However, a new consideration arises: if a nested entity is a long list associated with a single parent, fetching the entire list could result in a heavy, inefficient query.

To solve this potential problem, we addressed it through API design. For use cases where a nested entity could return a very long list, our GraphQL API returns only the list of IDs. We then provide a separate, dedicated API endpoint to fetch the contents of that list, complete with pagination features.

Conclusion

This challenge pushed us to delve deeper into GraphQL's execution logic and ultimately implement a sophisticated solution using DataLoader patterns. The results were undeniable: we achieved a significant reduction in database load and dramatically improved response times for our large-scale admin panel, ensuring it could scale effectively.

However, no solution is perfect. As we noted, addressing one bottleneck often reveals another, leading us to design a hybrid approach for large datasets using paginated endpoints.

The key lesson? Powerful abstractions are invaluable, but they must be implemented with a clear understanding of their performance implications. Proactive monitoring and a willingness to iterate on your design are crucial for long-term success.

We’re eager to hear from other developers and architects. Share your experiences and thoughts in the comments below!

Help us reach more developers by your reaction and sharing this case study with your network.

Case Study: How we Cut Blocking Time by 92% in React admin panel - A Story Starring useTransition

behnam rahimpour — Fri, 16 May 2025 21:10:28 +0000

Overview

In this article, I want to tell you the story of the fixing a massive performance problem I faced in one of the projects which had a laggy, frustrating UI with slow renders and excessive API calls by changing the way of thinking in the coding architecture. The app had a complex tree-table structure, where every interaction felt sluggish, with blocking times up to 850ms and an explosion of network requests.

It happens just by rethinking how data should flows and stores and how components should be rendered, we slashed blocking time to 70ms (92% faster), cut API calls by 60% and 2x faster rerendering in performance of user interactions with any components in the page.

How? I found when the issue is in the process of data flow or the way of storing the data throwing more useMemo at the problem or some minor changes in the caches doesn't help at all. Instead, we had to:

Break a heavy dependency between the huge components, and URL state which caused massive heavy rerendering and high blocking time.
Stop recursive fetching that caused O(n) API calls.

In this experience I learnt some good lessions and I reached to some ideas and I decided to share it with you.

Let’s dive in.

Problem realizing

In this project, there is a large, tree-shaped main component, structured like this:

Additionally, a table dynamically updates its content based on the selected node in this tree with many features like drag and drop of columns, many filtering, switching columns, export, etc:

To persist results between page reloads and enable shareable links, we store the selected tree branch and related data in the URL. This is achieved using dynamic path segments and query parameters, structured like this:

You see all ids after place path is the selected branch ids in the tree.

There were several problems:

Excessive API Requests on Page Load

Based on selected branch ids in the url, for every tree node, we checked if its ID existed in the selected branch IDs string or not. If so, we fetched its children.
This resulted in O(n) server requests (where n = depth of selected branches), significantly slowing down initial load.

Slow Re-rendering on User Interaction

Clicking a tree or table item triggered a >160ms delay due to:
Heavy components depended on any url changes and as the result getting rerendered.
Full dependency on URL state for all components even for some changes which shouldn't be depend on. For example tree shouldn't be depend or changes of selected table item in the url.

We can see on click of each item in table we rendered the tree, despite we had memoization the ui part of the each tree node but as their ui logics accessed to parameters in the url they had rerendered in the ui logic part of them.

You can see after clicking on each item in the table in average we have 150ms of rerender.

Also after clicking on each node in the tree we had in average 160ms of rerender time.

Solution

Excessive API Requests on Page Load

The implementation suffered from two compounding issues.

First, each node independently accessed URL parameters to determine whether it needed to fetch its children.
Second, the recursive nature of these checks meant that for a deeply nested selection in the tree - say five levels deep - the page would make five consecutive API requests before fully rendering, with each request waiting for its parent's response like links in a chain.

This waterfall fetching pattern not only slowed initial page loads but also caused unnecessary network traffic, as intermediate nodes would re-fetch data their parents already possessed.

In this diagram, tree node is each node item in the tree and tree view as the main component of the tree which contains all the tree nodes.

So we changed our idea of getting the data from the node to just fetching the whole branch at once from highest parent tree component and render it just once not level by level from the node aspect.

To address these performance issues, we fundamentally redesigned the data fetching approach. Rather than having each individual node check the URL and recursively fetch its children - which created the O(n) request problem - we implemented a centralized solution. The highest-level parent component now retrieves the complete branch data in a single request when the URL parameters change. This atomic fetch gathers all necessary nodes from the root to the deepest selected leaf in one network call, eliminating the previous chain of sequential requests.

With this optimized architecture, the tree renders just once with the complete dataset instead of progressively updating level by level. The nodes no longer need to independently manage data fetching or parse URL parameters, which prevents the cascading re-renders that previously bypassed memoization. By shifting from a distributed to a consolidated data model, we reduced both network overhead and computational waste, as the system now handles branch selection as a unified operation rather than a series of fragmented node-level interactions.

And in the result, with the same level of selected tree node form 3.6s of LCP 2.25s pf FCP and 850ms of blocking time,

We reached to 2.1 of LCP, 0.7s of FCP and 70ms of blocking time.

Laggy UI on url changes

As we mentioned, based on the selected branch IDs in the URL, we re-rendered the tree and the table together since both of them depended on URL changes.

We used a technique in the tree to make it agnostic about URL changes. Because we had many heavy re-renders based on URL changes, we separated the tree and table re-renders into two smaller, independent re-renders. To achieve this, we followed these steps:

Defined an internal store for the tree state. which has two parameters.

export type TreeState = {
  /**
   * With nodeToFetch, we decide which node required to fetch its sub tree and show loading.
   */
  nodeToFetch?: string;
  /**
   * With selectedBranchIds we ask tree view to change selected one and ask url to update the path
   * */
  selectedBranchIds?: string;
};

To make the tree, agnostic about the url changes we removed its dependency to the url changes and just initialize the selected branch ids when component mounted for the first time, just for one time.

   const urlBranchIds = this.commonUrlHanlder.getSelectedTreeBranchIds();
    useEffect(() => {
      this.treeStateStore.getState().setTreeState({
        selectedBranchIds: urlBranchIds,
      });
    }, []);

To update the URL based on internal state changes and separate the re-renders of the tree and table into two isolated smaller re-renders, we used transitions for URL updates.

    const updateParamsNavigator =
      this.commonUrlHanlder.getNavigatorToUpdateParams();

    const [_, startTransition] = useTransition();
    const navigator = this.commonUrlHanlder.getNavigatorToUpdateBranchIds();
    useEffect(() => {
      if (!isInitialized) return;

      startTransition(() => {
        navigator(selectedBranchIds ?? "");
        updateParamsNavigator({ page: 0 });
      });
    }, [selectedBranchIds]);

As a result, all internal state changes of our computationally intensive tree component now occur in isolation, while table updates synchronize via URL changes using useTransition — allowing React to prioritize these updates as non-blocking background work.

And in the result on click of each node in the tree from in average 190ms of heavy task in the performance:

We reached to all small rerenders all less than 50ms:

Last shot to remove all unnecessary rerenders in the tree

As the last action, the commonUrlHandler which was the boundary between the main codes and update url methods, behind the scene was using react router hooks and with any unrelated changes in the url parameters, the tree got rerendered. But based on our strategy the tree component shouldn't care about the url changes at all. So we used window object methods to get url data staticaly and just for hydration and update url chantes:

  /**
   * Update route without rerendering and react hooks
   * @param route - route to update
   */
  staticUpdateRouteWithoutRerendering(route: string) {
    window.history.pushState({}, "", Endpoint.sanitizeURL(`${route}`));
    window.dispatchEvent(new PopStateEvent("popstate"));
  }

This is the method in commonUrlHandler class which cause updating the url without rerendering the tree and this dispatch event helps react router find url changed then rerender the components.

 startTransition(() => {
        const getRouteWithoutParams =
          this.commonUrlHanlder.staticRouteWithoutParams();

        if (!getRouteWithoutParams) return;

        this.commonUrlHanlder.staticUpdateRouteWithoutRerendering(
          `${getRouteWithoutParams?.route}/${selectedBranchIds || ""}`,
        );
      });

As you see instead of using react router hooks we just used window object in the tree and just on the first load we hydrate the component by the url informations.

As the result, now the tree doesn't rerender, on the changes of the url.

Performance result

The performance result calculated by user interaction with other components of the app except the tree, like advanced table component which was another huge component with many fitlers, features and drag and drop of columns in the same page as the tree.

All re-renders in the app caused by URL changes have now been optimized, improving performance by 2x.

For example, in the comparison screenshot, we clicked the same item in a table across two versions of the app. Previously, this would trigger a URL update (storing the selected item in the URL), leading to unnecessary re-renders in the tree component. Now, the performance impact is significantly reduced—here’s as we opt-out tree rerenders by url changes and the result:

From average 75 reached to less than 50ms in all tests.

And after all these changes the final score of light house from in average 65 increased to 90 in average.

Conclusion

Performance optimizations often look like small tweaks, but the some times biggest wins come from architectural shifts, not just micro-optimizations. Here’s what we learned:

One State Shouldn’t Control Everything
Storing all state in the URL created cascading massive re-renders. By isolating the main standalone app component's state, we can keep it fast while still allowing shareable links.
Batch request, Don’t Cascade
Batch request and cut network overhead and removed render waterfalls.
Break your heavy renders
With useTransition, we made the table’s URL updates non-blocking, so the tree stayed responsive even during large state changes in two lighter rerenders.

Final Thought:
If your app feels slow and you tried all tools and techniques from the framework and youre language, but still no changes happened, look from more abstraction viewport, maybe the solution resides in the higher level of architecting the codes not just small tweaks.

If you found this article helpful, I’d be truly grateful if you could:
⭐ Add some reaction to the article
💬 Share your thoughts in the comments

Every interaction helps these best practices reach more developers!

Next.js Localization Best Practices for Enterprise Apps

behnam rahimpour — Sat, 03 May 2025 14:49:41 +0000

Table of contents
Overview
Guideline for adding new key
Folder acrhitecture
Configuration
Provider and client support
Combination with failure handling and params validation

Requirements

This article based on Next.js boilerplate repository.
To explore all concepts in depth and see a production-ready boilerplate and following these best practices, visit:

behnamrhp / Next-clean-boilerplate

A Full featured nextjs boilerplate, based on clean architecture, mvvm and functional programming paradigm.

Nextjs clean architecture boilerplate

Table of content

Nextjs clean architecture boilerplate

Table of content

Overview

Motivation

Technologies

Architecture

Folder structure

Requirements

Getting Started

Local

Docker

naming convetions:

Overview

This project is a starting point for your medium to large scale projects with Nextjs, to make sure having a structured, maintainable and scalable foundation for your Next.js project based on best practices in clean architecture, DDD approach for business logics, MVVM for the frontend part, storybook and vitest for testing and, localization and also functional programming with error handling for business logics.

Motivation

Next.js and many other modern SSR frameworks provide powerful tools and a fresh approach to frontend development. However, since these tools are relatively new, the focus has largely been on features rather than software engineering best practices.

As a result, many teams use Next.js for its capabilities but neglect maintainability, architecture, and scalability—especially in medium to large-scale applications…

View on GitHub

Also to know more about higher level architecture in Next.js applications. please take a look at clean architecture in Next.js article.

Overview

A major issue with most localization libraries is their reliance on hardcoded string keys throughout the codebase. This forces developers to manually track and update every language dictionary file whenever keys change - a tedious and error-prone process with no type safety or automation.

This document provides guidelines for:

File organization: Structure localization files so changes to any key trigger errors across all language resources
Key management: Replace hardcoded strings with typed objects to eliminate manual refactoring when keys change
Possible to work with error handling

Guideline for adding new key

Define namespace: at first based on the domains which we talked about it in this article we make a folder.
Main folder: common
Add langkey and namespace name for the domain: langKey is the single source for the languages in that domain which all dictionaries will use it. As we use this source in failure and params message in domain layer we put them in feature layer but dictionaries will remain in bootstrap.

/**
 * main language keys which will be used for translation to avoid using strings directly and be
 *  a single source of truth in all changes between all languages dictionaries.
 * All languages dictionaries should have the same keys by having this object type.
 */
const commonLangKey = {
  global: {
    home: "global.home",
    dashboard: "global.dashboard",
    loading: "global.loading",
    required: "global.required",
    passwordMinLength: "global.passwordMinLength",
  },
  failure: {
    network: "failure.network",
    param: "failure.param",
  },
  dashboard: {
    invoice: {
      createButton: "dashboard.invoice.createButton",
    },
  },
};

export const commonLangNs = "common";

export default commonLangKey;

Main file: common-lang-key.ts

note: Make sure the namespace name is the same as folder name in dictionaries to be able import them by this namespace name.

Dictionaries: Add related dictionaries for the domain in bootstrap layer.

// en.ts

import commonLangKey from "@/feature/common/lang-keys/common.lang-key";

const en: typeof commonLangKey = {
  global: {
    home: "Home",
    loading: "Loading",
    required: "{{field}} is Required",
    dashboard: "Dashboard",
    passwordMinLength: "Password length should be at least 8 characters!",
  },
  dashboard: {
    invoice: {
      createButton: "Create random Invoice",
    },
  },
  failure: {
    network: "Something went wrong please try again layer!",
    param: "Please provide correct information",
  },
};

export default en;

Main file: en.ts

note: as we use language enum to define languages make sure the langs are the same as language enum in this file to be able import the dictionaries.

Add your new key to langKey.ts to proper domain.
Add translation for new key in en.ts and ru.ts in the same domain as in the langKey.ts. en.ts and ru.ts objects are connected to source object, so typescript will show an error if new key added or old key was changed. Also this connections helps us to avoid code become brittle since typescript will show an error in places of usage of translation keys if they were changed.

langKey.ts

const langKey = {
  global: {
    keyWithoutSpecificDomain: "global.keyWithoutSpecificDomain"
  },
  sampleKey: "sampleDomain.sampleKey",
};

export default langKey;

ru.ts

const ru: typeof langKey = {
  global: {
    keyWithoutSpecificDomain: "Строка без домена"
  },
   sampleKey: "Строка с доменом",
}

en.ts

const en: typeof langKey = {
  global: {
    keyWithoutSpecificDomain: "String without domain"
  },
  sampleKey: "String with domain",
}

Folder acrhitecture

.
└── src/
    ├── bootstrap/
    │   └── i18n/
    │       ├── i18n.ts
    │       └── dictionaries/
    │           └── common/
    │               ├── en.ts
    │               └── ru.ts
    └── feature/
        └── common/
            └── lang-keys/
                ├── common.lang-keys.ts
                └── user.lang-key.ts

i18n.ts configuring i18next.

langKey.ts contains object of all possible keys for translation.

ru.ts object of russian keys.

en.ts object of english keys.

Configuration

Before usage i18next's translation hook, it must be configured with languages it should support.

example of initialization

export const i18nInstance = createInstance();

export enum LANGS {
  EN = "en",
  RU = "ru",
}

const nameSpaces = [commonLangNs, userLangNs];

export const getI18n = async (params: {
  lng: LANGS;
  resources?: Resource;
  ns?: string;
}) => {
  const { lng, ns, resources } = params;
  if (i18nInstance.isInitialized) {
    await i18nInstance.changeLanguage(lng);
    return {
      i18n: i18nInstance,
      resources: i18nInstance.services.resourceStore.data,
      ns: nameSpaces,
      defaultNs: commonLangNs,
      t: i18nInstance.t,
    };
  }
  await i18nInstance
    .use(initReactI18next)
    .use(
      resourcesToBackend(
        (language: LANGS, namespace: string) =>
          import(`./dictionaries/${namespace}/${language}.ts`),
      ),
    )
    .init({
      ...getOptions(lng, ns),
      resources,
      ns: nameSpaces,
      defaultNS: commonLangNs,
      preload: resources ? [] : languages,
    });

  await i18nInstance.init();

  return {
    i18n: i18nInstance,
    resources: i18nInstance.services.resourceStore.data,
    t: i18nInstance.t,
  };
};

export async function getServerTranslation(
  lng: LANGS,
  ns?: string,
  options: { keyPrefix?: string } = {},
) {
  const { i18n } = await getI18n({ lng });
  // console.log(i18n);
  return {
    t: i18n.getFixedT(lng, Array.isArray(ns) ? ns[0] : ns, options?.keyPrefix),
    i18n: i18nInstance,
  };
}

Main file

Provider and client support

To support client side translations with once loaded data in the server we can use provider component like this file.

Then we can use this provider in one main layout of the app like this file.

Combination with failure handling and params validation

For combination with failure hanlding, please check this article or this document in the boilerplate
Also for combination with params please check the feature layer architecture article.

Conclusion

By implementing this structured approach to localization, we've solved three critical pain points:

Type-safe translations - No more hardcoded string keys
Automated synchronization - Changes propagate across all language files
Scalable architecture - Clean separation between domains

This system integrates seamlessly with:

Failure handling
Param validation
Next.js server/client components

If you found this article helpful, I’d be truly grateful if you could:
⭐ Star the repository to support its visibility
💬 Share your thoughts in the comments—your feedback helps improve content reach

Every interaction helps these best practices reach more developers!

Why Next.js Apps Struggle at Scale (And How Feature Layers Solve It)

behnam rahimpour — Sat, 03 May 2025 09:50:11 +0000

Table of Contents
Architecture overview of the feature layer
Class diagram of feature layer
Layers responsibilities
- Data layer
  - Data transfer object (DTO) / Mapper
- Repository
- Domain layer
  - Entity
  - Enums
  - IRepo
  - Usecase
  - Params
  - BaseFailure
The usage of functional programming in feature layer

Architecture overview of the feature layer

Business logic in applications is one of the most critical components, playing a major role in a project's maintainability and scalability. Unfortunately, in many large-scale frontend applications, mixing this logic with UI-related code severely compromises maintainability. In this article, we introduce a dedicated feature layer,a separate architectural tier for isolating business logic in medium-to-large projects. We’ll also explore how to organize this layer’s components (data/domain) and its folder structure using basic DDD principles.

This article based on Next.js boilerplate repository.
To explore all concepts in depth and see a production-ready boilerplate and following these best practices, visit:

behnamrhp / Next-clean-boilerplate

A Full featured nextjs boilerplate, based on clean architecture, mvvm and functional programming paradigm.

Nextjs clean architecture boilerplate

Table of content

Nextjs clean architecture boilerplate

Table of content

Overview

Motivation

Technologies

Architecture

Folder structure

Requirements

Getting Started

Local

Docker

naming convetions:

Overview

This project is a starting point for your medium to large scale projects with Nextjs, to make sure having a structured, maintainable and scalable foundation for your Next.js project based on best practices in clean architecture, DDD approach for business logics, MVVM for the frontend part, storybook and vitest for testing and, localization and also functional programming with error handling for business logics.

Motivation

Next.js and many other modern SSR frameworks provide powerful tools and a fresh approach to frontend development. However, since these tools are relatively new, the focus has largely been on features rather than software engineering best practices.

As a result, many teams use Next.js for its capabilities but neglect maintainability, architecture, and scalability—especially in medium to large-scale applications…

View on GitHub

Also to know more about higher level architecture in Next.js applications. please take a look at clean architecture in Next.js article.

As we mentioned this layer handles the business logic of each feature. For each feature this layer is divided into two parts, data and domain. where the data is divided into:

mapper
repository

while the domain is divided into;

usecase
entity
failure
repository interface

Class diagram of feature layer

The following class diagram shows the relation between domain and data inside feature layer:

Layers responsibilities

feature layer responsibilities can be divided into data layer responsibilities and domain layer responsibilities.

Data layer

Data transfer object (DTO) / Mapper:

Data transfer object (DTO) are commonly used within the repository layer to convert data fetched from external sources (such as databases or APIs) into domain entities, and vice versa. This conversion ensures that the domain entities remain agnostic of the underlying data storage mechanisms and allows for easier integration with different data sources without affecting the core business logic. for example let's imagine that the response type when a book will be created is as follows:

export default class UserMapper {
  static get toApiRole(): Record<Role, ApiRole> {
    return {
      [Role.ADMIN]: ApiRole.ADMIN,
      [Role.USER]: ApiRole.DESIGNER,
      [Role.MANAGER]: ApiRole.MANAGER,
    };
  }

  static get toEntityRole(): Record<ApiRole, Role> {
    return {
      [ApiRole.ADMIN]: Role.ADMIN,
      [ApiRole.DESIGNER]: Role.USER,
      [ApiRole.MANAGER]: Role.MANAGER,
    };
  }

  static mapToEntity(
    response: WithPaginationResponse<UserResponse>,
  ): WithPagination<UserParams> {
    try {
      const usersEntity = response.data.map((user) =>
        new User({
          id: user.id,
          username: user.username,
          role: user.role ? UserMapper.toEntityRole[user.role] : Role.USER,
          displayName: user.display_name ?? "",
        }).toPlainObject(),
      );
      return new WithPagination(usersEntity, response.total).toPlainObject();
    } catch (e) {
      throw new ResponseFailure(e);
    }
  }

  static mapToCreateParams(params: CreateUserParams): CreateUserApiParams {
    return {
      username: params.username,
      password: params.password,
      display_name: params.displayName,
      role: UserMapper.toApiRole[params.role],
    };
  }

  static mapToUpdateParams(params: UpdateUserParams): UpdateUserApiParams {
    return {
      username: params.username,
      display_name: params.displayName,
      role: UserMapper.toApiRole[params.role],
    };
  }
}

Main file: user.mapper.ts

Repository:

The repository acts as an adapter pattern between the use case and external resource. Also transforms entity-shaped data into a format compatible with the data source. This bidirectional transformation is achieved through the use of data transfer objects (DTOs), which we call mapper in this boilerplate. Additionally, repositories can interact with each other within the same layer, enabling seamless communication between sibling repositories.

export default class UserRepositoryImpl implements UserRepository {
  readonly endpoint: BackendEndpoint;

  private fetchHandler: FetchHandler;

  constructor() {
    const di = serverDi(userModuleKey);
    this.fetchHandler = di.resolve(FetchHandler);
    this.endpoint = di.resolve(BackendEndpoint);
  }

  update(params: UpdateUserParams): ApiTask<true> {
    const options: FetchOptions<UpdateUserApiParams> = {
      endpoint: `${this.endpoint.users}/${params.id}`,
      method: "PUT",
      body: UserMapper.mapToUpdateParams(params),
    };
    return this.fetchHandler.fetchWithAuth(options);
  }

  delete(ids: string[]): ApiTask<true> {
    const options: FetchOptions<string[]> = {
      endpoint: this.endpoint.users,
      method: "DELETE",
      headers: {
        "Content-Type": "application/json",
      },
      body: ids,
    };
    return pipe(
      this.fetchHandler.fetchWithAuth<undefined, string[]>(options),
      map(() => true),
    );
  }
}

Main file: user repository

You can see in this repository class we imported backend endpoints and fetch handler boundary, and the repository knows how to work with these dependencies to connect to the third party apis.

To know more about endpoint architecture and di in Next.js applications use these two other articles:

How We Fixed Next.js at Scale: DI & Clean Architecture Secrets From Production

A Simple Way to Organize API Endpoints Like a Senior

Domain layer

Entity:

Entity is the business object that contains business rules. For example a Book entity can be as follows:

export default class Book {
  id: string;

  title: string;

  autherName: boolean;

  status: BookStatus;

  constructor({ id, autherName, title, status }) {
    this.id = id;
    this.title = title;
    this.autherName = autherName;
    this.status = status;
  }
}

note: BookStatus is an enum implemented in the same layer with entity.

Enums:

Enums are used to define a fixed set of values for specific properties within an entity. They ensure type safety and provide clarity on the possible states or options for those properties. for example if there is prop inside Book entity that shows the status of the book, if the book is published, sent, draft, an enum can be added as follows:

enum BookStatus {
    PUBLISHED = "published",
  SENT = "sent",
  DRAFT = "draft",
}
export default BookStatus;

IRepo:

The repository interface defines a contract for data access operations, abstracting the interaction between the application's domain logic and the underlying data storage mechanisms. for example an IRepo to get a book can be implmented as follows:

interface IGetBookRepository{
    execute(): TaskEither<Failure, Book>
}

Usecase:

Usecase represents the main business logic of the application and orchestrates the overall process flow. It interacts with entities and communicates with external systems through repositories (IRepository). Usecase can connect to its siblings in the same layer, other usecases for example, the following diagram illustrates how usecase and repositories can connect to other ones in the same layer:

Params:

Params serve as structured schemas containing input parameters crucial for use case execution. These schemas encompass business rules and validations that necessitate careful handling during processing. Their primary function is to facilitate modularization and decoupling within the application architecture, offering a standardized interface for seamless communication between different layers. For example if it is required to validate the params of the book, the title, authorName and status should be validated, the team is formulating the validation terms, for example the team agreed on the following:

title: it should not be undefined
authername: it can be undefined
status: it should be defined so the parms class will have two methods, the first one to validate each param separately, the second one to validate all the params at once:

 get bookCreationParamsValidator() {
    return {
      title: string().required(),
      autherName: string(),
      status: string().required(),
    };
  }

  /**
   * Schema for all parameters.
   * You can use it to validate or cast or use its type
   */
  get schema() {
    return object(this.bookCreationParamsValidator);
  }
}

required word means that the param should be defined, bookCreationParamsValidator can be used to validate a param while schema is used to validate all params.

note: In the boilerplate we used zod but you can use any other similare libraries for this part.

BaseFailure:

BaseFailure mechanisms in the application serve as critical pointer of errors or exceptional conditions encountered during execution. By sticking to functional programming principles, errors are consistently represented on the left side, ensuring clear and predictable error handling pathways. The base failure, represented by the Base Failure class, plays an important role in this process. By extending the Error class and providing a standardized failure message, it serves as a foundational element for creating custom failure classes made specifically to specific error scenarios. These custom failure classes allow for precise and reliable error signaling, enabling straight error handling workflows. Additionally, the use of failure keys facilitates automated error handling processes, enhancing efficiency and robustness. Overall, the integration of failure mechanisms aligns straightforward with the application's functional programming paradigm, ensuring comprehensive error management and enhancing code reliability.

note: during the implementation, BaseFailure is the left side of the reusable type ApiTask which is based on TaskEither from fp-ts library. for example to make a failure for a problem in the network, it can be implemented as follows:

export default class NetworkFailure extends BaseFailure {
  constructor() {
    super("network");
  }
}

to get more familiar with failure, take a look at this article How to Automate Failure Handling and Messages with This Design

The usage of functional programming in feature layer

Functional programming plays a crucial role in our feature layer, providing a structured and efficient approach to managing connections between different layers of our system. Beyond its traditional benefits, functional programming enables robust error handling and manipulation throughout the application. By following to functional principles, we ensure that each process within our system is handled independently and comprehensively, enhancing clarity and maintainability.
Through functional programming, we can easily propagate return types across layers, enabling clear communication and transparent data flow. This approach not only enhances code organization and readability but also promote modularization and decoupling, leading to a more maintainable and scalable architecture.
We leverage the fp-ts library for functional programming in TypeScript, which provides a rich set of abstractions and utilities for working with functional concepts. For more detailed information on functional programming concepts, see Functional programming documentation

Conclusion

The Feature Layer is the powerhouse of your Next.js app, cleanly separating business logic (domain) from data handling while leveraging functional programming for robust, scalable code. By structuring entities, use cases, and repositories with clear boundaries, you ensure:

✅ Maintainability – Business rules stay pure and testable.
✅ Flexibility – Swap data sources without breaking logic.
✅ Error Resilience – Functional programming (via fp-ts) streamlines error handling.

Every interaction helps these best practices reach more developers!

Production-Proven Clean Architecture in Next.js: A Practical Guide

behnam rahimpour — Fri, 02 May 2025 15:42:46 +0000

Table of Contents
Clean Architecture Overview
Why did We choose Clean Architecture?
Project clean architecture diagram
Layers breaking down
- Application Layer
- Feature Layer
  - Domain
  - Data
- Bootstrap layer
Layers Connection
Folder structuring
- DDD aproach in folder structuring
Conclusion
Clean Architecture Overview

Clean Architecture is a software design philosophy that promotes structuring of large scale systems with a strong emphasis on separation of concerns and dependency inversion. The main goal is to create systems that are highly maintainable, scalable, and testable, while ensuring business logic remains isolated and independent of external frameworks and tools.

Note: for reading more information about clean architecture visit this link

Why did We choose Clean Architecture?

For large-scale projects that contains multiple domains characterized by tight coupling between them. Furthermore, these domains can be extended with new features without any predicted limitations.

Therefore, we require an architecture that can support, scalability, single responsibility, maintainability, testability and quality assurance. Also we need a shared language for our big system which is understandable among the team members.

Implementing a clean architecture, customized to accommodate frontend-specific features, was the optimal solution for this issue.

Project clean architecture diagram

As we discussed we used customized version of clean architecture based on nextjs-specific features.

This article based on Next.js boilerplate repository.
To explore all concepts in depth and see a production-ready boilerplate and following these best practices, visit:

behnamrhp / Next-clean-boilerplate

A Full featured nextjs boilerplate, based on clean architecture, mvvm and functional programming paradigm.

Nextjs clean architecture boilerplate

Table of content

Nextjs clean architecture boilerplate

Table of content

Overview

Motivation

Technologies

Architecture

Folder structure

Requirements

Getting Started

Local

Docker

naming convetions:

Overview

This project is a starting point for your medium to large scale projects with Nextjs, to make sure having a structured, maintainable and scalable foundation for your Next.js project based on best practices in clean architecture, DDD approach for business logics, MVVM for the frontend part, storybook and vitest for testing and, localization and also functional programming with error handling for business logics.

Motivation

Next.js and many other modern SSR frameworks provide powerful tools and a fresh approach to frontend development. However, since these tools are relatively new, the focus has largely been on features rather than software engineering best practices.

As a result, many teams use Next.js for its capabilities but neglect maintainability, architecture, and scalability—especially in medium to large-scale applications…

View on GitHub

Layers breaking down

Application Layer

This layer is responsible for handling framework and tools, also it'll connect directly to the user.

This Layer is based on MVVM (Model-ViewModel-View) Architecture.

This architecture Helps us separate the business logics (controller), UI logics (ViewModel) and UI (View).

To decrease the size of the article we separated application layer document to a separated document.

For application layer concepts visit this doc and also article which we mentioned inside of it to get master at MVVM in react based projects:
application layer architecture

Feature Layer

This layer responsibles for just business logics.

Domain

This layer is a part of Feature layer which is the heart of our app and it just care about the main business logics of the app.
So This layer is independent of any specific technology or framework and represent the fundamental concepts and rules of the business domain.
User domain layer in the project

This layer contains three parts:

Entity: Is our business object and contains our business rules.

  Example: `User` entity represents:
    - `id`
    - `firstName`
    - `lastname`
    - Also some business object logics like `getFullName`

Example Code in the project: user.entity.ts

Usecase: The Use Case represents the main business logic of the application and orchestrates the overall process flow. It interacts with entities and communicates with external systems through repositories (IRepository).
In this scenario, the primary benefit is the separation of core business logic from external frameworks and third-party dependencies, ensuring encapsulation and maintainability of the application.
```
Example:
In an e-commerce application:
`PlaceOrderUseCase`:
Manages the process of placing an order, including validation, inventory management, and order creation.
Utilizes IProductRepository to retrieve and update product information without directly coupling to the database or external APIs.
```
Example code in the porject: create-user.usecase.ts
I-Repository: It's an interface to define a contract for data access operations within the application. It abstracts away the details of specific data storage implementations (such as databases or external services) from the usecase.
Example code in the porject: user.repository.interface.ts

So our usecase knows how to communicate with outside of the app through I-Repository.

This is exactly the adapter pattern which our repository will work as our adapter in our project. To learn more about adapter pattern check this link.

Data

This layer is responsible for interfacing with external systems and services, adapting their data formats and logic into business entities that the application can use.
user data layer in the project

Repository: It implements the IRepository interface defined in the domain layer. It serves as a bridge for managing data format adaptation between the application's business entities and external data sources. In essence, the Repository acts as an adapter between use cases and external services.

Example code in the project: user.repository.ts

This repository uses Mapper to turn data format between application business entities and datasources.
user.mapper.ts

Note: For more details about feature layer, class diagram, code example, testing of this layers, you can visit this document:
feature layer architecture

Bootstrap layer

Bootstrap layer represents configs and initial configuration of application. It includes DI configuration, localization configuration, configuration for graphql, httpHandled and local storage, base classes for context, view and vm.

It has these folders:

boundary - to implement library boundary.
config - configuration for application.
di - DI configuration.
global-types - typescript types to be used in any place of project.
helper - place for extract frequently encoutered functions, classes and types.
i18n - localization configuration.

Layers Connection

For connecting layers we uses DI(dependency-injection) by tsyringe.

Note: Fore more details about DI, Structures and usage examples, please visit DI documentation from Clean Architecture Layering in Next.js with DI

Folder structuring

└── src/
    ├── app/
    │   └── users/
    │       ├── controllers
    │       ├── view/
    │       │   ├── server
    │       │   └── client/
    │       │       └── some-component/
    │       │           ├── some-component.view.tsx
    │       │           ├── stories
    │       │           └── style/
    │       │               └── i-vm
    │       ├── page
    │       └── vm
    ├── feature/
    │   ├── core/
    │   │   └── users/
    │   │       ├── data/
    │   │       │   ├── repository
    │   │       │   └── mapper
    │   │       └── domain/
    │   │           ├── failure
    │   │           ├── i-repository
    │   │           ├── entity
    │   │           └── usecase
    │   ├── support
    │   └── generic
    ├── bootstrap/
    │   ├── boundary
    │   ├── config/
    │   │   ├── server
    │   │   └── client
    │   ├── di
    │   ├── endpoint
    │   ├── helper
    │   └── i18n
    └── test/
        ├── common
        ├── unit
        └── e2e

DDD aproach in folder structuring

For folder structuting we can following Domain Driven Design approach. A domain is a subject area that describes a set of business problems and goals. We have 3 domains in our project

core - all the features that are related to the main purpose of the project.
generic - reusable logic to use in any place from project.
support - logic that helps to perform logic.

Each one of them has subdomains for separate feature.

For example for buisness layer of User feature we will go inside of src/features/core/user.

Conclusion

Clean Architecture in Next.js ensures a scalable, maintainable, and testable codebase by separating concerns into distinct layers: Application (UI), Feature (business logic), and Bootstrap (configurations).

Why It Works:
Decoupled Logic – Business rules stay independent of frameworks.

Easy Testing – Isolated layers simplify unit and integration tests.

Flexible Growth – Features can expand without tight coupling.

By using Dependency Injection and Domain-Driven Design, teams can collaborate efficiently while keeping the codebase clean and adaptable.

Every interaction helps these best practices reach more developers!

Clean Architecture Layering in Next.js with DI

behnam rahimpour — Fri, 02 May 2025 14:42:17 +0000

Di Architecture
- Table of Contents
- Overview
- Requirements
- Usecase
  - Where we Use DI
- Feature layer
  - DI Key: Interface-Based Binding
  - Module
  - Features di
  - Usage
- Application layer
  - vm key
  - App module
  - Provider
  - Usage
- Conclusion

Overview

Dependency Injection (DI) is one of the most debated design patterns in software development. While opinions vary on whether it’s universally beneficial, one thing is certain: DI can be extremely useful if not treated as a "golden hammer." Overusing it, such as blindly injecting every dependency, can lead to unnecessary complexity rather than cleaner code.

In this article, we’ll explore how DI can be effectively applied in Next.js, striking the right balance between scalability and simplicity and also tree shaking friendly to avoid messing the bundle size.

Requirements

This article builds on the architecture outlined in the Next.js Boilerplate repository. To fully understand the implementation, I recommend reviewing these two foundational documents first:

We've included direct file references to key implementations in the main repository for each example.

To explore all concepts in depth and see a production-ready boilerplate and following these best practices, visit:

behnamrhp / Next-clean-boilerplate

A Full featured nextjs boilerplate, based on clean architecture, mvvm and functional programming paradigm.

Nextjs clean architecture boilerplate

Table of content

Nextjs clean architecture boilerplate

Overview

This project is a starting point for your medium to large scale projects with Nextjs, to make sure having a structured, maintainable and scalable foundation for your Next.js project based on best practices in clean architecture, DDD approach for business logics, MVVM for the frontend part, storybook and vitest for testing and, localization and also functional programming with error handling for business logics.

Motivation

Next.js and many other modern SSR frameworks provide powerful tools and a fresh approach to frontend development. However, since these tools are relatively new, the focus has largely been on features rather than software engineering best practices.

As a result, many teams use Next.js for its capabilities but neglect maintainability, architecture, and scalability—especially in medium to large-scale applications…

View on GitHub

Usecase

In Next.js applications, we organize the project into two primary layers:

Feature Layer – Contains all business logic.
Application Layer – Handles communication with Next.js and React APIs.

Where we Use DI

We apply DI only between components that:

Require minimal knowledge of each other (loose coupling).
Can work independently but integrate seamlessly.

We apply dependency Injection (DI) in different ways in each layer:

Feature Layer
- Usage: DI connects UseCase and Repository via interfaces, following the Adapter Pattern.

Purpose: Ensures business logic remains decoupled from data sources (e.g., databases, APIs).

Application Layer
- Usage: DI bridges ViewModel (VM) and View, adhering to the Bridge Pattern.

Special Case: When passing a VM from a Server Component to a Client Component, we use a unique VM key for serialization.

Also global and other dependencies.

Feature layer

As mentioned earlier, we use Dependency Injection (DI) in the Feature Layer to connect the UseCase and Repository layers via interfaces.

DI Key: Interface-Based Binding

To link a UseCase with its corresponding Repository, we use a unique DI key tied to the repository interface. This ensures type-safe dependency resolution.

Example:

export default interface UserRepository {
  create(params: CreateUserParams): ApiTask<true>;
  update(params: UpdateUserParams): ApiTask<true>;
  delete(ids: string[]): ApiTask<true>;
}

export const userRepoKey = "userRepoKey";

file: user.repository.interface.ts

As you see in this file we have a userRepositoryKey Which we use to register a repository and also use it in usecase to use this repository inside of it.

Module

In Domain-Driven Design (DDD), a Module serves as a high-level organizational unit that groups related domain concepts. For example, all user-related domain logic (entities, repositories, services) would be organized within a User Module, where we also centralize its dependency injection (DI) registrations.

Example:

export default function userModule(di: DependencyContainer) {
  di.register(userRepoKey, UserRepositoryImpl);

  return di;
}

file: User module.

Let's examine the key aspects of this file:

Architectural Layer Responsibility:

This component has visibility into both domain repository interfaces (i-repo) and concrete repository implementations. According to Clean Architecture principles, this dual knowledge properly places it in the Data Layer.
Dependency Injection Setup:

We get a child DI container that registers all domain repositories and dependencies implementation.

Features di

To effectively organize, manage, and register all domain modules, we require a centralized component to handle these responsibilities:

Example:

/**
 * On adding new domain module, just add it to this list
 */
const moduleKeyToDi: Record<
  string,
  (di: DependencyContainer) => DependencyContainer
> = {
  [authModuleKey]: authModule,
  [userModuleKey]: userModule,
};

const memoizedDis: Record<string, DependencyContainer> = {};

export default function featuresDi(module: string): DependencyContainer {
  if (memoizedDis[module]) return memoizedDis[module];
  const moduleDiHandler = moduleKeyToDi[module];
  if (!moduleDiHandler)
    throw new Error(`Server Di didn't found for module: ${module}`);

  const moduleDi = moduleDiHandler(di.createChildContainer());
  globalModule(moduleDi);
  memoizedDis[module] = moduleDi;
  return moduleDi;
}

export function diResolve<T = unknown>(module: string, key: InjectionToken): T {
  return featuresDi(module).resolve<T>(key);
}

file: Feature di.

This implementation includes a method for retrieving domain-specific dependency injection (DI) configurations using unique module keys. Each domain is assigned a distinct identifier to ensure proper isolation and organization.
For reference, see the user domain domain module key in the user-module-key file.

Also in feature di file by adding new module for new domains we can add new domain module to the list of moduleKeyToDi object.

Usage

At the end, we can get the repository in usecase layer like this:

Example:

export default async function createUserUseCase(
  params: CreateUserParams,
): Promise<ApiEither<true>> {
  const repo = diResolve<UserRepository>(userModuleKey, userRepoKey);

  return repo.create(params)();
}

file: createUserUseCase

Application layer

Unlike the feature layer, the application layer follows a different architectural approach. Here we implement the MVVM (Model-View-ViewModel) pattern, where Dependency Injection plays a crucial role in passing ViewModels from server components to client-side views.

vm key

For a vm we can have a unique key to register the vm by a single unique string

App module

In each page or route we can define a module to register all vms and any other parts to our di like this:

Example:

/**
 * Each page can have its own di to connect all vms, usecases or controllers
 */
export default function dashboardAppModule() {
  const dashboardDi = di.createChildContainer();

  dashboardDi.register(
    createRandomInvoiceButtonVMKey,
    CreateRandomInvoiceButtonVM,
  );

  return dashboardDi;
}

file: Dashboard app module

Provider

We can distribute our dependency injection container throughout the component tree by implementing a provider pattern. This enables any component to access registered ViewModels while maintaining proper dependency isolation.

Example:


export default function Layout({ children }: { children: React.ReactNode }) {
  const di = useRef(dashboardAppModule());
  return (
    <ReactVVMDiProvider diContainer={di.current}>
      <div className="flex h-screen flex-col md:flex-row md:overflow-hidden">
        <div className="w-full flex-none md:w-64">
          <SideNav />
        </div>
        <div className="flex-grow p-6 md:overflow-y-auto md:p-12">
          {children}
        </div>
      </div>
    </ReactVVMDiProvider>
  );
}

file: Dashboard layout

In this example as we're using ReactVVM package, we passed the di to this library's provider so it can connect View to our vm, automatically based on passing Vmkey to the view component.

Usage

For a concrete implementation example, let's examine how to pass a ViewModel for random invoice generation to a button component.

Example:

export default async function LatestInvoices() {
  const latestInvoices = await latestInvoicesController();

  return (
    <div className="flex w-full flex-col md:col-span-4">
      ...
        <Button vmKey={createRandomInvoiceButtonVMKey} />
      ...
    </div>
  );
}

file: Latest Invoice

As you see we passed the vm key to the view by vmKey prop to the Button component.

Conclusion

In this article, we explored a Clean Architecture approach using Dependency Injection (DI) to decouple business logic, applying DDD principles to connect UseCase and Repository layers via interfaces for maintainability and testability.

For the Application Layer, we implemented an MVVM pattern, using unique VM keys to bridge server and client components while ensuring reusability and single responsibility via the Bridge Pattern. This keeps UI logic clean and scalable across Next.js applications.

By structuring DI registration around domain modules and centralized providers, we achieve a flexible, maintainable architecture that works seamlessly in both server and client contexts.

Every interaction helps these best practices reach more developers!

A Simple Way to Organize API Endpoints Like a Senior

behnam rahimpour — Thu, 01 May 2025 17:33:11 +0000

Endpoints architecture
- Table of Contents
- Overview
- Endpoints architecture
- Endpoints explanations
  - BaseEndpoint
  - SpecificEndpoint
- EndpointsProvider
- Usage example
- Conclusion

Overview

API URLs, versions, and endpoints are among the most volatile parts of any application. Since they depend on external services, frequent changes can quickly lead to:

Spaghetti code (scattered URL strings)
Brittle integrations (tight coupling with third-party APIs)
Maintenance nightmares (manual updates across files)

This architecture solves those problems by:

Centralizing endpoint logic in dedicated classes.
Abstracting URL construction behind reusable methods.
Isolating versioning/base URLs for easy updates.

Result: Your core code stays clean, even when APIs change.

This article is a part of set of articles about clean architecture in Next.js, to explore all concepts in depth and see a production-ready boilerplate and following these best practices, visit:

behnamrhp / Next-clean-boilerplate

A Full featured nextjs boilerplate, based on clean architecture, mvvm and functional programming paradigm.

Nextjs clean architecture boilerplate

Table of content

Nextjs clean architecture boilerplate

Table of content

Overview

Motivation

Technologies

Architecture

Folder structure

Requirements

Getting Started

Local

Docker

naming convetions:

Overview

This project is a starting point for your medium to large scale projects with Nextjs, to make sure having a structured, maintainable and scalable foundation for your Next.js project based on best practices in clean architecture, DDD approach for business logics, MVVM for the frontend part, storybook and vitest for testing and, localization and also functional programming with error handling for business logics.

Motivation

Next.js and many other modern SSR frameworks provide powerful tools and a fresh approach to frontend development. However, since these tools are relatively new, the focus has largely been on features rather than software engineering best practices.

As a result, many teams use Next.js for its capabilities but neglect maintainability, architecture, and scalability—especially in medium to large-scale applications…

View on GitHub

Endpoints architecture

The following class diagram shows the architecture of endpoints:

Endpoints explanations

BaseEndpoint:

The Endpoint class is implemented for manipulating API endpoints within an application.
the Endpoint class requires two parameters: baseURL and apiVersion, which represent the base URL of the API and the version of the API being used.

export default class Endpoint {
  protected baseURL: string;

  protected apiVersion: string;

  constructor({
    baseURL,
    apiVersion,
  }: {
    baseURL: string;
    apiVersion: string;
  }) {
    this.apiVersion = apiVersion;
    this.baseURL = baseURL;
  }

  static compose(uris: string[]) {
    return Endpoint.sanitizeURL(uris.join("/"));
  }

  protected buildEndpoint(endpoint: string) {
    return Endpoint.sanitizeURL(
      `${this.baseURL}/${this.apiVersion}/${endpoint}`,
    );
  }

  static sanitizeURL(url: string) {
    return url.replaceAll(/(?<!:)\/\//g, "/");
  }
}

Endpoint class has several methods:

compose Method (Static) This static method, takes an array of strings representing different parts of the URL and returns a sanitized URL by joining these parts together. It ensures that the URL is properly formatted and free of any unnecessary double slashes or incorrect separators.
buildEndpoint Method This instance method, buildEndpoint, is responsible for constructing a complete endpoint URL by appending a specific endpoint to the base URL and API version. It returns a sanitized URL string ready for use in API requests.
sanitizeURL Method (Static) You can use this method to ensure that the constructed URLs are correctly formatted. It replaces any occurrences of consecutive slashes with a single slash, ensuring that the URL is valid and compliant with URL standards.

Overall, The Endpoint class offers a convenient and reliable way to construct and manage endpoint URLs within an application. It enables team members to use a shared language when working with third-party libraries, reducing the risk of bloating the main application code due to API or UI changes in external dependencies.

SpecificEndpoint

Every specific endpoint class extends the functionality of the Endpoint class and introduces additional features specific to this specific endpoint. This inheritance includes methods for composing and building endpoint URLs.
The specific endpoint encapsulates private properties, these properties are URLs for a specific endpoint.
The following is an example about making a specific endpoint and how it extends the base endpoint:

export default class BookEndpoint extends Endpoint {
  private addBookEndpoint: string;

  private booksEndpoint: string;

  get addBook() {
    return this.buildEndpoint(this.addBookEndpoint);
  }

  get books() {
    return this.buildEndpoint(this.booksEndpoint);
  }

  constructor({
    addBookEndpoint,
    booksEndpoint,
    baseURL,
    apiVersion,
  }: {
    addBookEndpoint: string;
    booksEndpoint: string;
    baseURL: string;
    apiVersion: string;
  }) {
    super({
      apiVersion,
      baseURL,
    });
    this.addBookEndpoint = addBookEndpoint;
    this.booksEndpoint = booksEndpoint;
  }
}

As you see the BookEndpoint class extends Endpoint to provide a structured way of managing book-related API endpoints. It encapsulates endpoint construction logic, ensuring consistency and reusability across the application.

EndpointsProvider

The EndpointsProvider class offers centralized static methods for retrieving various endpoints used in the application. Each method returns an instance of a specific endpoint class, preconfigured with the necessary URLs and settings.

By encapsulating the logic for creating and configuring endpoints, this class simplifies access and usage across the application. Below is an example of how the EndpointsProvider works:

import BookEndpoint from "~/bootstrap/helper/endpoint/endpoints/book-endpoints";
import appConfigs from "~/bootstrap/config/app-configs";

/**
 * Provides static methods to retrieve different types of endpoints.
 */
export default class EndpointsProvider {
  /**
   * Book api
   */
  static book() {
    return new BookEndpoint({
      apiVersion: "api/v1",
      addBookEndpoint: "book/add",
      booksEndpoint: "book",
      baseURL: appConfigs.baseApis.book,
    });
  }
}

Note: The EndpointProvider step is optional to make the code agnostic about the changes or replacing of BookEndpoint with any other one. Instead, you can statically define all required endpoint configurations directly in the endpoint class's constructor. It's your choice based on the flexibility that your projects need.

Usage Example

You can see implementation examples in this Next.js boilerplate:

Endpoint Files

Endpoint implementations Contains two endpoint types:
1. HTTP backend API connections
2. Identity provider API connections

Implementation

Repository usage Demonstrates how backend endpoints are consumed throughout the application

Conclusion

Managing API endpoints effectively is crucial for building maintainable applications in our API-driven world. The architecture we've explored:

✅ Isolates volatile API configurations from business logic

✅ Standardizes endpoint management across your codebase

✅ Dramatically reduces tech debt when APIs inevitably change

By implementing this pattern, you'll spend less time on finding and fixing broken endpoints and more time building features by separating api management responsibility in an isolated layer.

Remember: Good architecture isn't about preventing change - it's about making change manageable.

Every interaction helps these best practices reach more developers!

How to Automate Failure Handling and Messages with This Design!

behnam rahimpour — Thu, 13 Mar 2025 21:05:46 +0000

What is a failure

In each application and in each logic, there can be failures in the process, and based on their complexity, there can be a few or many possible scenarios for these failures.

In software development, we always try to have more control over these failures to:

Avoid possible bugs
Help users understand the state of the application with proper messages
Control processes for side effects
Monitor the behavior of the application

So, having a specific way of handling errors to achieve all these requirements in our app helps us build a more robust, reliable, and maintainable application.

Many frameworks provide their own ways to handle these failures, which they may call exceptions, failures, or other terms. But we shouldn't always depend on the behavior of frameworks for our logic and apps. Besides, many frameworks do not provide error handling tools, so we need to design a reliable architecture for the error handling in our application.

Failure handling with base failure

To have granular control over failures and define a specific type for all errors, we can use the power of inheritance and abstraction in OOP.

We can define an abstract class as our base failure, which serves as the specific type for all failures in the application.

export default abstract class BaseFailure<META_DATA> {

  metadata: META_DATA | undefined;

  constructor(metadata?: META_DATA) {
    this.metadata = metadata ?? undefined;
  }
}

As you can see, it's just a simple abstract class that takes some metadata about the error details in any form. But wait, this is just the beginning of the story, we can explore many ideas with this failure.

How to write a simple failure

So, to create a simple failure, we can define our failure in any domain for any scenario we need, like this:

export default class CreateUserFailure extends BaseFailure<{ userId: string }> {
  constructor(metadata?: { userId: string }) {
    super(metadata);
  }
}

So in our logics for creating user we can return specific type of failure for creating user.

Combination with Functional programming

Functional programming is a deep topic that we cannot fully cover here. For more details, you can check out various courses and books available online.

However, for this article, we focus on one of the most useful functors in functional programming and how failure fits perfectly with it. This concept is the Either type.

Either is an algebraic data type (ADT) that represents computations that can return either a success or a failure. It consists of two possible values:

Right(value): Represents a successful result.
Left(error): Represents a failure or unexpected result.

You're guessing right, our base failure will serve as the Left value in Either, allowing us to handle errors in a structured and functional way.

Either<
  BaseFailure<unknown>,
  ResponseType
>

So as we always have specific type for handling unexpected results, so we can define a new type for either in our app.

export type ApiEither<ResponseType> = Either<
  BaseFailure<unknown>,
  ResponseType
>;

So, for any API calls, we can use the Either type to handle both success and failure cases.

Additionally, for asynchronous processes, we use TaskEither, which works similarly to Either but is designed for handling asynchronous operations.

type ApiTask<ResponseType> = TaskEither<BaseFailure<unknown>, ResponseType>;

For example, when creating a customer repository to handle all API calls for customers, we can use this type to manage success and failure cases.

export default interface CustomerRepo {
  fetchList(query: string): ApiTask<Customer[]>;
}

And in the repo we can have this pipe to get customer data:

Note: In functional programming, a pipe is a composition of functions where the output of one function is passed as the input to the next, allowing for a clean, readable flow of data transformations.

pipe(
      tryCatch(
        async () => {
          ...// calling api and returning result
        },
        (l) => failureOr(l, new NetworkFailure(l as Error)),
      ),
      map(this.customersDto.bind(this)),
    ) as ApiTask<Customer[]>;

As you can see, in the try-catch block, which is the constructor of ApiEither, we define the right response in the first callback and the failure in the second callback argument.

failureOr is just a helper function that takes an error and converts it into a specific failure type, NetworkFailure in this example.

This ensures that during the process of fetching customer data, we always know the unexpected result will be of a specific type.

export function failureOr(
  reason: unknown,
  failure: BaseFailure<any>,
): BaseFailure<any> {
  if (reason instanceof BaseFailure) {
    return reason;
  }
  return failure;
}

So in the process of fetching customer we know the unexpected result, always will be a speicfic type.
So in any layer we can get the failure do some logics on left response based on its metadata and turn the failure shape to any other failure shape and use it for different purposes.

Usecases of this idea

There are many situations where, if an important process encounters problems, we want to have control over it. We need to know when and why these issues happened and store that information in one of the monitoring tools.

For example, when a CreateUserFailure occurs in the repository layer, we can send a log with the specific time and relevant parameter data to any logging or monitoring tool.

Monitoring on bugs with dev failures

There are many situations, especially in frontend applications, where unexpected behavior occurs due to development mistakes or bugs. For example, when bugs or data changes in APIs happen, it's possible to face unexpected behaviors. In such cases, we want to show a specific message or redirect the user to an error page with a clear message.

Additionally, in frontend applications, logs may not be directly available in these situations, as the issue occurs on the user's system. To handle this, we can send metadata as a log to an API when encountering development failures.

To achieve this, we can simply define another abstract failure like this:

export default abstract class BaseDevFailure<
  META_DATA,
> extends BaseFailure<META_DATA> {}

As you can see, it’s just another failure that extends from the base failure.

For example, in some parts of the application, when sending dynamic arguments into the domain layer, there's a possibility of sending unexpected data. In such situations, we can define a specific development failure like this:

export default class ArgumentsFailure<
  META_DATA,
> extends BaseDevFailure<META_DATA> {
  constructor(metadata?: META_DATA) {
    super(metadata);
  }
}

So we can consider this scenario in our logics and facing with this failure we can make a log request to our log api even from frontend applications, so on facing with this situation they can show a descent message to user to contact to support team at the same time they store the bug log to have full controll on these situations.

Manage translations and error messages with failure

With this approach, we can go a step further than just error handling and even manage translations and display related messages in frontend applications automatically.

For each process and scenario, we should define a specific failure. At the same time, for each failure, we should display a corresponding message in the selected language based on the user's preference.

We can use this idea to automate both the error handling and message translation process.

To achieve this, we can pass a unique string key from the constructor based on the failure scenario. Our base failure will look like this:

export default abstract class BaseFailure<META_DATA> {
  private readonly BASE_FAILURE_MESSAGE = "failure";

  /**
   * Use this message as key lang for failure messages
   */
  message = this.BASE_FAILURE_MESSAGE;

  metadata: META_DATA | undefined;

  constructor(key: string, metadata?: META_DATA) {
    this.message = makeFailureMessage(this.message, key);
    this.metadata = metadata ?? undefined;
  }
}

/**
 * Gets Message key and it'll add it to the failure message key hierarchy
 */
export function makeFailureMessage(message: string, key: string) {
  if (!key) return message;
  return `${message}.${key}`;
}

As you can see, we have a message property, which contains BASE_FAILURE_MESSAGE, the base key for all failure messages. It also accepts a key from the constructor, and with the makeFailureMessage function, it concatenates the new key with the message, shaping a unique message for each failure.

Each failure can have its own key passed from its constructor.

In the end, we can have a chained message key that we can use as the message key for each failure.

For example, for a failure like UserAlreadyExistsFailure, we can have a parent failure for all user domain failures, like this:

export default class UserFailure extends BaseFailure {
  constructor(key: string) {
    super(makeFailureMessage("user", key));
  }
}

and now we can define our failure:

export default class UserAlreadyExistsFailure extends UserFailure {
  constructor() {
    super("alreadyExists");
  }
}

so the result of message for UserAlreadyExistsFailure, will be failure.user.alreadyExists.

At the same time, in another part of our project, we're using a langKey object to specify the translation key. This object, like the failure structure, follows the domain and folder structure to specify the language key.

const langKey = {
  // ...
    failure: {
      user: {
        alreadyExists: "failure.user.alreadyExists",
      }
  }
}

So, we can use our failure message key to retrieve the language key. By passing it to the translation method, we can get the translated failure message and automate the process of displaying the error message based on the failure we encounter.

const usecaseResponse = await getUsersUsecase() as Promise<Either<BaseFailure, User[]>>

if (!isLeft(usecaseResponse)) return;
  if (!(usecaseResponse instanceOf BaseFailure)) return;

const translatedFailureMessage = t(usecaseResponse.left.message)

This is the final version, class diagram for our failur architecture:

Conclusion

In this article, we've explored how to handle failures effectively in software applications by combining error handling with functional programming concepts like the Either type.

Furthermore, by integrating these failure handling mechanisms with automated processes for translating and displaying error messages, we create a more seamless experience for users, no matter the scenario. This approach not only improves the user experience by offering clear and context-specific messages, but it also provides valuable insights through monitoring and logging, enabling teams to quickly address issues.

Ultimately, this architecture supports building more robust, maintainable, and user-friendly applications, which I have used in many of my own projects, especially in frontend ones.

Cracking the Code: How the MVVM with Bridge Pattern Saves a Messy Frontend UI (Part 2)

behnam rahimpour — Sun, 01 Dec 2024 13:49:53 +0000

Note: This is the second part of our series on the MVVM architecture in the frontend. If you haven’t read the first part yet, we highly recommend starting here.

Bridge Pattern Coding Example

In the first part of this series, we discussed how the Bridge Pattern can enhance the reusability and maintainability of UI components in a large-scale frontend application. While we focused primarily on the high-level design with uml class diagrams, the real challenge lies in its implementation. After all, even the best designs are merely theoretical without effective implementation.

Example: A Reusable Button Component

Let’s walk through a simple example: creating a button component that is reusable across different contexts and logic in our application.

The Bridge Pattern in Action

To achieve this, we use an interface to establish a convention between the UI (view layer) and the UI logic (view model layer). This interface acts as a bridge, enabling the separation of concerns and improving flexibility.

interface ButtonUiLogic {
  props: {
    title: string;
    disabled: boolean;
  }
  onClick(e: MouseEvent): void 
}

When building reusable components, it's important to distinguish between props (state-driven UI data) and events (interactions or behaviors triggered by the user).

In our example, the props define the visual and state attributes of the button, such as title and disabled. Meanwhile, the events, such as onClick, are passed separately to handle interactions outside the UI logic. This convention can help you to have a clear separation and also can help you in some memoization down the road.

interface ButtonProps {
  uiLogic: ButtonUiLogic;
  ... // rest of props comes from the parent
}

Abstraction layer (UI)

Now its time to handle our abstraction layer of bridge pattern which is a button component.

function AppButton(props: ButtonProps) {
  const { uiLogic } = props;

  return (
    <button disabled={uiLogic.props.disabled} onClick={uiLogic.onClick}>
      {uiLogic.props.title}
    </button>
  );
}

In this code you can see that we got our uiLogic from our props and binding events and props of ui logic to the UI part which is nothing but a react component. It’s responsible just to decide how to show the data and how to connect behaviors to the UI.

Implementation layer (UI logic)

The implementation layer in the Bridge Pattern defines the behavior and state logic of the component. For our button example, we’ll implement a counting button that increments a counter every time it’s clicked.

This example demonstrates how the UI logic handles the component's state and provides props for the UI, ensuring a clean separation of concerns.

class CounterUILogic implements IBaseUiLogic<ButtonUiLogic> {
  useUiLogic(): ButtonUiLogic {
    const [count, setCount] = useState(0);

    return {
      props: {
        disabled: false,
        title: `Current counter is: ${count}`,
      },
      onClick: () => setCount((prev) => prev + 1),
    };
  }
}

You can see we used a class which implements IBaseUiLogc by passing correspond ButtonUiLogic as generic to it which is nothing but.

export default interface IBaseUiLogic<UI_LOGIC> {
  useUiLogic(): UI_LOGIC;
}

You can see that this interface is just a convention for having one custom hook with a specific name to handle ui logic inside of it.

So you can see instead of having many implementation of one ui component for each logic, we can have thousands of UI logic for one UI for any purpose, like submit a form, open a modal, etc. Most of the hooks, connection to business logic to fetch the data, manipulating the state of the component, will happen in this layer.

Connection

Let’s review the design together one more time.

The connection between the UI and UiLogic layers is critical for ensuring seamless interaction while maintaining isolation. This connection must ensure:

Encapsulation: The logic and state changes of one component don’t affect others.
Reactivity: The UI updates dynamically when the state in the UiLogic changes.
Reusability: A single component can serve as a reusable environment for various UiLogic implementations.

To achieve this, we’ll create a reusable LogicProvider component. It will encapsulate the UiLogic and provide the necessary bridge to the UI.

interface IUiLogicProvider<UI_LOGIC> extends PropsWithChildren {
  Ui: FC<any & { uiLogic: UI_LOGIC}>;
  UiLogic: IBaseUiLogic<UI_LOGIC>;
  restProps?: Record<string, any>;
}

function UiLogicProvider<UI_LOGIC>(props: IUiLogicProvider<UI_LOGIC>) {
  const { Ui, UiLogic, restProps, children } = props;
  const uiLogic = UiLogic.useUiLogic();

  const allProps = {
    ...restProps,
    uiLogic,
  };

  return <Ui {...allProps}>{children}</Ui>;
}

In this basic component we’re getting UiLogic instance and based on the interface convention for our UI logic we call our ui logic to run and pass the result to the Ui.
Notes and Optimization Tips

Encapsulation: The UiLogicProvider encapsulates all the logic-specific state updates and re-renders, ensuring other components remain unaffected.
Automatic Memoization: By wrapping this provider with memo, you avoid the need to explicitly use React.memo or similar techniques for each child component as you know your UI component should just be rerendered by changes of the Uilogic not rerendering of the parents. This ensures optimal performance without extra effort in an automatic way.

For example:

export default memo(UiLogicProvider, (prevProps, currProps) => {
  if (
    prevProps.restProps !== currProps.restProps ||
    prevProps.children !== currProps.children
  )
    return false;
  return true;
});

This component is the most basic one. You can get the base concept of it and use it with other ideas and techniques as well. The main concept is one layer will handle calling the Ui logic to avoid other components getting affected by this component.

Last part
The last part will be the easiest one. Just from required parent component connect Ui and Ui logic with our provider.

function App() {
  return (
    <div>
      <UiLogicProvider Ui={ButtonComponent} UiLogic={new CounterUILogic()}  />
      <UiLogicProvider Ui={ButtonComponent} Uilogic={new CancelButtonLogic()} />
    </div>
  );
}

Transitioning to MVVM Architecture in Bridge Pattern

In the MVVM (Model-ViewModel-View) architecture:

Model: Handles the business logic and manipulates stored data.
ViewModel (VM): Focuses on UI logic and connects the Model to the View.
View: Manages the UI rendering and binds to the ViewModel via an interface, typically called IVM, which acts as the Bridge.

This architecture builds on the Bridge Pattern we discussed earlier, but introduces a Model layer to separate business logic, ensuring a clean and scalable foundation for large-scale applications.

Mapping Bridge Pattern to MVVM

Here’s how the Bridge Pattern concepts translate into MVVM:

Bridge Pattern	MVVM	Role
Abstraction Layer	View	Reusable UI components that bind to the ViewModel.
Bridge	IVM Interface	Connects the View to the ViewModel.
Implementation Layer	ViewModel (VM)	Handles UI logic and mediates between View and Model.
-	Model	Business logic and data manipulation.

Till now we had all our logic inside of the Implementation layer part if we separate business logic into separate classes or functions and we name it as a model. So the only remains in Implementation is just real UI logic and just with one connection with the model we can send all data to UI and handle UI logic as well.
In this case we’ll have a clean foundation architecture based on MVVM for our large scale application that is reusable, maintainable and testable.

Now in MVVM (Model-ViewModel-View) our Model is responsible for business logic, ViewModel is responsible for UI logic and connecting model to view and then we’ll have our reusable View part that connects to ViewModel with one interface as the IVM which plays our bridge.

Now lets review the diagram but this time in MVVM architecture.

Now you can see in the above diagram that View is replaced with an abstraction layer, IVM replaced with Bridge and VM replaced with an implementation layer. Also we add Model as a layer which is responsible for business logics and manipulation of stored data.

Now we can translate our code example to MVVM shape. For this reason we need to just replace the UI name with View and UiLogic with VM. That’s it now you have a base MVVM approach architecture in your react.

Rewriting the example in MVVM

View (UI)

function AppButton(props: ButtonProps) {
  const { vm } = props;

  return (
    <button disabled={vm.props.disabled} onClick={vm.onClick}>
      {vm.props.title}
    </button>
  );
}

IVM and IProps (Bridge)

interface ButtonVM {
  props: {
    title: string;
    disabled: boolean;
  }
  onClick(e: MouseEvent): void 
}

interface ButtonProps {
  vm: ButtonVM;
  ... // rest of props comes from the parent
}

VM (UI Logic)

CounterVM implements IBaseVM<ButtonVM> {
  useVM(): ButtonVM {
    const [count, setCount] = useState(0);

    return {
      props: {
        disabled: false,
        title: `Current counter is: ${count}`,
      },
      onClick: () => setCount((prev) => prev + 1),
    };
  }
}

Final Conclusion

With this journey, we’ve wrapped up building a clean MVVM architecture in a React application, ensuring it aligns with the best practices of performance and software architecture.

Separation of Concerns: Each layer has a distinct responsibility with using Model, ViewModel (VM), View.
Bridge Pattern Integration: The IVM interface serves as the Bridge, providing a clean abstraction between the View and the ViewModel, making the architecture flexible and reusable.
Reusability and Testability: Models, ViewModels, and Views are independently reusable and testable, ensuring long-term maintainability and reducing the cost of changes.
Performance Optimization: With the use of a UiLogicProvider, we’ve ensured that re-renders are isolated to only the relevant components. By encapsulating the ViewModel logic, we’ve also enabled automatic memoization, avoiding unnecessary re-renders across the application.
Scalability: The modular design makes the architecture inherently scalable, suitable for large-scale applications with complex requirements.

Congratulations on completing these two articles with me! I hope you found them helpful. If you did, please let me know in the comments and feel free to like and share to help more people discover and benefit from these ideas. I’d also love to hear your suggestions or ideas about coding architecture and approaches that have worked well for you!

Cracking the Code: How the MVVM with Bridge Pattern Saves a Messy Frontend UI (Part 1)

behnam rahimpour — Sun, 01 Dec 2024 12:50:31 +0000

One of the most basic concerns in frontend applications is reusability of UI components. While there are several ideas on how to categorize them, one of the most underrated concepts is how to manage their logic to maintain reusability while also preserving the single responsibility principle for parent components.

What does that mean?

Let's explore this with an example. Imagine we have a card component whose responsibility is to display some detailed information. Naturally, we want to reuse this card component in various scenarios. But where do we handle the data fetching and transformation necessary for displaying in the component? If we place this logic inside the component itself, it will no longer be reusable. So, most of the time, we move these logics to the parent component.

Now, imagine this parent component contains not just the card, but also other components like a SelectBox, input fields, and others. Each of these components, which are also reusable, requires some logic as well. Where do we put this logic? Once again, it ends up in the parent component. This is where the problem arises: we violate the single responsibility principle because the parent component now manages too many details it shouldn't need to know about.
Now, imagine having to modify the logic for one of these components within this increasingly complex parent component. Not to mention the challenge of testing all these intertwined logics.

What's the solution?

In such situations, it's clear that there is a problem with our coding architecture, which could have significant effects on both the development process and the maintainability of the application. We need to rethink how we structure our UI and UI logics to keep components reusable while ensuring their business logic remains specific to each component without cluttering the parent components. This is where the Bridge Pattern comes into play.

Bridge Pattern

Note: This article won't focus on the bridge pattern itself with extensive examples, but rather on the concept as it pertains to this discussion. For more details, you can refer to the gang of four book or refactoring guru.

The Bridge Pattern helps when we have a large class or multiple tightly coupled classes by separating them into two layers: abstraction and implementation.

Abstraction: Don't confuse this with the "abstract" keyword in your programming language. The abstraction layer is the part of the code that handles high-level responsibilities and delegates functionality to the implementation layer.
Implementation: This lower-level module handles all the actual work and logic, returning the results to the abstraction layer.
Bridge: The bridge is the interface that connects the abstraction to the implementation layer.

Each abstraction layer has one corresponding bridge, and based on this bridge, we can have multiple implementations for different purposes.

Now, how does this work in a real-world frontend application?

Bridge Pattern in Frontend Applications

In frontend applications, we often have UI components that need to be reused in multiple places. These components, which are responsible only for displaying data and not for handling logic, represent the abstraction layer.

We mentioned earlier that we need an interface for this abstraction layer, which will act as the bridge.

So, at this point, we have the abstraction and the bridge. The only thing left is the UI logic, which will act as our implementation layer.

Imagine we have a button component. In this case, we create a UI component that serves as the abstraction layer with an interface acting as the bridge. On the other hand, we can have multiple UI logics for this button for different purposes, and they all follow the bridge interface.

You can visualize this relationship in the following class diagram:

In the above example, you can see how we can have multiple UI logics for a reusable UI component through one interface that serves as the bridge.

Now, you might wonder how we connect one UI logic to its respective UI component. This is where the parent component comes in - it knows which UI logic is associated with which UI component. In this setup, the parent component simply connects the child components to their corresponding UI logics without knowing any of the details. This is the parent component's only responsibility.

This is the revised version of the previous diagram with considering the connection between UI and UI logics.

Benefits

With this approach, your code becomes much more maintainable. Any changes in one implementation layer won't affect the parent component or the UI itself. Additionally, the code is fully testable: you can write unit tests for your UI logics and test the UI thoroughly using appropriate tools.

The Devil Is in the Details

Of course, these concepts offer only a high-level overview. Implementing this architecture requires careful consideration of framework-related performance issues, like rerendering. In the next article, we'll dive deeper into implementing these ideas using the React framework.

Conclusion

In conclusion, the Bridge Pattern offers a clean solution to the common challenge of maintaining reusable UI components while preventing parent components from becoming cluttered with business logic. By separating concerns between the abstraction and implementation layers, and introducing a bridge to connect them, we ensure that each component remains modular, maintainable, and easy to test. Adopting this architectural approach can significantly improve both the quality and scalability of frontend applications.

DEV Community: behnam rahimpour

How I Monitor My Career Performance

Overview

The Chain of Efforts Rule

Why Monitoring Matters

How I Build My Roadmap and Habits

Creating the Right Habits

That’s how I build the “chain of efforts” we talked about earlier.

Monitoring the Roadmap and Goals

My Favorite Tool for Goal Monitoring: Obsidian

My Key Plugins

My Folder Structure

Tracking Habits

Conclusion

A Practical Guide to GraphQL N+1 Solutions in NestJS

Overview

What is the N+1 problem (why GraphQL often triggers it)

Solutions

Solution Choice

Coding Design

Context-based DataLoader Management

Our requirements

Scenarios and how to apply the tools

Directory design (per-domain batch layer)

Class diagram (PUML)

Implementation guideline

GraphQL Module Configuration

BatchLoad Module Structure

Adding New Domain Batch Loaders

Resolver Usage

Key Implementation Details

Results and complexity comparison

Last consideration: Handling Large Lists

Conclusion

Case Study: How we Cut Blocking Time by 92% in React admin panel - A Story Starring useTransition

Overview

Problem realizing

Excessive API Requests on Page Load

Slow Re-rendering on User Interaction

Solution

Excessive API Requests on Page Load

Laggy UI on url changes

Last shot to remove all unnecessary rerenders in the tree

Performance result

Conclusion

Next.js Localization Best Practices for Enterprise Apps

Table of contents

Requirements

behnamrhp / Next-clean-boilerplate

A Full featured nextjs boilerplate, based on clean architecture, mvvm and functional programming paradigm.

Nextjs clean architecture boilerplate

Table of content

Overview

Motivation

Overview

Guideline for adding new key

Folder acrhitecture

Configuration

Provider and client support

Combination with failure handling and params validation

Conclusion

Why Next.js Apps Struggle at Scale (And How Feature Layers Solve It)

Table of Contents

Architecture overview of the feature layer

behnamrhp / Next-clean-boilerplate

A Full featured nextjs boilerplate, based on clean architecture, mvvm and functional programming paradigm.

Nextjs clean architecture boilerplate

Table of content

Overview

Motivation

Class diagram of feature layer

Layers responsibilities

Data layer

Data transfer object (DTO) / Mapper:

Repository:

Domain layer

Entity:

Enums:

IRepo:

Usecase: