Forem: Hamza Saleem

Scaling to 70 Modules: Building a Web, Mobile, and API backend on one Convex deployment

Hamza Saleem — Wed, 21 Jan 2026 06:31:53 +0000

Production Convex: What 70 Modules Looks Like

What I learned building one Convex backend for web, mobile, and API

When I started building Client Commander, I had one Next.js app and maybe ten tables. A year later, it's serving a web dashboard, a mobile app, a background sync service, and a full REST API. 50+ tables. 70+ modules. Same deployment.

I didn't plan for any of that. I just kept building, and the architecture held up. That surprised me.

Here's how it happened.

What We Built

Client Commander is a multi-tenant CRM. Companies sign up, add their team, manage contacts and deals. Nothing revolutionary about the domain — but the technical requirements add up fast: permissions, real-time sync, mobile, API access, background jobs.

Quick terminology so the rest makes sense:

Agents: The users (employees) using the system.
Contacts: The people/customers being tracked.
Companies: The tenants (customers of the SaaS).

Permissions That Update Themselves

Change someone's role, and their dashboard updates in real-time. They see different data instantly — no refresh, no logout, no waiting.

I didn't build that. I just wrote a normal permission check at the top of my queries, and it worked.

Took me a while to understand why. Convex queries are subscriptions, not one-off requests. They keep running — every time the underlying data changes, the query re-evaluates. So my permission check runs again when contacts change. It runs again when the user's role changes. Same code, always current.

const { agentId, companyId, role } = await getAuthContext(ctx);

if (!hasPermission(role, "contacts.view")) {
  throw new Error("Forbidden");
}

return await ctx.db.query("contacts")
  .withIndex("by_company", q => q.eq("companyId", companyId))
  .collect();

Adding new permission levels was just config after that. Owner sees everything. Team Leader sees their team. Agent sees only their own contacts. New roles? Add them to the config. Queries stay the same.

The part that impressed me: Convex tracks which data each query actually touches. My query reads the user's role, so the platform knows that query depends on that role record. Change the role, and only queries that care about it re-run — not everything. I didn't set up subscriptions or configure channels. It figured that out from the code.

With most backends, you'd need WebSocket infrastructure, cache invalidation, push logic — a whole thing. Here it's just... the default.

Adding Mobile Without Adding Backend

We shipped a mobile app. Zero new backend code.

But honestly, the time savings wasn't the main thing. The main thing was this: we stopped discovering "mobile is out of sync" from user bug reports. We started discovering it before the code compiles.

The Expo app imports the exact same API as the Next.js app. Same queries, same mutations, same types. Fix a bug in a query? Fixed on both. Change the schema? Both apps break until they handle it — during development, not after users complain.

// Same import, whether you're in Next.js or Expo
import { api } from "@workspace/backend/convex/_generated/api";

const contacts = useQuery(api.contacts.list);
const createContact = useMutation(api.contacts.create);

Convex generates typed APIs from your schema. That generated code is the contract. Write a query, and it creates types for the arguments and return value. Call it from React — web or mobile, doesn't matter — you get autocomplete and type checking.

The monorepo makes it work. Backend is a shared package. Both apps depend on it. Schema is the single source of truth.

Add a field? Both apps get type errors. Rename a query? TypeScript shows you every callsite that needs updating — across platforms, in one compile. I've caught so many things this way that would've been production bugs otherwise.

Most cross-platform setups have duplicated types, separate clients, manual syncing. Here, the generated API handles sync. Change the source, types change everywhere. No process to remember. It just breaks if you forget.

Real-Time for Users, REST for Everything Else

Real-time is great for dashboards. But external integrations don't speak WebSocket. They want REST. Webhooks need HTTP endpoints.

So we added a REST API — 40+ endpoints. No separate service. The HTTP layer just authenticates, rate limits, then calls the same functions that power the UI.

