MTY HUB / REWRITE 01
A practical build guide

Build the shop app first.

A focused, multi-shop MTY Hub rebuild with Clerk, Convex, Vite, React Router, and Vercel. Start with the workflow your service advisor needs. Add platform complexity only when it earns its place.

DECISION
01

Use Clerk now. It gets organizations, user management, invitations, roles, and polished sign-in UI into the product quickly. Save WorkOS for the moment a real customer needs enterprise SSO or directory sync.

Clerk selected
01 / architecture

One app. Clear ownership.

Each tool gets one job. This keeps the codebase easy to understand for you, Luciano, and the next person who joins the build.

Interface

React + Vite

Fast client application for the logged-in MTY Hub experience.

TypeScript · pnpm
Navigation

React Router

Routes, layouts, protected screens, and shop-aware navigation.

/org/:orgSlug/shop/:shopId
Identity

Clerk

Sign-in, people, organizations, invitations, and company roles.

active organization
Product backend

Convex

Data, realtime updates, functions, jobs, and product authorization.

queries · mutations · actions

Deploy the frontend on Vercel. Convex provides an official Vercel workflow that deploys your frontend and backend functions from the same code push.[3]

02 / why Clerk

Choose the fast path to a real product.

Clerk is the right choice here because the first MTY Hub job is product workflow, not custom identity infrastructure.

What Clerk handles

Clerk brings the identity pieces that otherwise steal weeks from a first release. Its official Convex integration passes a signed-in Clerk session into Convex, where backend functions can use the verified identity.[1]

01
People and sign-in. Passwords, profile details, recovery, and sign-in screens.
02
Organizations. Invite people, switch company context, and assign company-wide roles.[2]
03
Less custom UI. Ship a clean, proven auth experience before designing every auth screen yourself.
03 / tenant model

An organization is a company, not a shop.

Clerk Organizations are designed for multi-tenant apps. A user can belong to more than one organization, and the active organization selects the current company context.[2]

Clerk User

One real person

Lucas, a service advisor, a technician, or an outside accountant. They may work across more than one customer company.

Clerk Organization

One paying company

MTY Collision or a future collision-group customer. This is the company boundary, its members, and its broad role permissions.

Convex shops

Physical locations

Dallas, Fort Worth, and Arlington live under one company. Do not create one Clerk organization per location.

shopMemberships

Location access

A manager may access every shop. A technician may work only in Dallas. Keep this product rule in Convex.

04 / guardrails

Never trust the browser with tenant access.

Clerk includes active-organization information in the session token. Convex functions should still make every ownership and shop check before returning or changing business data.[6]

Every Convex query and mutation

run the gate sequence
Signed-in identityRead the verified Clerk identity from the Convex auth context.
Active companyConfirm the selected organization maps to this MTY Hub tenant.
Shop belongs hereConfirm the requested shop lives under that same company.
Permission is enoughConfirm the role and shop membership permit this action.
05 / start build

Start in a clean bay.

Make the first codebase boring on purpose. The goal is a running app with real identity and a real backend, not a pile of optional tools.

STEP 01

Scaffold a Vite TypeScript app.

Use Vite with React and TypeScript. React Router officially supports this direct Vite setup.[4]

STEP 02

Add Convex and start its dev deployment.

npx convex dev creates the Convex project connection, writes the convex/ folder, and keeps backend functions synced while you build.[5]

STEP 03

Create the Clerk application.

Enable Organizations. Activate Clerk's Convex integration, put the Clerk Frontend API URL in the Convex environment, then add convex/auth.config.ts and sync it with Convex.[1]

STEP 04

Wire the providers once.

At the app root, Clerk wraps the Convex provider. This lets the client send Clerk's auth token to Convex without building a second session system.[1]

STEP 05

Build one usable workflow.

Start with company setup, shop setup, team invites, and one repair-order flow. A good first release lets someone create, assign, update, and close a repair.

06 / release line

Build in three short phases.

Each phase must produce a usable result. Do not wait for the entire dream product before putting the first real workflow in front of a shop team.

Phase 1

Foundation

  • Vite, Router, Clerk, Convex
  • Company + shop setup
  • User invite and access model
  • Shared visual system
Phase 2

One repair flow

  • Customer and vehicle
  • Create repair order
  • Assign staff and move status
  • Notes, photos, activity record
Phase 3

Ship it safely

  • Test core permissions
  • Deploy frontend on Vercel
  • Deploy Convex functions
  • Use a custom domain such as app.mtyhub.com

Do not start with this.

None of these are wrong. They are simply not version-one work. A direct frontend-to-Convex product does not need extra machinery just to feel “serious.”

Separate Express APISQL + ORMtRPCSeparate realtime serviceVite PlusPaymentsCustomer portalAI featuresMonorepo
07 / definition of ready

Version one is ready when the shop can operate.

“Ready” is not a long feature list. It is the moment a real team can get through their daily work without dropping the thread.

✓
Admin creates an organization and adds its physical shops.The future tenant model exists from day one.
✓
Admin invites a user and gives company and shop access.People can work across companies without sharing one account.
✓
Service advisor creates a customer, vehicle, and repair order.The business workflow is the center of the product.
✓
Team updates status, attaches notes or photos, and sees the history.Convex makes the shared data update in realtime.
✓
Unauthorized users cannot read or mutate another shop's data.Permission checks happen in Convex, not only in the UI.

Sources

  1. Clerk and Convex integration. Clerk documents the Convex setup, provider relationship, and verified identity access in Convex functions.
  2. Clerk Organizations. Clerk documents multi-organization users, active organization context, memberships, roles, and permissions.
  3. Using Convex with Vercel. Convex documents Vercel deployment, production deploy keys, custom-domain authentication setup, and preview deployments.
  4. React Router with Vite. React Router documents the Vite bootstrap and BrowserRouter setup.
  5. React and Convex Quickstart. Convex documents the Vite React app setup and npx convex dev flow.
  6. Clerk session tokens. Clerk documents active-organization token claims.
Commands copied