The backend team talks about bounded contexts, eventual consistency, and service meshes. You're thinking about loading states, stale data, and why the checkout page breaks when the inventory service is slow.

This article is for frontend engineers working in microservice environments. You'll learn how to consume multiple service APIs without creating a tangled mess, how to handle partial failures gracefully in the UI, how to manage distributed state across services, and how to work effectively with backend teams on API contracts because half the battle is communication, not code.

The goal is not to turn you into a backend engineer, it's to give you the mental models and patterns that make frontend development in a microservice world less painful.

Prerequisites

To get the most out of this article, you should be familiar with:

• React or a similar component framework (the examples use React and TypeScript)

• Basic understanding of REST APIs and HTTP

• Experience fetching data in frontend applications (fetch, Axios, or React Query)

• General awareness of what microservices are (you don't need to have built one)

Table of Contents

• The Frontend's Microservice Problem

• Pattern 1: The Backend-for-Frontend (BFF)

• Pattern 2: Handling Partial Failures in the UI

• Pattern 3: Managing Distributed State

• Pattern 4: Taming Multiple API Contracts

• Pattern 5: Timeout Budgets for Page Assembly

• Pattern 6: Error Boundaries Per Service

• Working With Backend Teams on Contracts

• When to Push Back

• Conclusion

The Frontend's Microservice Problem

In a monolithic architecture, the frontend talks to one API. That API owns the database, handles the business logic, and returns exactly the shape of data the UI needs. Life is simple.

In a microservice architecture, that single API fractures into many:

Monolith:
  Browser → API → Database

Microservices:
  Browser → API Gateway → User Service
                        → Order Service
                        → Inventory Service
                        → Payment Service
                        → Notification Service

Each of those services is owned by a different team, deployed independently, and may use different data formats or conventions. As a frontend engineer, you now have several new problems:

1. Multiple contracts: Each service has its own API shape. A "product" in the inventory service has different fields than a "product" in the catalog service.

2. Partial failures: The order service might respond in 50 ms while the recommendation service times out. Your UI needs to handle both.

3. Data consistency: A user updates their address, but the order service still shows the old one because it hasn't synced yet.

4. Increased latency: Assembling a single page might require three or four API calls instead of one.

These aren't backend problems that happen to affect the frontend. They're fundamentally frontend problems that require frontend solutions.

Pattern 1: The Backend-for-Frontend (BFF)

The most impactful pattern for frontend teams in a microservice world is the Backend-for-Frontend. A BFF is a thin API layer that sits between the browser and the microservices. It's owned by the frontend team and exists to serve the frontend's specific needs.

Without BFF:
  Browser → User Service    (call 1)
  Browser → Order Service   (call 2)
  Browser → Inventory Service (call 3)
  3 round trips, 3 contracts to manage

With BFF:
  Browser → BFF → User Service
                → Order Service
                → Inventory Service
  1 round trip, 1 contract to manage

The BFF aggregates calls, transforms responses into the shapes your components need, and handles cross-service concerns like authentication token forwarding.

// BFF endpoint: GET /api/order-summary/:orderId
// Aggregates data from three services into one frontend-friendly response
import express from "express";

const router = express.Router();

router.get("/api/order-summary/:orderId", async (req, res) => {
  const { orderId } = req.params;
  const token = req.headers.authorization;

  try {
    const [order, customer, shipment] = await Promise.allSettled([
      fetch(`\({ORDER_SERVICE}/orders/\){orderId}`, {
        headers: { Authorization: token },
      }).then((r) => r.json()),
      fetch(`\({USER_SERVICE}/users/\){req.userId}`, { // userId set by auth middleware
        headers: { Authorization: token },
      }).then((r) => r.json()),
      fetch(`\({SHIPPING_SERVICE}/shipments?orderId=\){orderId}`, {
        headers: { Authorization: token },
      }).then((r) => r.json()),
    ]);

    res.json({
      order: order.status === "fulfilled" ? order.value : null,
      customer: customer.status === "fulfilled" ? customer.value : null,
      shipment: shipment.status === "fulfilled" ? shipment.value : null,
      errors: [order, customer, shipment]
        .filter((r) => r.status === "rejected")
        .map((r) => r.reason.message),
    });
  } catch (error) {
    res.status(500).json({ error: "Failed to assemble order summary" });
  }
});

Notice the use of Promise.allSettled instead of Promise.all. This is critical in a microservice environment. Promise.all fails fast: if any one service is down, the entire request fails. Promise.allSettled lets you return partial data, which leads directly to the next pattern.

When to Use a BFF

A BFF is worth the investment when:

• Your frontend aggregates data from three or more services per page

• Different clients (web, mobile, admin) need different data shapes from the same services

• You want the frontend team to control response shapes without waiting on backend teams

A BFF isn't necessary when:

• You have an API gateway that already handles aggregation (for example, Apollo Federation for GraphQL)

• You only consume one or two services

• Your backend teams already provide frontend-optimized endpoints

Pattern 2: Handling Partial Failures in the UI

In a monolith, a request either succeeds or fails. In a microservice world, it can partially succeed. The order data loads fine, but the recommendation service is down. The product details are available, but the review service is slow.

Your UI needs to handle this gracefully. The key principle: never let a non-critical service failure break a critical user flow.

// Types for partial data loading
interface ServiceResult<T> {
  data: T | null;
  status: "loaded" | "error" | "loading";
  error?: string;
}

interface OrderPageData {
  order: ServiceResult<Order>;
  recommendations: ServiceResult<Product[]>;
  reviews: ServiceResult<Review[]>;
}

Build your components to render independently based on what data is available:

function OrderPage({ orderId }: { orderId: string }) {
  const { order, recommendations, reviews } = useOrderPageData(orderId);

  // Critical: order must load or the page makes no sense
  if (order.status === "loading") return <OrderSkeleton />;
  if (order.status === "error") return <ErrorPage message={order.error} />;

  return (
    <div>
      {/* Critical section: always rendered */}
      <OrderDetails order={order.data} />

      {/* Non-critical: degrades gracefully */}
      <section aria-label="Recommendations">
        {recommendations.status === "loaded" ? (
          <RecommendationCarousel products={recommendations.data} />
        ) : recommendations.status === "error" ? (
          <EmptyState message="Recommendations Unavailable" />
        ) : (
          <CarouselSkeleton />
        )}
      </section>

      {/* Non-critical: degrades gracefully */}
      <section aria-label="Customer reviews">
        {reviews.status === "loaded" ? (
          <ReviewList reviews={reviews.data} />
        ) : reviews.status === "error" ? (
          <EmptyState message="Reviews unavailable right now" />
        ) : (
          <ReviewSkeleton />
        )}
      </section>
    </div>
  );
}

Classifying Critical vs. Non-Critical Data

Not all data on a page is equally important. Before building any page that pulls from multiple services, classify each data source:

This classification should be a conscious decision made with your product team, not something you discover when a service goes down in production.

Pattern 3: Managing Distributed State

In a monolithic world, the server is the single source of truth. In a microservice world, truth is distributed. The user service knows the user's current address. The order service has a snapshot of the address at the time of the order. These might not match.

Stale Data and Cache Boundaries

When your frontend caches data from multiple services, you need to think about cache boundaries. Data from different services goes stale at different rates.

// Configure cache times based on how frequently the underlying data changes
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000, // Default: 30 seconds
    },
  },
});

// Product catalog: changes infrequently
function useProduct(productId: string) {
  return useQuery({
    queryKey: ["product", productId],
    queryFn: () => fetchProduct(productId),
    staleTime: 5 * 60_000, // 5 minutes: catalog updates are rare
  });
}

// Inventory levels: changes constantly
function useStockLevel(productId: string) {
  return useQuery({
    queryKey: ["stock", productId],
    queryFn: () => fetchStockLevel(productId),
    staleTime: 10_000, // 10 seconds: stock changes with every purchase
    refetchInterval: 30_000, // Poll every 30 seconds on active pages
  });
}

// User's own order: should reflect latest state
function useOrder(orderId: string) {
  return useQuery({
    queryKey: ["order", orderId],
    queryFn: () => fetchOrder(orderId),
    staleTime: 0, // Always refetch: user expects to see their latest action
  });
}

The mistake is treating all cached data the same. Product information from the catalog service can be cached for minutes. Stock levels from the inventory service need to be refreshed much more frequently. A user's own order data should always be fresh because they just performed an action and expect to see the result.

Cross-Service Invalidation

The trickiest part of distributed state is knowing when to invalidate. When a user places an order, you need to:

1. Invalidate the order list (order service)

2. Invalidate the stock level (inventory service)

3. Invalidate the user's loyalty points (user service)

// After a successful order placement, invalidate across service boundaries
async function placeOrder(cart: Cart): Promise<Order> {
  const order = await api.post("/api/orders", { items: cart.items });

  // Invalidate data from multiple services that this action affected
  queryClient.invalidateQueries({ queryKey: ["orders"] });
  queryClient.invalidateQueries({ queryKey: ["stock"] });
  queryClient.invalidateQueries({ queryKey: ["loyalty-points"] });

  // Optimistically update the cart (owned by the frontend)
  queryClient.setQueryData(["cart"], { items: [] });

  return order;
}