http.route({
  path: "/v1/contacts",
  method: "GET",
  handler: httpAction(async (ctx, request) => {
    const auth = await verifyApiKey(request);
    if (!auth.ok) return auth.response;

    const contacts = await ctx.runQuery(internal.contacts.list, {
      companyId: auth.companyId,
    });

    return new Response(JSON.stringify(contacts), {
      status: 200,
      headers: { "Content-Type": "application/json" },
    });
  }),
});

The nice part: ctx.runQuery inside an HTTP action runs the exact same code as the real-time subscriptions. I'm not maintaining two implementations — the REST endpoint is just a thin wrapper around stuff that already exists.

Webhooks work the same way. Payment provider sends a POST, I verify the signature, call a mutation. Same mutation the UI calls. One code path.

No separate API server. No connection pooling headaches. HTTP routes deploy with everything else. We went from "we need an API" to live endpoints in a day.

Workflows That Outlive Deployments

We have workflows that wait three days before executing the next step. Some wait a week.

Here's the thing: I don't lose them when I deploy. I don't wake up to half-finished workflows. I don't build state machines to track what step we're on.

They just continue. Server restarts, new deployment happens, doesn't matter. The delay finishes, the next step runs, picks up exactly where it left off.

If you've ever used scheduler.runAfter, you know it works for one-off delayed functions. But when you need a chain — wait, then do X, then wait again, then do Y — suddenly you're managing state. What if step 2 fails? How do you know step 1 finished? How do you retry?

The workflow component handles that. Each step gets recorded. If something restarts mid-execution, it replays from where it stopped — skipping steps that already ran.

const myWorkflow = workflow.define({
  args: { userId: v.id("users") },
  handler: async (step, { userId }) => {
    await step.runMutation(internal.users.markOnboardingStarted, { userId });

    await step.runMutation(internal.emails.sendFollowUp, 
      { userId }, 
      { runAfter: 3 * 24 * 60 * 60 * 1000 }  // 3 days
    );

    await step.runMutation(internal.users.checkEngagement, { userId });
  },
});

Each step is checkpointed. Server restarts after step 2 is scheduled? Fine. It recovers and picks up where it was.

I build automations that span weeks now without worrying about them. Onboarding sequences, trial expirations — they just run. No job queue to maintain. No polling for stuck jobs. No "what state is this in?" debugging at 2am.

Search Without the Infrastructure

We needed search. Full-text, on contacts. My first thought was "okay, time to figure out Elasticsearch."

Nope. Three lines in the schema.

contacts: defineTable({
  companyId: v.id("companies"),
  fullName: v.string(),
})
  .searchIndex("search_name", { 
    searchField: "fullName",
    filterFields: ["companyId"] 
  })

That's it. Search works. Filters by company. Ranks by relevance. Deploy, it's live.

Same pattern kept repeating. Need to find contacts by phone number? Add an index. Look up deals by stage? Index. Sort by next task due date? Store it denormalized and index it.

contactPhones: defineTable({
  contactId: v.id("contacts"),
  value: v.string(),
})
  .index("by_value", ["value"])

contacts: defineTable({
  // ...
  nextTaskDueAt: v.optional(v.number()),
})
  .index("by_company_nextTask", ["companyId", "nextTaskDueAt"])

Normally you'd be deciding: which search service, how to sync data, how to handle the lag between your database and search index. Here, search indexes update transactionally with your data. No sync. No eventual consistency weirdness.

The trade-off: I denormalize more than I would elsewhere. fullName gets computed and stored. nextTaskDueAt gets copied from tasks to contacts. Writes get a bit messier. But queries stay fast, and I don't manage infrastructure.

50+ tables, dozens of indexes. Every single one was a schema change, not a project.

That's what 70 modules looks like. One deployment. Web, mobile, REST, all hitting the same backend. Permissions that update in real-time. Types that catch drift before production. Workflows that survive restarts. Search that's three lines.

I didn't do anything clever to make this work. I just kept building, and the platform didn't get in the way.

If you're thinking about using Convex for something real — this is what happens when you do.

