Full-Stack Architecture: One API Contract for Web, Mobile, and AI

Most full-stack bugs I've debugged didn't come from hard problems. They came from two parts of the system quietly disagreeing about the shape of the data.

The backend returns total as a string. The web app expects a number. The mobile app was built three weeks earlier and still expects the old field name. Then someone adds an AI assistant that reads the same data and invents its own format. Nobody made a mistake on their own layer. The mistake lives in the gaps.

This post covers one habit that closes most of those gaps: defining your data contract once and sharing it across every layer.

What is an API contract in a full-stack app?

It's a single, written definition of what data looks like as it moves between your database, your API, and your clients (web, mobile, and AI features). If it lives in code, the compiler and tests can enforce it. If it lives in someone's head or a stale wiki page, you find out about disagreements in production.

Why do full-stack projects drift apart?

Different people build each layer at different times. Each one makes reasonable assumptions, and those assumptions slowly diverge. Every boundary between web, mobile, backend, and cloud setup is a place where context gets lost. The projects that stall are rarely the technically hard ones. They're the ones where nobody owned the whole picture.

How do you share one contract across layers?

If your stack is TypeScript end to end (React on the web, React Native on mobile, Node on the server), you can put your schemas in a shared package. Here's a small one using Zod:

// packages/contracts/src/order.ts
import { z } from "zod";

export const OrderSchema = z.object({
  id: z.string().uuid(),
  status: z.enum(["pending", "paid", "shipped", "cancelled"]),
  totalCents: z.number().int().nonnegative(),
  createdAt: z.string().datetime(),
});

export const OrderListResponse = z.object({
  orders: z.array(OrderSchema),
  nextCursor: z.string().nullable(),
});

export type Order = z.infer<typeof OrderSchema>;

I store money as integer cents on purpose. It avoids the floating-point rounding surprises that show up the first time finance compares a report to a receipt.

How does the backend use it?

The server validates its own output before sending it, so a bad database mapping fails loudly in your logs instead of silently in someone's app:

// server/routes/orders.ts
import { OrderListResponse } from "@acme/contracts";

app.get("/orders", async (req, res) => {
  const rows = await db.orders.findMany({ take: 20 });

  const body = OrderListResponse.parse({
    orders: rows.map((r) => ({
      id: r.id,
      status: r.status,
      totalCents: r.totalCents,
      createdAt: r.createdAt.toISOString(),
    })),
    nextCursor: null,
  });

  res.json(body);
});

How do web and mobile use the same contract?

One fetch function works in both React and React Native, because both import the same schema:

// packages/client/src/orders.ts
import { OrderListResponse, type Order } from "@acme/contracts";

export async function fetchOrders(apiUrl: string): Promise<Order[]> {
  const res = await fetch(`${apiUrl}/orders`);
  if (!res.ok) throw new Error(`Orders request failed: ${res.status}`);
  const data = OrderListResponse.parse(await res.json());
  return data.orders;
}

If the backend changes a field, both apps fail the same way in the same place, and you fix it once.

Where do AI features fit in?

This is the part people skip. If you add an AI assistant that answers questions about orders, don't let it build its own version of the data. Have it read through the same service layer the API uses:

// server/ai/context.ts
import { listOrdersForUser } from "../services/orders";

export async function orderContextForAssistant(userId: string) {
  const orders = await listOrdersForUser(userId); // same source as the API
  return orders
    .map((o) => `Order ${o.id}: ${o.status}, total $${(o.totalCents / 100).toFixed(2)}`)
    .join("\n");
}

When is this not the right approach?

Situation	What I'd use
All-TypeScript stack	Shared Zod package, as above
Backend in Java, Python, or .NET	OpenAPI spec plus generated client types
Many external consumers	Versioned public API with an OpenAPI spec
Tiny prototype	Skip it until the second client appears

Mistakes to avoid

• Changing a field without a version plan. Old mobile app versions stay installed for months. Add fields freely, but deprecate before you remove.

• Trusting the client's data. Validate on the server too. The contract helps you, but it isn't a security boundary.

• Letting the AI layer bypass the service layer. A direct query "just for the assistant" is where the disagreement starts.

• No check in CI. Run type checks and contract tests on every change so a breaking edit fails the build, not a customer.

  This is the Production pattern used in organizations, when a product spans web, mobile, cloud, and AI, since it keeps architectural decisions in one place instead of spread across handoffs.