Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
@carbon/query
The client data layer shared by the ERP and the MES: the TanStack Query cache in front of route loaders, and the realtime system that keeps it and the pages current.
Always
- There is no app-level cache file. Import from
@carbon/query(components) or@carbon/query/cache(route modules);~/utils/react-queryis gone. - Cache a loader by URL, never by a hand-written key.
export const clientLoader = cachedClientLoader<typeof loader>(). The key is[LOADER, companyId, pathname, search]. - Let the root middleware invalidate.
createInvalidationMiddlewaremarks everyLOADERentry stale after any non-GET request. A route does not name the lists its action changes, and exports noclientActionfor that. - Declare a route's tables in
handle.realtime.RouteRealtime(rendered once in each app shell) subscribes to them and reloads the page when one changes. A component that is not a route uses the app'suseRealtime(table, filter?). - A realtime table must have a broadcast handler in
packages/database/src/event-system/attachments.ts.RealtimeTableis derived from it, so an unknown table does not compile. - Import
@carbon/query/cachefrom a route module. It has no React or UI import. The package root (@carbon/query) pulls in@carbon/react.
Ask First
- Changing the cache key shape, or what the middleware invalidates
- Adding a topic shape other than
company:<companyId>:<table>,company:<companyId>:referenceanduser:<userId>:<table>(each needs arealtime.messagespolicy in the authz manifest)
Never
- Name a module here
*.client.tsor*.server.tsif a route calls it at module load: React Router empties.clientmodules on the server, androot.tsxcallscreateInvalidationMiddleware(...)while it is evaluated there. - Subscribe with
postgres_changes. Thesupabase_realtimepublication is empty; a subscription to it delivers nothing and reports no error. - Read
payload.new/payload.old. A broadcast carries{ table, op, ids }and no row data; re-read the rows by id through PostgREST, so table RLS still decides what the user sees. - Use a row count, a sequence value or a timestamp as a live list's cursor. The cursor is the transaction id
table_changes_sincehands back (a snapshot's xmin): a sequence value is taken before commit, so "the highest I saw" skips a row whose transaction commits late.
Validation Commands
pnpm exec turbo run typecheck --filter=@carbon/query
pnpm --filter @carbon/query test
Key Patterns
| Export | Use |
|---|---|
cachedClientLoader, loaderQueryKey, LOADER, RefreshRate |
Cache an api+ loader; build the same key for a component read |
useLoaderQuery(url) |
Read an api+ URL in a component: one shared request per URL, refetched when invalidated. Replaces useFetcher + fetcher.load in a mount effect |
cachedApiQuery(url) |
The same read from an event handler or an effect |
useAction({ onSuccess, onError, onSettled }) |
A mutation fetcher with callbacks. onSettled runs whenever a submission finishes, also when the action redirects and returns no data; onSuccess / onError need data |
setClientCompanyId(companyId, userId) / getCompanyId |
The shell layout sets both during render; the companyId cookie is httpOnly and unreadable in the browser. A different user empties the cache; leaving a company drops its loader entries |
useRevalidator() |
Defined in @carbon/react (the error boundaries need it) and re-exported here. React Router's useRevalidator, held while a fetcher is submitting or a navigation is in flight. The only one app code may import (no-raw-revalidator check): a revalidation during an action drops the fetcher's redirect, and one during the navigation after a save restarts that navigation |
createInvalidationMiddleware({ getCache, skipPaths }) |
Root clientMiddleware; skip POSTs that change no data (/refresh-session) |
RouteRealtime, useRealtimeTable, useTableChanges, useRealtimeRevalidator |
Realtime over private broadcast topics. Reloads go through useRevalidator, so they wait for a save in flight. A route entry { table, column, param } and a <name>Id=eq. filter follow one record's rows only (matchesFilter) |
useRealtimeChannel |
One channel with retry, private and onSubscribed(isReconnect). It reconnects when the tab returns after 5 minutes hidden or with a channel that is not joined — every reconnect reloads the page's data, so time in another tab does not |
LiveLists, useLiveList, LiveList |
Whole lists kept in the cache (items, customers, suppliers, people). IndexedDB first (the stored copy is keyed by company AND user: it is that user's RLS view); then table_changes_since(cursor) names the rows that changed since the stored copy and only those are re-read. The full list is fetched once per device, and again only when the log cannot answer (no cursor, a server restart, a cursor older than 7 days, more than 500 changed rows). Broadcasts patch it in memory while the tab is open; the stored copy is written only when the log is read (a patch does not move the cursor, so storing it buys nothing). Stored lists are removed from the device when they are no longer the user's: another user's or a company outside companyIds at page load, the current company when table_changes_since answers 42501, everything on the login page, and any list not written for 24 hours (STORED_LIST_MAX_AGE_MS). An open page repeats the check every hour and asks the log again, which rewrites its own lists and notices a user who has left the company |
Cross-References
.claude/rules/authz-manifest.md— therealtime.messagespolicies and the event-trigger attachmentspackages/database/src/event-system/functions/broadcast_*.sql— what a message containspackages/database/src/event-system/functions/log_*.sqland20261004200418_table-change-log.sql— the change log (tableChange, UNLOGGED) and its reader.ai/specs/2026-10-04-client-query-cache-and-realtime-broadcast.md— the design and its decisions