Service Layer Refactor

In the last few lessons, you learned how to make your API more professional —
you standardized responses, added validation to incoming data, and introduced structured logging.
Now it’s time to organize all that logic into a cleaner, more scalable structure — the service layer.

As your API grows, route files tend to become overloaded. They start doing too many things:
reading requests, validating data, applying business logic, modifying data, and sending responses.
This clutter makes your code hard to maintain, test, or even read.

A service layer solves this by separating your business logic from your request handling logic.
It becomes the “core brain” of your backend — where your app’s rules and behaviors live — while the route files act only as controllers that coordinate incoming and outgoing data.

By introducing a service layer now, you’re setting up your Remix backend for long-term maintainability and scalability.

To understand the need for a service layer, let’s think about what’s currently happening in your API routes.

Each route:

• Parses the request.
• Validates the data.
• Applies logic to the user list (like creating or updating users).
• Formats and returns a response.

This is fine for a small demo project, but as soon as you add more features — like roles, permissions, or external data fetching — these files can become messy.

Separation of Concerns:
Routes should handle communication (requests and responses), not business logic.
The service layer cleanly separates what the API does (business logic) from how requests are handled.

Reusability:
You can use service functions in multiple routes, or even in other parts of your app (like background jobs or CLI tools), without duplicating code.

Testability:
You can easily test service functions in isolation without needing to mock entire HTTP requests.
This makes your codebase more robust and easier to maintain.

Scalability:
As your app grows, your service layer can connect to databases, authentication systems, or external APIs — all without changing how your routes work.

In short:
The service layer keeps your routes lean, your logic centralized, and your code adaptable to future growth.

File: app/lib/services/userService.ts

import { users, type User } from "~/lib/data";

type OptionalUserFields = Partial<Omit<User, "id" | "createdAt">>;

function normalizeRole(role: unknown, fallback: string): string {
  return typeof role === "string" && role.trim() !== "" ? role.trim() : fallback;
}

function normalizeIsActive(isActive: unknown, fallback: boolean): boolean {
  return typeof isActive === "boolean" ? isActive : fallback;
}

export function getAllUsers(): User[] {
  return [...users];
}

export function getUserById(id: number): User | undefined {
  return users.find(candidate => candidate.id === id);
}

export function createUser(payload: OptionalUserFields & Pick<User, "name" | "email">): User {
  const nextId = users.length > 0 ? Math.max(...users.map(u => u.id)) + 1 : 1;

  const newUser: User = {
    id: nextId,
    name: payload.name.trim(),
    email: payload.email.trim(),
    role: normalizeRole(payload.role, "user"),
    isActive: normalizeIsActive(payload.isActive, true),
    createdAt: new Date().toISOString()
  };

  users.push(newUser);
  return newUser;
}

// ... replaceUser, patchUser, deleteUser

Each function in the service layer has one clear purpose:

• getAllUsers() → returns all users.
• getUserById() → returns a user if it exists.
• createUser() → adds a new user and applies normalization rules.
• replaceUser(), patchUser(), and deleteUser() → update or remove users as needed.

Helper functions like normalizeRole() and normalizeIsActive() ensure data is always stored consistently.

These service functions work directly with data but do not know anything about HTTP requests or responses.
That’s what makes them reusable and testable — they’re just plain logic.

Once your logic is extracted, routes become clean and focused.

Before:
Your routes handled everything — reading data, validating input, creating users, and formatting responses.

After:
They simply:

1. Parse and validate requests.
2. Call the appropriate service function.
3. Return a standardized response.

import { ok, err } from "~/lib/responses";
import { validateUserPayload } from "~/lib/validation";
import { withLogging } from "~/utils/withLogging.server";
import { createUser } from "~/lib/services/userService";

export async function action({ request }) {
  return withLogging("POST /api/users", async () => {
    if (request.method !== "POST") return err("Method Not Allowed", 405);

    try {
      const body = await request.json();
      const errors = validateUserPayload(body, { requireAll: true });
      if (errors.length) return err(errors, 400);

      const created = createUser({
        name: body.name,
        email: body.email,
        role: body.role,
        isActive: body.isActive
      });

      return ok(created, 201);
    } catch {
      return err("Invalid JSON body", 400);
    }
  });
}

Why This Is Better

• The route is shorter, clearer, and easier to read — you can understand it at a glance.
• Validation and response formatting stay at the route level.
• All real work (data manipulation, normalization, ID generation) happens in the service layer.
• A service layer reduces and localizes the changes needed when switching storage.
• If the service interface remains stable, route changes can be minimal.

With this refactoring, your Remix backend now has four clearly defined layers:

1. Routes (Controllers):
   Handle HTTP requests and responses.
   Example: app/routes/api.users.tsx

2. Service Layer:
   Contains business logic — how data is created, updated, filtered, or deleted.
   Example: app/lib/services/userService.ts

3. Validation Layer:
   Ensures input data is clean before it reaches the service layer.
   Example: app/lib/validation.ts

4. Response Utilities:
   Provide standardized success and error response structures.
   Example: app/lib/responses.ts

Request flow:

Request → Remix route → validateUserPayload → userService → ok/err response → withLogging logs result

Each layer has a single responsibility, making your code modular, testable, and easy to extend.

Imagine your project expands to include:

• A database like PostgreSQL.
• Role-based permissions.
• Background jobs or scheduled updates.

If all your logic lived inside route files, you’d need to rewrite a lot of code.
But with a service layer:

• Most storage-specific changes would live in the service layer, while route changes can often stay small if the service interface remains stable.
• You could reuse the same logic for APIs and background workers.
• Tests can call createUser() or deleteUser() directly, without mocking HTTP requests.

You’re building habits that make your backend future-ready.

In this lesson, you learned:

• What a service layer is and why it’s essential for scalable API design.
• How to move business logic out of routes and into reusable service functions.
• How this separation improves readability, maintainability, and testability.
• How your Remix API architecture now fits together as modular layers.

By introducing a service layer, you’ve completed the foundation for a modular backend architecture.
Your API is now consistent, validated, observable — and organized.

In the next section, you’ll extend the service layer and see how easily you can adapt your API to handle new behaviors without rewriting your routes.