Stop 19 · Frontend System DesignTopics · 2/13

Scalable Architecture

In short

An app that works for one developer can fall apart with ten. Scalable architecture means clear boundaries, so people can change one part without breaking three others.

Designing a frontend codebase so it stays maintainable as the app, team and feature count grow — clear boundaries, low coupling, predictable patterns.

The jaadu station master waves a green flag as three trains run on separate tracks.

Think of it like this

Indian Railways zones

Railways is huge, so it's split into zones, each running its own trains but following shared rules for tracks and signals. A good frontend works the same way: features run independently, but all follow shared rules for how they connect.

Watch it happen

Imports flow one way

app (pages)

features/cart

features/auth

shared/ui

shared/lib

1/5Pages sit at the top. They can import from features and shared code.

The big ideas

What you need to know

Layers with a direction

Pages use features, features use shared code. Shared code should never import from a feature.

Public entry points

Each feature exposes an index.ts. Other code imports only from there, never from its inner files.

Low coupling

Coupling means how much one part depends on another. Less coupling means smaller, safer changes.

Let tools enforce rules

Lint rules can block forbidden imports, so boundaries survive busy weeks and new joiners.

See it in code

Walk through the code

1// eslint.config.js (part of the rules section)2rules: {3  "no-restricted-imports": ["error", {4    patterns: [{5      group: ["@/features/*/*"],6      message: "Import from the feature's index file instead.",7    }],8  }],9},

1/3Turn on ESLint's built-in rule for blocking certain imports.

With this rule, importing @/features/cart/hooks/useCart fails lint. You must use @/features/cart, so the cart team can reorganise its internals freely.

Save yourself the pain

Common mistakes

Oops

Letting any file import any other file because it's quicker today.

Do this instead

Agree on which layers can import which, and add a lint rule so nobody has to remember it.

Oops

Building a complex architecture for a two-page side project.

Do this instead

Match the structure to the size of the app and team. Add boundaries as real pain appears.

Your mission

Draw your dependency map

~30 min

Quick check

Your shared Button component imports a helper from features/checkout. What's the problem?

Go deeper

1Identify the parts of a project that would be painful to change today — that's your coupling.
2Read about layering: keeping UI, business logic and data-access separate.
3Study how a real open-source app of meaningful size is organized.