One Contract, Two Backends: Offline Parity for Web and Mobile

JID Carwash ERP runs on three surfaces: a NestJS 10 plus Prisma 5 API, a Next.js 15 POS and admin panel, and a Flutter 3.22 field app the crew carries around the wash bays. Early on I hit a boring but expensive problem. The owner wanted to see the POS on his laptop during a meeting with no Wi-Fi. My frontend teammate wanted to build the payroll screen before the payroll endpoints existed. And I wanted my Flutter tests to run in CI without spinning up a Postgres database. All three are the same problem wearing different hats: the UI should not care whether a real backend is on the other end.

The fix was the repository adapter pattern applied consistently across both frontends. Each domain gets one contract, and two interchangeable implementations sit behind it. This is the same abstraction that clean-architecture Flutter apps use to keep the domain layer ignorant of data sources, and that typed TypeScript API clients use so the UI compiles against a spec rather than a live endpoint. Here is exactly how it works in a shipped codebase, including the trap that makes most mock layers lie.

One contract, defined once

Everything starts from a single types file. It declares the shape of each entity and the methods every repository must provide. The contract is the law both implementations obey, and critically, it encodes the domain invariants directly in the types. Money is an integer count of IDR, never a floating-point number, so the field is a plain number named to make its unit obvious. Every list and detail call takes a branchId, because on the server side every Prisma query is scoped by branch to prevent one branch from reading another's orders.

// apps/pos-web/src/api/types.ts — the single contract both clients honor
export interface OrdersRepository {
  list(params: { branchId: string; status?: OrderStatus }): Promise<Order[]>;
  getById(branchId: string, orderId: string): Promise<Order>;
  create(input: CreateOrderInput): Promise<Order>;
  settle(
    orderId: string,
    payment: PaymentInput,
    idempotencyKey: string,
  ): Promise<Order>;
}

export interface Order {
  id: string;
  branchId: string;        // every read is scoped by this
  pelangganId: string | null;
  totalIdr: number;        // integer IDR — never a float
  status: OrderStatus;
}

The Next.js side: httpClient versus mockClient

On the web, the two implementations are plain objects that both satisfy the OrdersRepository interface. The live one wraps our HTTP client and hits the NestJS routes. The mock one reads from an in-memory fixtures module. The rule I enforced from day one: the mock must reproduce the same behavior the API guarantees, not merely return data. So the mock filters fixtures by branchId exactly like the server scopes its queries, and its settle method dedupes on the idempotency key exactly like the real settlement service does. If the mock skipped those, the demo would behave differently from production and the whole point would collapse.

// apps/pos-web/src/api/http/orders.http.ts — live implementation
export const httpOrders: OrdersRepository = {
  list: ({ branchId, status }) =>
    api.get(`/branches/${branchId}/orders`, { params: { status } }),
  settle: (orderId, payment, idempotencyKey) =>
    api.post(`/orders/${orderId}/settle`, payment, {
      headers: { "Idempotency-Key": idempotencyKey },
    }),
  // ...
};

// apps/pos-web/src/api/mock/orders.mock.ts — fixture implementation
export const mockOrders: OrdersRepository = {
  list: async ({ branchId, status }) =>
    fixtures.orders
      .filter((o) => o.branchId === branchId)   // same branch scope as the API
      .filter((o) => !status || o.status === status),
  settle: async (orderId, payment, idempotencyKey) =>
    settleInMemory(orderId, payment, idempotencyKey), // dedupes on the key, like prod
  // ...
};

The Flutter side: ApiRepository versus MockRepository

The field app mirrors the exact same idea in Dart, just with language-appropriate tools. Each feature declares an abstract interface class, then ships two concrete classes. The live ApiOrdersRepository talks to NestJS and, when the device is offline, queues its writes into an outbox that connectivity_plus drains once the signal returns. The MockOrdersRepository holds fixtures in memory and powers both demos and widget tests. Riverpod wires the choice at the provider level, so no widget ever imports a concrete repository directly; they all watch the provider and receive whichever implementation the config selected.

// apps/field-app/lib/features/orders/data/orders_repository.dart
abstract interface class OrdersRepository {
  Future<List<Order>> list({required String branchId, OrderStatus? status});
  Future<Order> settle(String orderId, PaymentInput payment, String idempotencyKey);
}

// Live: talks to NestJS; queues writes in the outbox when offline
final class ApiOrdersRepository implements OrdersRepository { /* ... */ }

// Fixtures: powers demos and widget tests, no network at all
final class MockOrdersRepository implements OrdersRepository { /* ... */ }

final ordersRepositoryProvider = Provider<OrdersRepository>((ref) {
  return ref.watch(appConfigProvider).useMock
      ? MockOrdersRepository()
      : ApiOrdersRepository(ref.watch(httpClientProvider));
});

Swapped by config, not by code

The swap is one boolean, resolved once at the composition root. On the web it is an environment variable read at build time; in Flutter it is a field on the app config provider set from a build flavor. Every component and every screen imports the neutral name, never the http or mock variant. That single indirection is what makes the whole thing painless: to run a no-Wi-Fi demo I set the flag to mock and the exact same UI runs against fixtures; to ship production I leave it live. Nothing in the feature code changes.

// apps/pos-web/src/api/index.ts — the composition root
const useMock = process.env.NEXT_PUBLIC_API_MODE === "mock";

export const orders: OrdersRepository = useMock ? mockOrders : httpOrders;
export const payments: PaymentsRepository = useMock ? mockPayments : httpPayments;

// Components import `orders` — never `httpOrders` or `mockOrders` directly.

What the pattern actually bought us

• Demos with no backend. The owner runs the full POS on his laptop at a meeting with no network, ringing up orders and settling payments against fixtures that look exactly like a real branch's day.
• Frontend that never waits. The payroll and kasbon screens were built and reviewed weeks before those endpoints existed, coding straight against the mock and switching to live once the API shipped.
• Fast, deterministic tests. Flutter widget tests and Next.js component tests run against fixtures in CI with no Postgres, no network flakiness, and identical results on every run.
• A safe onboarding sandbox. New contributors clone the repo, set the flag to mock, and have a working ERP in one command without any secrets or database access.

Api versus Mock at a glance

The pattern is not free. You maintain a second implementation of every repository, and the invariant discipline above is real work. But for a product with three surfaces sharing one domain, the alternative is worse: a UI coupled to a live backend cannot be demoed offline, cannot be built ahead of its API, and cannot be tested without infrastructure. One contract and two adapters bought all three, and the config flag that switches them is the cheapest line of code in the whole codebase.