Hamza Saleem is the founder of Client Commander and a Convex Champion. Previously: Keeping Users in Sync with Convex.

Easily the best Subscription Tracker for me [Dockerized] [Local] [No Cloud]

Hamza Saleem — Sun, 16 Mar 2025 12:34:08 +0000

I built Subra out of frustration with my own subscription mess.... forgotten trials, surprise charges, and that constant "wait, how much am I spending?" feeling.

It's straightforward: Subra tracks your subscriptions in one clean dashboard, calculates your total spend, and reminds you before payments hit your card. No fluff, no complex features you don't need.

The core tools are free to use:
Subscription calculator
Family plan cost splitter
Spending analyzer

Try it at https://subra.app. No signup needed for the basic tools.

If you would prefer to host on your own without the email reminders. You can easily deploy using Docker with one-click:

Github: https://github.com/hamzasaleem2/subra-local

Subscription Hell? I Built a Way Out

Hamza Saleem — Sun, 02 Mar 2025 17:15:03 +0000

I built Subra out of frustration with my own subscription mess.... forgotten trials, surprise charges, and that constant "wait, how much am I spending?" feeling.

It's straightforward: Subra tracks your subscriptions in one clean dashboard, calculates your total spend, and reminds you before payments hit your card. No fluff, no complex features you don't need.

The core tools are free to use:
Subscription calculator
Family plan cost splitter
Spending analyzer

Try it at https://subra.app. No signup needed for the basic tools.

Keeping Users in Sync: Building Real-time Collaboration with Convex

Hamza Saleem — Sun, 09 Feb 2025 17:24:33 +0000

Sticky my startup, is inspired by the idea of making collaboration as natural as doing it in person. Building features for Stick was both challenging and exciting experience. As I worked through it, I gained alot of insights on how to keep users in sync, handle data efficiently and to make sure everything works smoothly.

Why Real Time Collaboration?

Realtime collaboration is important for modern workflow. Either for brainstorming some ideas, editing documents or debugging your code. Immediate feedback keeps the momentum alive. It lets you bounce ideas of off each other just like you will do in person.

Apps like Google Docs or Figma have done a great job making this possible. I tried to bring the same effortless feel to brainstorming ideas using sticky notes,

Challenges making Real Time Collaboration work:

Its not just about syncing data but also about creating a seamless and engaging experience. Here's how i approached some of the problems using Convex:

Sync and Optimistic Updates

Syncing data in real time is a common challenge in a collaborative app. In Sticky, each user's change needs to be reflected across all the active sessions instantly the traditional approach would require creating a complex system using Pollling and WebSockets. Which requires ton of custom logic and backend setup.

How Convex Solves This:

Convex simplifies this with a native real-time data sync mechanism. By using the useQuery hook, you can easily fetch and sync data, like sticky notes, with minimal setup. Convex handles the underlying complexities of WebSocket connections, keeping all clients in sync automatically. This lets developers focus on creating features instead of managing the socket connections to keep everything connected in real time

Optimistic Updates:

When collaborating in real time, you'd expect changes to appear instantly, however network latency can cause delays in reflecting these updates making the user experience sluggish. to address this properly. I used optimistic updates to instantly reflect changes in the UI even before server save changes in the backend.

What Optimistic Updates Help Solve:

Optimistic updates solve the problem of UI delay caused by network latency. When user creates a new note the change is immediately shown in the Board even though the mutation maybe still be pending. The change is rolled back if mutation fails ensuring data consistency without effecting the user experience.

const createNote = useMutation(api.notes.createNote).withOptimisticUpdate(
  (localStore, args) => {
    const existingNotes =
      localStore.getQuery(api.notes.getNotes, { boardId: actualBoardId }) || [];
    const tempId = `temp_${Date.now()}` as Id<"notes">;
    const now = Date.now();
    localStore.setQuery(api.notes.getNotes, { boardId: actualBoardId }, [
      ...existingNotes,
      { _id: tempId, _creationTime: now, ...args },
    ]);
  }
);