This is manual and error-prone. Every time a new service cares about order events, you need to remember to add an invalidation here.

For more robust alternatives, you can use server-sent events or WebSocket connections to let the backend push invalidation signals to the frontend, or adopt a pub/sub pattern within your client-side state layer where cache keys subscribe to domain events.

These approaches are beyond this article's scope, but worth exploring once your invalidation table grows past a dozen entries.

In the meantime, documenting these cross-service dependencies in a table helps:

Pattern 4: Taming Multiple API Contracts

In a microservice world, each service defines its own API contract. The user service returns firstName and lastName. The order service returns customerName as a single string. The notification service expects fullName. Same concept, three different field names.

The Adapter Layer

Create an adapter layer that translates each service's response into a consistent domain model that your components use:

// Domain models: what the frontend actually works with
interface User {
  id: string;
  fullName: string;
  email: string;
  address: Address;
}

// Adapter for the User Service
function adaptUserServiceResponse(raw: UserServiceResponse): User {
  return {
    id: raw.userId,
    fullName: `\({raw.firstName} \){raw.lastName}`,
    email: raw.emailAddress,
    address: {
      line1: raw.address.street,
      city: raw.address.city,
      postcode: raw.address.zipCode,
      country: raw.address.countryCode,
    },
  };
}

// Adapter for the Order Service (which embeds a different user shape)
function adaptOrderCustomer(raw: OrderServiceCustomer): User {
  return {
    id: raw.customerId,
    fullName: raw.customerName,
    email: raw.email,
    address: {
      line1: raw.shippingAddress.addressLine1,
      city: raw.shippingAddress.city,
      postcode: raw.shippingAddress.postalCode,
      country: raw.shippingAddress.country,
    },
  };
}

Your components only work with the User type. They never see the raw service responses. When a service changes its API, you update one adapter, not every component that displays a user's name.

Where to Put the Adapter Layer

If you have a BFF, the adapters live there. The browser never sees the raw service response. If you're calling services directly from the frontend, place the adapters in your data-fetching layer, between the HTTP call and the cache:

// The adapter runs before data enters the cache
function useUser(userId: string) {
  return useQuery({
    queryKey: ["user", userId],
    queryFn: async () => {
      const raw = await fetch(`/api/users/${userId}`).then((r) => r.json());
      return adaptUserServiceResponse(raw);
    },
  });
}

Pattern 5: Timeout Budgets for Page Assembly

When a page depends on multiple services, you need a timeout strategy. Without one, your page load time is determined by the slowest service, and in a microservice world, there's always a slow service.

A timeout budget allocates a maximum time for assembling all the data a page needs. If a non-critical service doesn't respond within its budget, you render without it.

In practice, this utility lives in a shared service layer (for example, lib/api.ts) rather than inline with each page's assembly logic. Here's the implementation:

// lib/api.ts: shared timeout utility
async function fetchWithTimeout<T>(
  url: string,
  options: RequestInit,
  timeoutMs: number
): Promise<T | null> {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const response = await fetch(url, {
      ...options,
      signal: controller.signal,
    });
    return response.json();
  } catch (error) {
    if (error instanceof DOMException && error.name === "AbortError") {
      console.warn(`Request to \({url} timed out after \){timeoutMs}ms`);
    }
    return null;
  } finally {
    clearTimeout(timeout);
  }
}

// Page assembly with tiered timeouts
async function assembleProductPage(productId: string): Promise<ProductPageData> {
  // Critical data: longer timeout, page fails without it
  const product = await fetchWithTimeout<Product>(
    `/api/products/${productId}`,
    {},
    3000 // 3 second budget for critical data
  );

  if (!product) {
    throw new Error("Product not found");
  }

  // Non-critical data: shorter timeout, page renders without it
  const [reviews, recommendations, relatedProducts] = await Promise.all([
    fetchWithTimeout<Review[]>(
      `/api/reviews?productId=${productId}`,
      {},
      1500 // 1.5 second budget
    ),
    fetchWithTimeout<Product[]>(
      `/api/recommendations?productId=${productId}`,
      {},
      1000 // 1 second budget: nice to have
    ),
    fetchWithTimeout<Product[]>(
      `/api/products/${productId}/related`,
      {},
      1000
    ),
  ]);

  return {
    product,
    reviews: reviews ?? [],
    recommendations: recommendations ?? [],
    relatedProducts: relatedProducts ?? [],
  };
}

Notice the different budgets. Critical data (the product itself) gets 3 seconds. Non-critical data (reviews, recommendations) gets 1–1.5 seconds. If recommendations are slow, you show the product without them. The user doesn't wait for a service they may not even look at.

Pattern 6: Error Boundaries Per Service

React error boundaries are especially powerful in a microservice frontend. Instead of one error boundary at the page level, place boundaries around sections that map to different backend services.

If you haven't used error boundaries before, here's a minimal implementation. Error boundaries must be class components, React doesn't support them as function components yet (see the React docs for more detail):

class ErrorBoundary extends React.Component<
  { fallback: React.ReactNode; children: React.ReactNode },
  { hasError: boolean } > {
  state = { hasError: false };

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: React.ErrorInfo) {
    console.error("ErrorBoundary caught:", error, info);
  }

  render() {
    if (this.state.hasError) return this.props.fallback;
    return this.props.children;
  }
}

With that in place, scope your boundaries to individual service sections:

function ProductPage({ productId }: { productId: string }) {
  return (
    <div>
      {/* If the product service fails, show a full-page error */}
      <ErrorBoundary fallback={<ProductErrorPage />}>
        <Suspense fallback={<ProductSkeleton />}>
          <ProductDetails productId={productId} />
        </Suspense>
      </ErrorBoundary>

      {/* If the review service fails, just hide reviews */}
      <ErrorBoundary fallback={<EmptyState message="Reviews unavailable" />}>
        <Suspense fallback={<ReviewSkeleton />}>
          <ProductReviews productId={productId} />
        </Suspense>
      </ErrorBoundary>

      {/* If recommendations fail, hide silently */}
      <ErrorBoundary fallback={null}>
        <Suspense fallback={<CarouselSkeleton />}>
          <Recommendations productId={productId} />
        </Suspense>
      </ErrorBoundary>
    </div>
  );
}

Each boundary catches errors from its own data source independently. The review service crashing doesn't affect the product details. The recommendation service timing out doesn't show an error at all – the section simply doesn't render.

This maps directly to your critical/non-critical classification. Critical services get error boundaries with visible error UI. Non-critical services get boundaries that degrade silently or show a minimal empty state.

Working With Backend Teams on Contracts

The technical patterns above solve symptoms. The root cause of most frontend pain in microservice environments is poor communication between frontend and backend teams about API contracts.

Contract Conversations to Have Early

1. What fields will the frontend actually use?

Backend services often expose their entire data model. The frontend uses three fields. If the backend team knows which fields you depend on, they can maintain those fields more carefully and deprecate the ones nobody uses.

2. What is the expected latency budget for this endpoint?

If the product page has a 2-second total budget and the recommendation service averages 1.8 seconds, you have a problem before you write any frontend code. Surface this early.

3. What happens when this service is degraded?

Ask each backend team: "If your service responds with 500 errors for an hour, what should the frontend show?" This question often reveals that nobody has thought about it, which is exactly why you need to ask.

4. How will you communicate breaking changes?

Agree on a process. Whether it is OpenAPI spec diffs in pull requests, a Slack channel for API changes, or versioned endpoints, pick something and hold each other to it.

API Contracts as Shared Artifacts

Push for machine-readable contracts. OpenAPI specs, GraphQL schemas, or Protocol Buffer definitions serve as a shared source of truth between frontend and backend teams. They enable:

• Automated type generation: Tools like openapi-typescript generate TypeScript types from OpenAPI specs. When the backend changes a field, your build fails immediately, not in production.

• Contract testing: Tools like Pact let you define the expected request/response pairs from the frontend's perspective. The backend runs these tests in their CI pipeline. If their changes break the frontend's expectations, the pipeline fails.

• Mock servers: Generated mocks from the spec let you build the frontend before the backend is ready. When the real service ships, your code already works.

// Generated types from OpenAPI spec, always in sync with the backend
import type { components } from "./generated/inventory-api";

type Product = components["schemas"]["Product"];
type StockLevel = components["schemas"]["StockLevel"];

// If the backend renames "available" to "inStock",
// this code fails at compile time, not in production
function formatStockMessage(stock: StockLevel): string {
  if (stock.available > 10) return "In Stock";
  if (stock.available > 0) return `Only ${stock.available} left`;
  return "Out of Stock";
}

Testing Against Multiple Services

Contract testing catches backend-side breaking changes, but you also need to test your frontend's behavior when services respond in unexpected ways. Mock Service Worker (MSW) lets you spin up per-service mock handlers in your test environment:

import { setupServer } from "msw/node";
import { http, HttpResponse } from "msw";

// Mock each service independently
const server = setupServer(
  http.get("/api/products/:id", () =>
    HttpResponse.json({ productId: "abc-123", name: "Widget", price: 49.99 })
  ),
  http.get("/api/reviews", () =>
    HttpResponse.json([{ rating: 5, body: "Great product" }])
  )
);

