Query Modules

57 TanStack Query (React Query) modules in frontend/src/lib/queries/ (as of 2026-06, excluding tests and the barrel index.ts). Each module encapsulates query keys, query hooks, and mutation hooks for a specific domain entity.

Module Pattern

Every module follows the key factory + as const pattern:

export const buildingKeys = {
  all: ['buildings'] as const,
  lists: () => [...buildingKeys.all, 'list'] as const,
  list: (filters: Filters) => [...buildingKeys.lists(), filters] as const,
  details: () => [...buildingKeys.all, 'detail'] as const,
  detail: (id: string) => [...buildingKeys.details(), id] as const,
};

Central key registry: frontend/src/lib/queryKeys.ts.

Key Modules

Module	File	Entity / Domain
buildingQueries	buildingQueries.ts	Buildings (plus buildingComponentQueries, buildingPhotosQueries, buildingRoleQueries, technologyQueries)
projectQueries	projectQueries.ts	Projects (plus scenarioQueries for Scenarios)
contactQueries	contactQueries.ts	Contacts (with HubSpot sync)
companyQueries	companyQueries.ts	Companies (with HubSpot sync)
quoteQueries	quoteQueries.ts	Quotes, allocations, links
invoiceQueries	invoiceQueries.ts	Invoices, line items
billing* (6 modules)	billingQueries.ts, billingItemsQueries.ts, billingMailQueries.ts, billingServiceCatalogQueries.ts, billingStandaloneInvoiceQueries.ts, billingDocumentTemplates.ts	Billing domain
workflowQueries	workflowQueries.ts	Workflows (Workflow v4 board; plus scopeChangesQueries for quote-change badges/drawer)
contractor* (3 modules)	contractorEngagementQueries.ts, contractorInquiriesQueries.ts, contractorTranchesQueries.ts	Contractor engagements, inquiries, tranches
siteProtocolQueries	siteProtocolQueries.ts	Site protocols on the building dashboard (PR#1969)
fundingApplicationQueries	fundingApplicationQueries.ts	Funding Applications (plus fundingProgramQueries)
documentObtainingQueries	documentObtainingQueries.ts	Document Obtaining (plus documentRequestQueries, documentTemplateQueries, documentTemplateLabelQueries, flowDefinitionQueries)
fileQueries	fileQueries.ts	Files (plus fileCollectionQueries)
portalQueries	portalQueries.ts	Portal operations (plus portalAppointmentQueries)
authQueries	authQueries.ts	Authentication (plus permissionQueries, roleQueries, profileQueries)
pdfQueries	pdfQueries.ts	PDF Templates
hubspot-queries	hubspot-queries.ts	HubSpot Integration (plus property-mapping and enum-mapping modules)
adminQueries	adminQueries.ts	Admin Dashboard, Users (plus entraGroupQueries, engagementTaskTemplatesAdminQueries)
dashboardQueries	dashboardQueries.ts	Building dashboard (plus timelineQueries, revenueQueries, performanceQueries, activityQueries)
appointmentQueries	appointmentQueries.ts	Appointments
sevdeskPaymentSyncQueries	sevdeskPaymentSyncQueries.ts	sevDesk payment sync

Former leadQueries, productQueries, and formQueries modules no longer exist as standalone files; their domains are served by other modules.

Rules

• Define in lib/queries/ — never inline useQuery/useMutation in components
• ESLint enforced (frontend/eslint.config.js): importing useMutation from @tanstack/react-query in components//pages/ is an error (zero tolerance); inline useQuery and direct @/lib/api imports are warnings (gradual migration)
• Key factories — all query keys built via factory functions with as const for consistent invalidation
• Mutations invalidate related queries via onSuccess callbacks

API Client

Query hooks call the axios api instance (@/lib/api/core), which handles:

• Base URL configuration
• Auth via interceptors
• Error response parsing

Direct fetch() calls are an ESLint error in components//pages/. See API Layer Pattern for the client structure.

Related

• React Query Pattern — Detailed pattern documentation
• API Layer Pattern — Frontend API client organization
• State Management — When to use React Query vs other state tools
• Frontend Architecture — Query module placement in project structure
• Hooks — Custom hooks that compose query modules