By immediately showing the new note on the board, users can continue collaborating without waiting for the server's response. Only if the mutation completes with a different result will the UI be updated accordingly.

Real-time Presence Tracking Tracking who is online and where they are on the board is essential for real-time collaboration. In Sticky, I needed to show users cursor positions, indicating where others are working on the board. Real-time presence tracking also ensures that the team knows who is active and engaged.

What I Learned:

Implementing real-time presence required handling frequent updates of user cursor positions, which can overwhelm the system if not managed efficiently.

How Convex Solves This:

I used debounced updates to efficiently manage the frequency of presence updates. This function ensures the database isn't overloaded with too many requests by limiting the frequent updates.

Here’s a quick explanation of debouncing:

debouncing is a technique where the function only triggers after a specified delay, avoiding redundant or unnecessary calls. In this case, it helps prevent sending excessive updates for small, rapid movements of the cursor.

export function usePresence(boardId: Id<"boards">, isShared: boolean) {
  const updatePresence = useMutation(api.presence.updatePresence);
  const removePresence = useMutation(api.presence.removePresence);
  const activeUsers = useQuery(api.presence.getActiveUsers, { boardId });
  const cursorPositionRef = useRef({ x: 0, y: 0 });
  const [localCursorPosition, setLocalCursorPosition] = useState({ x: 0, y: 0 });

  const debouncedUpdatePresence = useCallback(
    debounce((position: { x: number; y: number }) => {
      if (isShared) {
        updatePresence({
          boardId,
          cursorPosition: position,
          isHeartbeat: false
        });
      }
    }, PRESENCE_UPDATE_INTERVAL, { maxWait: PRESENCE_UPDATE_INTERVAL * 2 }),
    [boardId, updatePresence, isShared]
  );

  useEffect(() => {
    if (!isShared) return;

    const heartbeatInterval = setInterval(() => {
      updatePresence({
        boardId,
        cursorPosition: cursorPositionRef.current,
        isHeartbeat: true
      });
    }, HEARTBEAT_INTERVAL);

    return () => {
      clearInterval(heartbeatInterval);
      removePresence({ boardId });
    };
  }, [boardId, updatePresence, removePresence, isShared]);

  return {
    activeUsers: isShared ? activeUsers : [],
    updateCursorPosition,
    localCursorPosition
  };
}

By debouncing the updates, the system can efficiently tracks user activity without overwhelming the backend or causing performance issues.

Schema Design and Indexing As real-time data grows, efficient database design becomes crucial. I had to ensure that data could be retrieved quickly as the board and user base expanded.

How Convex Helps:

Convex's schema design allows for easy definition of tables and indexes.

For example, the presence table schema enables efficient queries based on user and board, as well as tracking the last update time for each user.

presence: defineTable({
  userId: v.id("users"),
  boardId: v.id("boards"),
  lastUpdated: v.number(),
  cursorPosition: v.object({
    x: v.number(),
    y: v.number(),
  }),
})
  .index("by_board", ["boardId"])
  .index("by_user_and_board", ["userId", "boardId"])
  .index("by_board_and_lastUpdated", ["boardId", "lastUpdated"]);

These indexes ensure that as the database grows, data retrieval remains fast, even with a large number of active users or boards.

End-to-End Type Safety A major advantage of using Convex is its seamless integration with TypeScript. The type safety that TypeScript offers across the stack is a huge benefit when building real-time systems. With type-safe queries, mutations, and schema definitions, I was able to catch potential bugs during development, making the entire process smoother and more predictable.

Lesson Learned

I learned was how important is is for state management to be simple. Real time systems are naturally complex but with right tools it can be make a huge difference. With Convex, I can focus on creating a great user experience instead of worrying about the technicals.

A Final Thought

Building Sticky was a rewarding experience. The process taught me a lot about real-time systems and the value of tools that simplify complex tasks. For anyone looking to implement similar features, my advice is to start small, leverage existing tools, and iterate as you learn.

Check out Sticky to see these features in action or explore the source code for more implementation details.