// Test: what happens when the review service is down?
test("renders product page when reviews service fails", async () => {
  server.use(
    http.get("/api/reviews", () => HttpResponse.error())
  );

  render(<ProductPage productId="abc-123" />);

  expect(await screen.findByText("Widget")).toBeInTheDocument();
  expect(await screen.findByText("Reviews unavailable")).toBeInTheDocument();
});

This lets you simulate the partial failure scenarios from Pattern 2 in your test suite. Test your adapter layer (Pattern 4) with unit tests against raw service response fixtures, and use MSW for integration tests that verify the full page assembles correctly when individual services are slow, down, or return unexpected shapes.

When to Push Back

Not every microservice problem has a frontend solution. Sometimes the right answer is to push back on the architecture.

Push back when the frontend is making more than 5 API calls for a single page. This is a signal that either the services are too granular or there is a missing aggregation layer. The fix is a BFF or a composite API, not more Promise.all calls in the browser.

Push back when two services return conflicting data about the same entity. If the user service says the user's name is "Jane" and the order service says it is "Janet," this is a data consistency problem that the frontend can't solve. It needs to be fixed at the source, either through event-driven syncing between services or by establishing one service as the authoritative source for that field.

Push back when backend teams make breaking changes without notice. If your production app breaks because a service renamed a field in a minor version bump, that's a process failure. Advocate for versioned APIs, deprecation notices, and contract testing.

You're not just a consumer of APIs. You're a stakeholder in how those APIs are designed. The earlier you participate in API design conversations, the fewer surprises you deal with in production.

Conclusion

The patterns in this article give you a structured starting point, but the underlying principle is consistent across all of them:

Key takeaways:

1. Own the aggregation layer: A BFF gives the frontend team control over response shapes and lets you handle partial failures at the server level instead of the browser.

2. Classify every data source as critical or non-critical: This single decision determines your error handling, timeout budgets, and loading strategies for every section of every page.

3. Normalize at the boundary: Adapter layers between raw service responses and your components protect you from upstream API changes and give you a consistent domain model.

4. Invest in contracts: Machine-readable API contracts, generated types, and contract testing catch breaking changes at build time instead of in production.

5. Push back when needed: Not every microservice problem has a frontend solution. If the architecture creates an unreasonable burden on the UI layer, say so early.

Microservices are a backend architecture decision, but their consequences are felt most acutely in the frontend. The patterns in this article won't make that complexity disappear, but they will give you a structured way to manage it.

There are three dominant patterns: REST over HTTP, gRPC with Protocol Buffers, and event-driven messaging through a broker. Most production systems use a mix of all three. The skill is knowing which pattern fits which interaction.

In this article, you'll learn the core mechanics of each communication style, the real trade-offs between them across five dimensions (latency, coupling, schema evolution, debugging, and operational complexity), and a decision framework for choosing the right pattern for each service interaction.

Prerequisites

To get the most out of this article, you should be familiar with:

• Basic HTTP concepts (request/response, status codes, headers)

• Working with APIs in any backend language (the examples use TypeScript and Node.js)

• General understanding of microservices architecture

• Familiarity with JSON as a data interchange format

Table of Contents

• The Three Patterns at a Glance

• REST: The Default Choice

• gRPC: The Performance Choice

• Event-Driven Messaging: The Decoupling Choice

• The Five Trade-Off Dimensions

• The Decision Framework

• Hybrid Architectures: Using All Three

• Schema Governance at Scale

• Conclusion

The Three Patterns at a Glance

Before diving deep, here's the landscape:

Each has strengths, and none is universally better. The rest of this article explores why.

REST: The Default Choice

REST over HTTP is the most widely understood communication pattern. Services expose resources at URL endpoints, and clients interact through standard HTTP methods.

// Order service calls the inventory service
async function checkInventory(productId: string): Promise<InventoryStatus> {
  const response = await fetch(
    `https://inventory-service/api/v1/products/${productId}/stock`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${getServiceToken()}`,
      },
    }
  );

  if (!response.ok) {
    throw new HttpError(response.status, await response.text());
  }

  return response.json();
}

Where REST Excels

Every language, framework, and platform speaks HTTP. Your frontend, your mobile app, your partner integrations, and your internal services can all use the same protocol.

The tooling is also mature: load balancers, API gateways, caching proxies, and debugging tools all understand HTTP natively.

It's also relatively simple. A new developer can read a REST call and understand what it does. The URL describes the resource. The HTTP method describes the action. The status code describes the outcome. There's no schema compilation step, no code generation, and no special client library required.

Beyond this, HTTP has built-in caching semantics. A GET /products/123 response with a Cache-Control: max-age=60 header can be cached by every proxy between the caller and the server. gRPC and event-driven patterns have no equivalent built-in mechanism.

// REST response with cache headers
app.get("/api/v1/products/:id", async (req, res) => {
  const product = await getProduct(req.params.id);

  res.set("Cache-Control", "public, max-age=60");
  res.set("ETag", computeETag(product));

  res.json(product);
});

Where REST Falls Short

REST's resource-oriented model often requires multiple round-trips to assemble a response. Fetching an order with its items, customer details, and shipping status might mean three separate HTTP calls. Each call adds network latency, TCP handshake overhead, and serialization cost.

// Three sequential calls to build one view
async function getOrderDetails(orderId: string): Promise<OrderDetails> {
  const order = await fetch(`/api/orders/${orderId}`).then((r) => r.json());
  const customer = await fetch(`/api/customers/${order.customerId}`).then((r) => r.json());
  const shipment = await fetch(`/api/shipments/${order.shipmentId}`).then((r) => r.json());

  return { order, customer, shipment };
}

You can mitigate this with composite endpoints or GraphQL, but that adds complexity. gRPC handles this more naturally with message composition.

The serialization overhead is also an issue. JSON is human-readable but expensive to parse. For high-throughput internal communication where nobody reads the payloads, you are paying a tax in CPU and bandwidth for readability you do not need.

Finally, there's no streaming. Standard REST is request-response. If you need the server to push updates to the client (real-time order tracking, live metrics), REST requires workarounds like polling, Server-Sent Events, or WebSockets. None of these are part of the REST model itself.

gRPC: The Performance Choice

gRPC is a Remote Procedure Call framework built on HTTP/2 and Protocol Buffers. Instead of URLs and JSON, you define services and messages in .proto files, and the framework generates strongly-typed client and server code.

Defining the Contract

// inventory.proto
syntax = "proto3";

package inventory;

service InventoryService {
  // Unary: single request, single response
  rpc CheckStock(StockRequest) returns (StockResponse);

  // Server streaming: single request, stream of responses
  rpc WatchStockLevels(WatchRequest) returns (stream StockUpdate);

  // Client streaming: stream of requests, single response
  rpc BulkUpdateStock(stream StockAdjustment) returns (BulkUpdateResult);
}

message StockRequest {
  string product_id = 1;
  string warehouse_id = 2;
}

message StockResponse {
  string product_id = 1;
  int32 available = 2;
  int32 reserved = 3;
  google.protobuf.Timestamp last_updated = 4;
}

message StockUpdate {
  string product_id = 1;
  int32 available = 2;
  string warehouse_id = 3;
}

After running protoc (the Protocol Buffer compiler), you get generated client and server stubs in your target language. The TypeScript client looks like this:

import { InventoryServiceClient } from "./generated/inventory";
import { credentials } from "@grpc/grpc-js";

const client = new InventoryServiceClient(
  "inventory-service:50051",
  credentials.createInsecure()
);

async function checkStock(productId: string): Promise<StockResponse> {
  return new Promise((resolve, reject) => {
    client.checkStock(
      { productId, warehouseId: "warehouse-eu-1" },
      (error, response) => {
        if (error) reject(error);
        else resolve(response);
      }
    );
  });
}

Where gRPC Excels

Protocol Buffers serialize to a compact binary format. A message that is 1 KB as JSON might be 300 bytes as Protobuf. Combined with HTTP/2 multiplexing (multiple requests over a single TCP connection), gRPC delivers significantly lower latency and higher throughput than REST for internal service calls. And we all know performance is important.

The exact improvement depends on payload size, network topology, and server implementation. In benchmarks, the difference ranges from marginal (tiny payloads on fast networks) to an order of magnitude (large payloads, high concurrency).

The takeaway: gRPC's binary serialization and HTTP/2 multiplexing give it a structural advantage for internal traffic, but you should measure in your own environment before making latency claims.

Also, gRPC natively supports four communication patterns: unary (request-response), server streaming, client streaming, and bidirectional streaming. This makes it a natural fit for real-time use cases like live stock updates, log tailing, or progress reporting.

// Server streaming: watch inventory changes in real time
function watchStockLevels(warehouseId: string): void {
  const stream = client.watchStockLevels({ warehouseId });

  stream.on("data", (update: StockUpdate) => {
    console.log(`Product \({update.productId}: \){update.available} available`);
  });

  stream.on("error", (error) => {
    console.error("Stream error:", error.message);
    // Reconnect logic here
  });

  stream.on("end", () => {
    console.log("Stream ended");
  });
}

Finally, it has strong typing across services. The .proto file is the single source of truth. Both the client and server are generated from it. If the inventory service changes the StockResponse message, the order service's build fails until it regenerates its client. You catch breaking changes at compile time, not at 3 AM.

Where gRPC Falls Short

The first key issue is browser support. Browsers can't make native gRPC calls because the browser's fetch API doesn't expose the HTTP/2 framing that gRPC requires (for example, trailers for status codes and fine-grained control over bidirectional streams).

You need gRPC-Web, which uses a proxy like Envoy to translate between the browser-compatible subset of gRPC and the full protocol. Alternatively, you can place a REST or GraphQL gateway in front of your gRPC services.

Either way, gRPC isn't a viable choice for any endpoint that a browser calls directly — which is why the decision framework in this article defaults to REST for public-facing APIs.

It's also difficult to debug. You can't curl a gRPC endpoint. The binary payloads aren't human-readable. Tools like grpcurl and Postman's gRPC support help, but the debugging experience is worse than inspecting a JSON response in a browser's network tab.

# Debugging a REST endpoint
curl -s https://inventory-service/api/v1/products/abc-123/stock | jq

# Debugging a gRPC endpoint (requires grpcurl)
grpcurl -plaintext -d '{"product_id": "abc-123"}' \
  inventory-service:50051 inventory.InventoryService/CheckStock

Finally, operational overhead is an issue. You need to manage .proto files, run code generation in your build pipeline, version your proto definitions, and ensure all consumers regenerate when schemas change.

For a team with two services, this is manageable. For twenty services, you need a proto registry and a governance process.

Event-Driven Messaging: The Decoupling Choice

Event-driven communication flips the model. Instead of service A calling service B directly, service A publishes an event to a broker (Kafka, RabbitMQ, Amazon SNS/SQS, or similar), and service B consumes it asynchronously.

// Order service publishes an event after confirming an order
import { Kafka } from "kafkajs";

const kafka = new Kafka({ brokers: ["kafka:9092"] });
const producer = kafka.producer();

async function publishOrderConfirmed(order: Order): Promise<void> {
  await producer.send({
    topic: "order.confirmed",
    messages: [
      {
        key: order.id,
        value: JSON.stringify({
          eventType: "order.confirmed",
          eventId: crypto.randomUUID(),
          timestamp: new Date().toISOString(),
          data: {
            orderId: order.id,
            customerId: order.customerId,
            items: order.items.map((item) => ({
              productId: item.productId,
              quantity: item.quantity,
            })),
            total: order.total,
          },
        }),
      },
    ],
  });
}

// Inventory service consumes the event independently
const consumer = kafka.consumer({ groupId: "inventory-service" });

async function startInventoryConsumer(): Promise<void> {
  await consumer.subscribe({ topic: "order.confirmed" });

  await consumer.run({
    eachMessage: async ({ message }) => {
      const event = JSON.parse(message.value.toString());

      for (const item of event.data.items) {
        await decrementStock(item.productId, item.quantity);
      }

      logger.info("Inventory updated for order", {
        orderId: event.data.orderId,
      });
    },
  });
}

Where Event-Driven Excels

First, it employs temporal decoupling. The producer doesn't wait for the consumer. The order service publishes "order confirmed" and moves on. If the inventory service is down, the event sits in the broker until it recovers. No timeout, no retry logic in the producer, no cascading failure.

One event can also trigger multiple independent reactions. When an order is confirmed, the inventory service decrements stock, the notification service sends a confirmation email, the analytics service records a conversion, and the shipping service starts fulfillment. The order service doesn't know or care about any of these consumers.

order.confirmed event
  ├── inventory-service    → Decrement stock
  ├── notification-service → Send confirmation email
  ├── analytics-service    → Record conversion
  └── shipping-service     → Create shipment

Adding a new consumer requires zero changes to the producer. This is the lowest coupling you can achieve between services.

There's also a natural audit trail. If your broker retains events (Kafka does this by default), you have a complete history of everything that happened. You can replay events to rebuild state, debug issues by examining the exact sequence of events, or spin up a new service that processes historical events to backfill its data.

Where Event-Driven Falls Short

After the order service publishes "order confirmed," there's a window where the inventory service hasn't yet processed the event. During that window, a concurrent request might read stale stock levels. If your use case requires "read your own writes" consistency, event-driven communication alone is not enough.

// The problem: order confirmed, but stock not yet decremented
async function handleCheckout(cart: Cart): Promise<Order> {
  const order = await createOrder(cart);
  await publishOrderConfirmed(order);

  // If another request checks stock RIGHT NOW,
  // it sees the old (pre-decrement) value.
  // The inventory consumer hasn't processed the event yet.
  return order;
}

Debugging also gets more complex. When something goes wrong in a synchronous call chain, you get a stack trace. When something goes wrong in an event-driven flow, you get a message in a dead-letter queue and a question: which producer sent this? When? What was the system state at that time? Distributed tracing helps, but correlating events across services is fundamentally harder than following a request through a call stack.

You can also have issues with ordering guarantees. Most brokers guarantee ordering within a partition (Kafka) or a queue, but not globally. If the order service publishes "order confirmed" and then "order cancelled," the inventory service might process the cancellation first if the events land on different partitions.

// Use a consistent partition key to guarantee ordering per entity
await producer.send({
  topic: "order.events",
  messages: [
    {
      // All events for the same order go to the same partition
      key: order.id,
      value: JSON.stringify(event),
    },
  ],
});

Keying messages by entity ID (order ID, customer ID) ensures events for the same entity are processed in order. Events for different entities can be processed in parallel.

Finally, your operations get more complex. Running a message broker isn't free. Kafka requires ZooKeeper (or KRaft), topic management, partition rebalancing, consumer group coordination, and monitoring for consumer lag. Managed services like Amazon MSK, Confluent Cloud, or Amazon SQS reduce this burden but add cost.

Handling Broker Failures

What happens when the broker is unavailable? If your service writes to the database and then publishes an event, a broker outage means the event is lost even though the database write succeeded.

These patterns help:

1. The Outbox Pattern

Instead of publishing directly to the broker, write the event to an "outbox" table in the same database transaction as your business data. A separate process (a poller or a change-data-capture connector like Debezium) reads the outbox table and publishes to the broker.

// Outbox pattern: write event to the database, not the broker
// db injected via dependency injection
async function confirmOrder(order: Order, db: Database): Promise<void> {
  await db.transaction(async (tx) => {
    // Business write and event write in the same transaction
    await tx.update("orders", { id: order.id, status: "confirmed" });
    await tx.insert("outbox", {
      id: crypto.randomUUID(),
      topic: "order.confirmed",
      key: order.id,
      payload: JSON.stringify({
        orderId: order.id,
        customerId: order.customerId,
        items: order.items,
        total: order.total,
      }),
      created_at: new Date(),
    });
  });
  // A separate relay process picks up outbox rows and publishes to Kafka
}

Because the event and the business data are written atomically, you never lose an event due to a broker outage. The relay process retries until the broker is back.

2. At-least-once delivery

Most brokers guarantee at-least-once delivery, meaning consumers may see the same event more than once (for example, after a rebalance or a retry). Your consumers must be idempotent: processing the same event twice should produce the same result as processing it once.

// Idempotent consumer: use the eventId to deduplicate
async function handleOrderConfirmed(event: EventEnvelope<OrderData>): Promise<void> {
  const alreadyProcessed = await db.query(
    "SELECT 1 FROM processed_events WHERE event_id = $1",
    [event.eventId]
  );

  if (alreadyProcessed.rows.length > 0) {
    logger.info("Duplicate event, skipping", { eventId: event.eventId });
    return;
  }

  await db.transaction(async (tx) => {
    await decrementStock(tx, event.data.items);
    await tx.insert("processed_events", {
      event_id: event.eventId,
      processed_at: new Date(),
    });
  });
}

The combination of the outbox pattern (producer side) and idempotent consumers (consumer side) gives you reliable event-driven communication even when the broker has intermittent failures.

The Five Trade-Off Dimensions

Choosing a communication pattern isn't about which is "best." It's about which trade-offs you can accept for each specific interaction. Here are the five dimensions that matter most.

1. Latency

Exact numbers depend on payload size, network hops, and infrastructure. The structural ordering is consistent: gRPC is fastest for synchronous calls, REST is close behind, and event-driven messaging trades latency for decoupling.

If the caller needs an immediate response (user-facing checkout, real-time search), use gRPC or REST. If the caller doesn't need the result right now (send email, update analytics), use events.

2. Coupling

Coupling has two dimensions: temporal (does the caller wait for the receiver?) and schema (do they share a contract?).

REST's loose typing is a double-edged sword. You can add fields to a JSON response without breaking consumers (additive changes are safe). But you can also accidentally remove a field, and the consumer fails at runtime instead of compile time.

gRPC's strict typing catches breaking changes at build time, but it means every schema change requires regenerating clients. For two services, this is trivial. For twenty services consuming the same proto, you need a coordination process.

Event-driven messaging decouples in time but still couples on the event schema. If the order.confirmed event changes its structure, every consumer must handle both the old and new format during the transition.

3. Schema Evolution

Schema evolution is how you change the contract between services without breaking existing consumers. This is where the three patterns diverge most sharply.

REST (JSON):

// Version 1: price as a number
{ "productId": "abc-123", "price": 49.99 }

// Version 2: price as an object (breaking change)
{ "productId": "abc-123", "price": { "amount": 49.99, "currency": "USD" } }

JSON has no built-in versioning. You manage it through one of three strategies:

Additive changes (new fields) are safe with any strategy. Structural changes (renaming fields, changing types) require explicit versioning — URL or header — so consumers can migrate at their own pace.

gRPC (Protocol Buffers):

// Protocol Buffers have built-in evolution rules
message StockResponse {
  string product_id = 1;
  int32 available = 2;
  int32 reserved = 3;
  // Field 4 was removed (never reuse field numbers)
  string warehouse_id = 5;       // New field: old clients ignore it
  optional string region = 6;    // Optional: old clients don't send it
}

Protocol Buffers handle evolution well by design. You can add new fields (old clients ignore them), deprecate fields (stop writing them, keep the number reserved), and use optional for fields that may not be present.

You can't rename fields, change field types, or reuse field numbers. These rules are enforced by the tooling.

Event-driven (Avro/JSON Schema):

For events, schema registries like Confluent Schema Registry enforce compatibility rules:

// Register a schema with backward compatibility
// New consumers can read old events, old consumers can read new events
const schema = {
  type: "record",
  name: "OrderConfirmed",
  fields: [
    { name: "orderId", type: "string" },
    { name: "customerId", type: "string" },
    { name: "total", type: "double" },
    // New field with default: backward compatible
    { name: "currency", type: "string", default: "USD" },
  ],
};

With a schema registry, producers can't publish events that violate the compatibility contract. This is the strongest governance model: the registry rejects incompatible schemas before they reach consumers.

4. Debugging and Observability

For event-driven systems, correlation IDs are essential:

// Always include a correlation ID in events
interface EventEnvelope<T> {
  eventId: string;
  eventType: string;
  correlationId: string; // Links related events across services
  causationId: string;   // The event that caused this one
  timestamp: string;
  source: string;
  data: T;
}

async function publishEvent<T extends { entityId: string }>(
  topic: string,
  type: string,
  data: T,
  correlationId: string,
  causationId?: string
): Promise<void> {
  const event: EventEnvelope<T> = {
    eventId: crypto.randomUUID(),
    eventType: type,
    correlationId,
    causationId: causationId ?? correlationId,
    timestamp: new Date().toISOString(),
    source: SERVICE_NAME,
    data,
  };

  await producer.send({
    topic,
    messages: [{ key: data.entityId, value: JSON.stringify(event) }],
  });
}

When investigating an issue, you search for the correlation ID across all services and reconstruct the full event chain. Without it, you're searching for a needle in a haystack.

5. Operational Complexity

REST has the lowest operational overhead. Every team knows how to run an HTTP server.

gRPC adds a build-time dependency (proto compilation) and requires teams to learn new tooling.

Event-driven adds a runtime dependency (the broker) that must be highly available because if the broker goes down, inter-service communication stops.

The Decision Framework

Use this framework when deciding how a specific pair of services should communicate. The answer is rarely one pattern for your entire system.

Does the caller need an immediate response?
├── Yes → Is this a public-facing or browser-accessible API?
│         ├── Yes → REST
│         └── No  → Is throughput or latency critical?
│                   ├── Yes → gRPC
│                   └── No  → REST (simpler, good enough)
└── No  → Can the caller tolerate eventual consistency?
          ├── No  → Use synchronous call (REST or gRPC) with async follow-up
          └── Yes → Does the event need to trigger multiple consumers?
                    ├── Yes → Event-driven messaging
                    └── No  → Is ordering critical?
                              ├── Yes → Event-driven with partition key
                              └── No  → Event-driven (or simple queue like SQS)

Some concrete examples:

Hybrid Architectures: Using All Three

Most production systems use a combination. Here's a pattern that works well:

┌──────────┐    REST     ┌──────────────┐    gRPC    ┌──────────────┐
│ Browser  │────────────▶│  API Gateway │───────────▶│ Order Service│
└──────────┘             └──────────────┘            └──────┬───────┘
                                                           │
                                                    publishes event
                                                           │
                                                           ▼
                                                    ┌─────────────┐
                                                    │    Kafka     │
                                                    └──────┬──────┘
                                          ┌────────────────┼────────────────┐
                                          ▼                ▼                ▼
                                   ┌────────────┐  ┌────────────┐  ┌────────────┐
                                   │ Inventory  │  │ Notification│  │ Analytics  │
                                   │  Service   │  │  Service    │  │  Service   │
                                   └────────────┘  └────────────┘  └────────────┘

• REST at the edge: the browser talks to the API gateway using standard HTTP. Cacheable, debuggable, universally supported.

• gRPC between the gateway and internal services: low latency, strong typing, efficient serialization.

• Event-driven for downstream reactions: the order service publishes an event, and multiple consumers react independently.

The Anti-Synchronous Trap

A common mistake is using synchronous calls (REST or gRPC) where events are a better fit. The symptom: a service that makes five synchronous calls during a single request, waiting for each to complete before responding to the caller.

// Anti-pattern: synchronous fan-out
async function confirmOrder(order: Order): Promise<void> {
  await inventoryService.decrementStock(order.items);    // 50ms
  await paymentService.capturePayment(order.paymentId);  // 200ms
  await notificationService.sendConfirmation(order);     // 100ms
  await analyticsService.recordConversion(order);        // 80ms
  await shippingService.createShipment(order);           // 150ms
  // Total: 580ms, and if any one fails, the order fails
}

Only the first two calls (inventory and payment) are critical to confirming the order. The rest are reactions that can happen asynchronously:

// Better: synchronous for critical path, events for reactions
async function confirmOrder(order: Order): Promise<void> {
  // Critical path: must succeed for the order to be valid
  await inventoryService.decrementStock(order.items);
  await paymentService.capturePayment(order.paymentId);

  // Non-critical: publish event, let consumers handle the rest
  await publishOrderConfirmed(order);
  // Total: 250ms, and notification/analytics/shipping failures
  // don't block the checkout
}

This is the same tiered approach from my designing resilient APIs article. Critical operations are synchronous. Non-critical reactions are event-driven. The caller responds faster, and downstream failures do not cascade.

Schema Governance at Scale

As your service count grows, schema management becomes a first-class concern. Here's a practical approach for each pattern.

REST: OpenAPI as the Contract

# openapi/inventory-service.yaml
openapi: "3.1.0"
info:
  title: Inventory Service
  version: "1.2.0"
paths:
  /api/v1/products/{productId}/stock:
    get:
      operationId: getStock
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Stock level for the product
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StockResponse"
components:
  schemas:
    StockResponse:
      type: object
      required: [productId, available, reserved]
      properties:
        productId:
          type: string
        available:
          type: integer
        reserved:
          type: integer

Generate client SDKs from the OpenAPI spec using tools like openapi-typescript or openapi-generator. This gives you type safety without the build-time coupling of gRPC.

gRPC: Proto Registry

Store .proto files in a shared repository or a dedicated proto registry (Buf Schema Registry is a good option). Use Buf's breaking change detection in CI:

# Detects breaking changes before they merge
buf breaking --against ".git#branch=main"

This command requires a buf.yaml configuration file at the root of your proto directory. The file defines your module name and any lint or breaking change rules. See the Buf documentation for setup details.

This fails your pull request if you rename a field, change a type, or reuse a field number. Non-breaking changes (adding fields, adding services) pass through.

Events: Schema Registry with Compatibility Modes

For event-driven systems, a schema registry enforces compatibility at publish time. Confluent Schema Registry supports four modes:

Use FULL compatibility for production topics. It ensures that any consumer, regardless of which schema version it was built against, can read any event on the topic.

Conclusion

In this article, you learned the core mechanics of REST, gRPC, and event-driven messaging, the five trade-off dimensions that matter when choosing between them (latency, coupling, schema evolution, debugging, and operational complexity), and a decision framework for matching patterns to specific service interactions.

The key takeaways:

1. REST for the edge: Browser clients, public APIs, simple CRUD. Cacheable, debuggable, universally supported.

2. gRPC for internal hot paths: High-throughput service-to-service calls where latency matters and both sides are under your control.

3. Events for reactions: When the producer shouldn't wait, when multiple consumers need the same signal, or when temporal decoupling prevents cascading failures.

4. Use all three: Most production systems combine patterns. REST at the boundary, gRPC internally, events for async workflows.

5. Schema governance scales the system: OpenAPI for REST, proto registries for gRPC, schema registries for events. Without governance, schema changes become the primary source of production incidents.

The right communication pattern isn't a global decision. It's a per-interaction decision, made deliberately, based on which trade-offs you can accept for that specific data flow.

Then the project grows. Features multiply. A second app appears, maybe a separate admin dashboard, a marketing site, or a mobile-facing API. Suddenly, you're copying components between repos, duplicating business logic, arguing over where auth utilities belong, and asking yourself: where did it all go wrong?

The answer is almost always architecture, or rather, the absence of one. Not the kind that lives in a Notion doc but the kind baked into your folder structure, your module boundaries, and the tools you reach for at the start of a project (not after it's already broken).

This article is a practical guide to building layered, reusable architecture in Next.js.

You'll learn about the App Router's colocation model, building scalable folder structures around features, sharing logic across apps with Turborepo, drawing clean data-fetching boundaries using Server Components, designing a testing strategy that matches your layer structure, and wiring up a CI/CD pipeline that only builds and tests what actually changed.

By the end, you'll have a blueprint you can actually use, not just admire.

Table of Contents

• The Core Problem: Coupling Without Intention

• Layer 1: The App Router and Colocation

• Layer 2: Feature-Based Folder Structure

• Layer 3: Monorepo with Turborepo (Sharing Logic Across Apps)

• Layer 4: Server Components and Data-Fetching Boundaries

• Layer 5: Testing Strategy for a Layered Codebase

• Layer 6: CI/CD with Turborepo

• Putting It All Together: The Full Blueprint

• Common Pitfalls and How to Avoid Them

• Final Thoughts

The Core Problem: Coupling Without Intention

When a component reaches directly into a global store, when a page imports a utility from three directories away, when your auth logic is spread across /lib, /helpers, and /utils with no clear owner, every file knows too much about every other file.

The app still runs. But now changing one thing breaks three others, onboarding takes a week, and adding a second app means copying half the first one.

Layered architecture solves this by giving everything a place, and making those places mean something.

Layer 1: The App Router and Colocation

Next.js 13+ introduced the App Router with a file-system-based routing model that does something subtly powerful: it lets you colocate everything related to a route inside that route's folder.

Before the App Router, pages lived in /pages, components lived in /components, and data fetching was scattered. The App Router flips this. A route segment can now own its layout, its loading and error states, its server actions, and even its local components, all in one place.

What Colocation Actually Means

Consider a /dashboard route. In the App Router model, its folder might look like this:

app/
  dashboard/
    page.tsx              # The route entry point
    layout.tsx            # Dashboard-specific shell/navigation
    loading.tsx           # Streaming loading state
    error.tsx             # Error boundary
    components/
      StatsCard.tsx       # Used only within dashboard
      ActivityFeed.tsx
    lib/
      queries.ts          # Data fetching for this route only
      formatters.ts       # Dashboard-specific transforms

The key insight: StatsCard.tsx and queries.ts don't belong to your whole application, they belong to /dashboard. When you delete or refactor the dashboard, you delete or refactor one folder. Nothing else breaks.

This is colocation. It's not a new idea, but the App Router makes it idiomatic in Next.js for the first time.

The Rule of Proximity

A good heuristic: a file should live as close as possible to where it's used. If it's used in one route, it lives in that route's folder. If it's used by two routes under the same parent segment, it moves up one level. If it's used across the entire app, it belongs in a shared layer (more on that shortly).

app/
  (marketing)/          # Route group , no URL segment
    layout.tsx          # Shared layout for marketing pages
    page.tsx
    about/
      page.tsx
  (dashboard)/
    layout.tsx          # Different shell for app routes
    dashboard/
      page.tsx
    settings/
      page.tsx

Route groups (folders wrapped in parentheses) let you share layouts across segments without polluting the URL. This is a clean way to separate concerns, marketing pages and app pages can have entirely different shells without any URL trickery.

Layer 2: Feature-Based Folder Structure

Colocation handles the route level. But large applications have cross-cutting concerns – things that don't belong to any single route but aren't generic utilities either.

This is where most projects fall apart: the /components folder becomes a dumping ground, /lib becomes a junk drawer, and nobody agrees on where useAuth should live.

Feature-based folder structure brings order to this chaos.

Organising by Domain, Not by File Type

Instead of grouping files by what they are (components, hooks, utils), group them by what they do.

src/
  features/
    auth/
      components/
        LoginForm.tsx
        AuthGuard.tsx
      hooks/
        useAuth.ts
        useSession.ts
      lib/
        tokenStorage.ts
        validators.ts
      types.ts
      index.ts            # Public API , only export what others need

    billing/
      components/
        PricingTable.tsx
        SubscriptionBadge.tsx
      hooks/
        useSubscription.ts
      lib/
        stripe.ts
      types.ts
      index.ts

    notifications/
      ...

Each feature folder is a self-contained unit. It has its own components, hooks, utilities, and types. Crucially, it has a barrel file (index.ts) that defines its public API, the things other parts of the app are allowed to import.

Enforcing Boundaries with Barrel Exports

The index.ts is not optional. It's the mechanism that prevents features from becoming entangled.

// features/auth/index.ts
export { LoginForm } from './components/LoginForm';
export { AuthGuard } from './components/AuthGuard';
export { useAuth } from './hooks/useAuth';
export type { AuthUser, AuthState } from './types';

// NOT exported, internal implementation detail:
// tokenStorage.ts, validators.ts

Now, the rest of your app imports from @/features/auth, never from @/features/auth/lib/tokenStorage. If you refactor how tokens are stored internally, nothing outside the feature breaks. This is the essence of encapsulation, not just as a theoretical principle, but as a structural one enforced by your folder layout.

Shared vs. Feature

Not everything belongs in a feature. Truly generic utilities: a cn() classname helper, a date formatter, or a base HTTP client, for example, belong in a shared layer:

src/
  shared/
    components/
      Button.tsx
      Modal.tsx
      Spinner.tsx
    hooks/
      useDebounce.ts
      useMediaQuery.ts
    lib/
      http.ts
      dates.ts
    ui/              # shadcn/ui or design system components

The rule: shared/ has zero knowledge of any feature. Features can import from shared/. shared/ never imports from a feature.

Layer 3: Monorepo with Turborepo (Sharing Logic Across Apps)

Single-repo architecture gets you far, but most teams eventually end up with multiple apps: a customer-facing Next.js app, an admin panel, a separate marketing site, maybe a set of API services.

The question becomes: how do you share code between them without copy-pasting?

The answer is a monorepo with shared packages, and Turborepo is currently the best tool for Next.js teams doing this.

The Monorepo Shape

A well-structured Turborepo looks like this:

my-platform/
  apps/
    web/              # Customer-facing Next.js app
    admin/            # Internal admin panel (also Next.js)
    marketing/        # Marketing site
  packages/
    ui/               # Shared component library
    config/           # Shared ESLint, TypeScript, Tailwind configs
    auth/             # Shared auth utilities and types
    database/         # Prisma client + query helpers
    utils/            # Generic utilities
  turbo.json
  package.json        # Root workspace config

apps/ contains deployable applications. packages/ contains shared code that apps depend on. Neither app imports directly from the other, all sharing flows through packages/.

Setting Up a Shared Package

A package is just a folder with a package.json that other workspace members can depend on.

// packages/ui/package.json
{
  "name": "@my-platform/ui",
  "version": "0.0.1",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts"
  }
}

// packages/ui/src/index.ts
export { Button } from './Button';
export { Modal } from './Modal';
export { Card } from './Card';

Now your apps consume it like any npm package:

// apps/web/package.json
{
  "dependencies": {
    "@my-platform/ui": "*"
  }
}

// apps/web/app/dashboard/page.tsx
import { Card, Button } from '@my-platform/ui';

Change Card once in packages/ui, and every app that uses it gets the update, no copy-pasting, no drift.

Important: Because the package points directly at TypeScript source files (not compiled output), each consuming Next.js app must tell the bundler to transpile it. Add this to your Next.js config:

// apps/web/next.config.ts
const config: import('next').NextConfig = {
  transpilePackages: ['@my-platform/ui', '@my-platform/auth', '@my-platform/utils'],
};

export default config;

Without this, the build fails with syntax errors, Next.js doesn't transpile packages from node_modules or workspace dependencies by default. The alternative is compiling each package to dist/ and pointing exports there, but that adds a build step to every package and slows down the dev feedback loop. For internal monorepo packages, transpilePackages is the simpler tradeoff.

The turbo.json Pipeline

Turborepo's real power is its build pipeline. It understands the dependency graph between your packages and apps, caches build outputs, and runs tasks in parallel where possible.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

The ^build syntax means: before building this package, build all its dependencies first. So if apps/web depends on packages/ui, Turborepo ensures packages/ui is built before apps/web starts. Remote caching means if packages/ui hasn't changed, Turborepo skips rebuilding it entirely, even across CI runs and team members' machines.

What Goes in a Package vs. an App

A useful litmus test:

If two apps need the same logic, it goes in a package. If only one app needs it, it stays in that app, even if you think the other app might need it someday. Premature abstraction is just as damaging as none at all.

Layer 4: Server Components and Data-Fetching Boundaries

The App Router's Server Components model is arguably the most architecturally significant change Next.js has ever shipped, and also the most misunderstood.

Most developers approach it as a performance optimisation. It is that, but it's more importantly an architectural boundary. Understanding where that boundary sits, and designing around it deliberately, is what separates scalable App Router codebases from ones that fight the framework.

The Mental Model: Two Worlds

Every component in the App Router lives in one of two worlds:

Server Components (default) run exclusively on the server. They can await data directly, access databases, read environment variables, and reduce the JavaScript sent to the browser. They can't use browser APIs, useState, useEffect, or event handlers.

Client Components ('use client') run in the browser (and also during SSR/hydration). They can use hooks, handle events, and access browser APIs. They can't directly await server-side resources.

The directive 'use client' doesn't mean "this runs only in the browser" , it means "this is the boundary where the server-to-client handoff begins." Any module imported by a Client Component becomes part of the client bundle.

But Server Components passed as props (typically via children) retain their server-only nature, they're rendered on the server and streamed as HTML, not included in the client bundle. This distinction is what makes the composition pattern below work.

Designing the Boundary

The goal is to push the 'use client' boundary as far down the tree as possible, keeping data fetching and heavy logic on the server, and reserving Client Components for genuinely interactive leaves.

A pattern that works well in practice:

// app/dashboard/page.tsx , Server Component
// Fetches data, no 'use client' directive needed

import { getMetrics } from '@/features/analytics/lib/queries';
import { MetricsDashboard } from './components/MetricsDashboard';

export default async function DashboardPage() {
  const metrics = await getMetrics();   // Direct DB call , no API round-trip
  return <MetricsDashboard data={metrics} />;
}

// app/dashboard/components/MetricsDashboard.tsx , Server Component
// Composes layout, delegates interactivity to leaves

import { StatsCard } from './StatsCard';
import { ChartSection } from './ChartSection';

export function MetricsDashboard({ data }) {
  return (
    <div className="grid gap-6">
      <StatsCard value={data.revenue} label="Revenue" />
      <ChartSection points={data.trend} />
    </div>
  );
}

// app/dashboard/components/ChartSection.tsx , Client Component
// Interactive chart needs browser APIs

'use client';

import { useState } from 'react';
import { LineChart, RangeSelector } from '@my-platform/ui';

export function ChartSection({ points }) {
  const [range, setRange] = useState('7d');
  return (
    <div>
      <RangeSelector value={range} onChange={setRange} />
      <LineChart data={points.filter(/* range logic */)} />
    </div>
  );
}

The data flows from server to client in one direction. The server does the expensive work (database query), passes serialisable data down as props, and the client receives a ready-to-render dataset – no loading spinners, no client-side fetch waterfalls.

Colocating Data Fetching with Routes

A powerful pattern enabled by Server Components is colocating data fetching directly with the route that needs it, eliminating the need for global state management in many cases.

app/
  orders/
    page.tsx              # await getOrders() , renders list
    [id]/
      page.tsx            # await getOrder(id) , renders single order
      loading.tsx         # Streaming skeleton while awaiting
      components/
        OrderTimeline.tsx  # Server Component , renders timeline data
        CancelButton.tsx  # 'use client' , needs click handler

Each page fetches its own data, scoped to what it needs. Nested layouts and pages can fetch concurrently when using Promise.all or parallel route segments. And loading.tsx gives you streaming suspense boundaries without writing a single <Suspense> wrapper manually.

When to Use a Fetch Layer vs. Direct Queries

As apps scale, you'll want a consistent approach to data access. A practical pattern:

// packages/database/src/queries/orders.ts
// Runs on the server , can be imported in any Server Component

import { db } from '../client';

export async function getOrdersByUser(userId: string) {
  return db.order.findMany({
    where: { userId },
    include: { items: true },
    orderBy: { createdAt: 'desc' },
  });
}

// packages/database/src/index.ts
export { getOrdersByUser } from './queries/orders';
export { getProductById } from './queries/products';
// ...

Your Server Components import from @my-platform/database. Your Client Components never touch this package: they call API routes or Server Actions if they need to mutate data. This keeps the boundary clean and auditable.

Server Actions for Mutations

Data fetching flows through Server Components, but mutations need their own boundary. Server Actions ('use server') let you define server-side functions that Client Components can call directly – no API route boilerplate needed.

// app/orders/[id]/actions.ts
'use server';

import { db } from '@my-platform/database';
import { revalidatePath } from 'next/cache';

export async function cancelOrder(orderId: string) {
  await db.order.update({
    where: { id: orderId },
    data: { status: 'cancelled', cancelledAt: new Date() },
  });

  revalidatePath(`/orders/${orderId}`);
}

// app/orders/[id]/components/CancelButton.tsx
'use client';

import { cancelOrder } from '../actions';
import { useTransition } from 'react';

export function CancelButton({ orderId }: { orderId: string }) {
  const [isPending, startTransition] = useTransition();

  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => cancelOrder(orderId))}
    >
      {isPending ? 'Cancelling...' : 'Cancel Order'}
    </button>
  );
}

The architectural decision:

• use Server Actions for mutations that are colocated with a specific route (cancelling an order, updating a profile).

• Use API routes for mutations that are consumed by external clients (webhooks, mobile apps, third-party integrations).

Server Actions keep mutation logic close to the UI that triggers it. API routes provide a stable contract for external consumers.

This completes the data flow picture: Server Components handle reads, Server Actions handle writes, and Client Components are the interactive surface that connects them.

Layer 5: Testing Strategy for a Layered Codebase

The testing pyramid is one of those concepts that sounds obvious in theory but falls apart in practice, usually because the codebase doesn't have clear boundaries to test against. When everything is tangled, every test becomes an integration test by accident.

The layered architecture you've built changes this: each layer has a defined surface area, so you can test each one at the right level of abstraction.

Test Each Layer at the Right Granularity

The layered architecture maps naturally onto the testing pyramid:

The goal: test shared packages exhaustively, test features thoroughly, test pages for integration correctness, and use E2E only for the flows that matter most.

Not everything needs an E2E test, and treating E2E as the default testing strategy is one of the most expensive mistakes a team can make.

Unit Testing Shared Packages

Packages in packages/ are the easiest to test. They're pure TypeScript with no framework coupling. Use Vitest:

// packages/utils/src/dates.test.ts
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { formatRelativeDate } from './dates';

describe('formatRelativeDate', () => {
  beforeEach(() => {
    // Pin the clock to avoid flaky results near midnight
    vi.useFakeTimers();
    vi.setSystemTime(new Date('2026-03-15T12:00:00Z'));
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  it('returns "today" for dates within the current day', () => {
    expect(formatRelativeDate(new Date())).toBe('today');
  });

  it('returns "yesterday" for dates on the previous day', () => {
    const yesterday = new Date('2026-03-14T15:00:00Z');
    expect(formatRelativeDate(yesterday)).toBe('yesterday');
  });
});

Keep package tests colocated with the source file. A dates.ts file has a dates.test.ts sibling. No separate __tests__ folders, those are relics of less structured codebases.

Testing Feature Modules

Features are where most of your business logic lives, so they get the most test coverage. The key rule: test the public API of the feature, not its internals.

// features/auth/hooks/useAuth.test.ts
import { renderHook, act } from '@testing-library/react';
import { useAuth } from '../hooks/useAuth';
import { createWrapper } from '@/test/utils'; // your test provider wrapper

describe('useAuth', () => {
  it('returns authenticated state when session exists', async () => {
    const { result } = renderHook(() => useAuth(), {
      wrapper: createWrapper({ session: mockSession }),
    });

    expect(result.current.isAuthenticated).toBe(true);
    expect(result.current.user.email).toBe(mockSession.user.email);
  });

  it('redirects to login when session is null', async () => {
    const { result } = renderHook(() => useAuth(), {
      wrapper: createWrapper({ session: null }),
    });

    expect(result.current.isAuthenticated).toBe(false);
  });
});

Notice that the test imports from the hook directly, not from the feature's index.ts barrel. Feature index exports are public APIs. They're tested through integration tests that consume the feature as a whole. Internal hooks and utilities are tested at the unit level. Both are valid, and the distinction is intentional.

Testing Server Components

Server Components are async functions that return JSX. Testing them directly is still an evolving story. React's test renderer doesn't natively handle async components, and calling await DashboardPage() then passing the result to render() produces subtle issues (missing context, act() warnings, or outright failures depending on your setup).

The most reliable approach today is to test the layers separately: mock the data layer to verify it's called correctly, and test the presentational component with static props.

// app/dashboard/components/MetricsDashboard.test.tsx
import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { MetricsDashboard } from './MetricsDashboard';

describe('MetricsDashboard', () => {
  it('renders revenue metric from provided data', () => {
    render(
      <MetricsDashboard data={{ revenue: 84200, trend: [] }} />
    );

    expect(screen.getByText('£84,200')).toBeInTheDocument();
  });
});

// features/analytics/lib/queries.test.ts
import { describe, it, expect } from 'vitest';
import { getMetrics } from './queries';

describe('getMetrics', () => {
  it('returns revenue and trend data', async () => {
    const metrics = await getMetrics();

    expect(metrics.revenue).toBeGreaterThan(0);
    expect(Array.isArray(metrics.trend)).toBe(true);
  });
});

The key insight: mock at the data layer boundary, not at the database or network layer. The data query has its own tests in packages/database. The presentational component has its own tests with static props. The Server Component page wires them together, and that wiring is verified by your E2E tests, which are better suited to catching integration issues across the async boundary.

End-to-End Tests with Playwright

Reserve Playwright for the flows that touch multiple layers and where a breakage would be catastrophic: authentication, checkout, and form submission with side effects. Don't use it for visual regressions or static content, as that's expensive and slow.

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test';

test('user can log in and reach dashboard', async ({ page }) => {
  await page.goto('/login');
  await page.fill('[name="email"]', 'test@example.com');
  await page.fill('[name="password"]', 'password123');
  await page.click('button[type="submit"]');

  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});

Colocate E2E tests in a top-level e2e/ folder at the monorepo root. They span apps and don't belong inside any single app's directory.

Configuring Vitest Across the Monorepo

Each package and app has its own vitest.config.ts, but they can share a base config via a shared package:

// packages/config/vitest.base.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/test/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov'],
    },
  },
});

// apps/web/vitest.config.ts
import { mergeConfig } from 'vitest/config';
import base from '@my-platform/config/vitest.base';

export default mergeConfig(base, {
  test: {
    include: ['src/**/*.test.{ts,tsx}', 'app/**/*.test.{ts,tsx}'],
  },
});

This ensures consistent test configuration across every app and package without duplication.

Layer 6: CI/CD with Turborepo

A well-designed monorepo without a smart CI pipeline is just a big repo. Turborepo's real power emerges in CI, where it can cut build and test times dramatically through caching and intelligent task scheduling.

The Core Insight: Only Run What Changed

Traditional CI pipelines run everything on every commit. In a monorepo, this means running tests for apps/admin when you only changed a utility in apps/web. Turborepo's dependency graph awareness eliminates this.

When you run turbo test, Turborepo:

1. Builds the dependency graph from your package.json files

2. Checks which packages have changed (against the last cached state)

3. Runs tests only for changed packages and their dependents

4. Caches results. If nothing changed, it restores from cache instantly.

A change to packages/ui triggers tests for packages/ui, apps/web, and apps/admin (since both depend on it). A change only to apps/web triggers tests for apps/web only.

Remote Caching

Without remote caching, Turborepo's local cache doesn't help in CI – each run starts fresh. With remote caching, build and test artifacts are stored in the cloud and shared across all CI runners and developers' machines.

# Authenticate with Turborepo remote cache (Vercel)
npx turbo login
npx turbo link

Or use a self-hosted cache server if you need to keep artifacts on your own infrastructure. Once configured, a CI run on a branch that touched only apps/web might take 45 seconds instead of 8 minutes, because every packages/* task restores from cache.

A Production-Ready GitHub Actions Pipeline

Here's a complete pipeline that uses Turborepo's caching, runs affected tasks only, and splits lint, test, and build into parallel jobs:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

jobs:
  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx turbo lint --filter="...[origin/main]"

  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx turbo test --filter="...[origin/main]"

  build:
    name: Build
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx turbo build --filter="...[origin/main]"

  e2e:
    name: E2E Tests
    runs-on: ubuntu-latest
    needs: [build]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci
      - run: npx playwright install --with-deps

      - name: Build the app (restores from Turborepo cache if unchanged)
        run: npx turbo build --filter="apps/web"

      - name: Run E2E tests
        run: npx turbo e2e

The E2E job assumes Playwright's webServer config handles starting the app automatically. Configure this in your playwright.config.ts:

// playwright.config.ts
export default defineConfig({
  webServer: {
    command: 'npm run start --prefix apps/web',
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
});

This way Playwright starts the production server before tests run and tears it down afterwards – no manual server management in CI.

The --filter="...[origin/main]" flag is the critical piece. It tells Turborepo to run tasks only for packages that have changed since the main branch, plus all packages that depend on those changed packages. This is the most impactful optimisation in the whole pipeline.

Filtering Strategies

Turborepo's --filter flag is flexible and worth understanding:

# Only run tasks for packages that changed vs main
turbo test --filter="...[origin/main]"

# Run tasks for a specific app and all its dependencies
turbo build --filter="apps/web..."

# Run tasks for everything except a specific app
turbo test --filter="!apps/admin"

# Run tasks for all apps (not packages)
turbo build --filter="./apps/*"

For most CI pipelines, --filter="...[origin/main]" on feature branches and turbo run test build (no filter) on main merges is the right split. You want fast feedback on PRs and confidence that everything still works on main.

Deployment Pipeline with Per-App Filtering

When deploying to Vercel, Netlify, or any platform with per-app deployments, Turborepo lets you detect which apps actually changed and skip deployments for unchanged ones:

# .github/workflows/deploy.yml
- name: Check if web app changed
  id: check-web
  run: |
    CHANGED=$(npx turbo run build --filter="apps/web...[origin/main]" --dry=json | jq '.packages | length')
    echo "changed=\(CHANGED" >> \)GITHUB_OUTPUT

- name: Deploy web
  if: steps.check-web.outputs.changed != '0'
  run: vercel deploy --prod
  env:
    VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

This ensures your admin app doesn't trigger a deployment when only the marketing site changed, reducing deploy times, costs, and the blast radius of any deployment failure.

Environment Variable Management

One of the trickier parts of a monorepo CI setup is environment variables: each app needs its own secrets, but some are shared across apps.

A clean convention:

# .env (repo root , shared across all apps in local dev)
DATABASE_URL=...
REDIS_URL=...

# apps/web/.env.local (web-specific overrides)
NEXT_PUBLIC_APP_URL=https://app.example.com
STRIPE_KEY=...

# apps/admin/.env.local (admin-specific)
NEXT_PUBLIC_APP_URL=https://admin.example.com
ADMIN_SECRET=...

In CI, store shared secrets as organisation-level GitHub secrets and app-specific secrets as repository-level secrets scoped to the appropriate environment.

Never store secrets in turbo.json or any committed file. Instead, use env in your pipeline steps and Turborepo's globalEnv field in turbo.json to declare which env vars should bust the cache when they change:

// turbo.json
{
  "globalEnv": ["NODE_ENV", "DATABASE_URL"],
  "tasks": {
    "build": {
      "env": ["NEXT_PUBLIC_APP_URL", "STRIPE_KEY"],
      "dependsOn": ["^build"],
      "outputs": [".next/**"]
    }
  }
}

This tells Turborepo: if DATABASE_URL changes, invalidate the cache for all tasks. If NEXT_PUBLIC_APP_URL changes, only invalidate the build task. Without this, you risk Turborepo restoring a cached build that was compiled against a different environment, a subtle and painful bug.

Putting It All Together: The Full Blueprint

Here's what the complete architecture looks like assembled:

my-platform/
  apps/
    web/
      app/
        (marketing)/
          layout.tsx
          page.tsx
          about/page.tsx
        (app)/
          layout.tsx            # Auth-protected shell
          dashboard/
            page.tsx            # Server Component , fetches data
            loading.tsx
            components/
              MetricsDashboard.tsx
              ChartSection.tsx  # 'use client'
          orders/
            page.tsx
            [id]/
              page.tsx
              components/
                OrderTimeline.tsx
                CancelButton.tsx  # 'use client'
      src/
        features/
          auth/
            components/
            hooks/
            lib/
            index.ts
          billing/
            ...
        shared/
          components/
          hooks/
          lib/
    admin/
      app/
        ...                     # Same layer structure
      src/
        features/
          ...
  packages/
    ui/                         # Shared primitives
    auth/                       # Shared auth logic
    database/                   # Prisma + queries
    config/                     # ESLint, TS, Tailwind configs
    utils/                      # Generic helpers
  turbo.json
  package.json

Notice how the 'use client' boundary appears only at the interactive leaves: ChartSection.tsx needs useState, and CancelButton.tsx needs a click handler and useTransition. Everything above them (MetricsDashboard.tsx, OrderTimeline.tsx, the page components) stays on the server, fetching data and composing layout without shipping any JavaScript to the browser.

The layers stack cleanly:

1. Turborepo packages: the lowest layer. Generic, reusable, no app-specific knowledge.

2. Shared feature layer: cross-cutting app concerns. Can consume packages, knows nothing of routes.

3. Feature modules: domain logic, encapsulated behind barrel exports.

4. App Router: routes, layouts, colocation. Consumes features and packages. Data flows through Server Components, interactivity is delegated to Client Component leaves.

Common Pitfalls and How to Avoid Them

"I'll just put it in /utils for now." This is how junk drawers form. If you can't name what a utility belongs to, it probably needs a new feature folder, not a generic dumping ground.

Over-extracting packages too early: Not everything needs to be a shared package. Start in the app, extract to a package only when a second consumer appears. The cost of premature abstraction is maintenance overhead and false coupling.

Client Components at the top of every tree: If your route's page.tsx has 'use client' at the top, you've lost most of what Server Components give you. Push the directive down to the interactive leaf.

Circular package dependencies: If packages/auth imports from packages/database and packages/database imports from packages/auth, you have a cycle. Keep the dependency graph a DAG: each package should have one clear level of abstraction.

Barrel files that export everything: The barrel file is a public API, not an index of every file in the folder. Export only what other parts of the app are meant to use.

Final Thoughts

Good architecture isn't about finding the perfect structure, it's about making the right decisions easy and the wrong decisions hard.

• Colocation makes it easy to find what you need.

• Feature modules make it hard to accidentally couple unrelated domains.

• Turborepo makes it easy to share code and hard to duplicate it.

• Server Components make it easy to fetch data where you need it and hard to send unnecessary JavaScript to the browser.

None of these ideas are new. Layered architecture, separation of concerns, and encapsulation are decades-old principles. What Next.js and Turborepo give you is a modern toolkit to express them idiomatically in a JavaScript codebase.

The best time to set this up is at the start of a project. The second best time is now, before the next feature makes untangling things twice as hard.