Query Modules

35+ TanStack Query (React Query) modules in frontend/src/lib/queries/. 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, technology, components, calc params
projectQueries	projectQueries.ts	Projects, phases, 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
fundingApplicationQueries	fundingApplicationQueries.ts	Funding Applications
documentObtainingQueries	documentObtainingQueries.ts	Document Obtaining
fileQueries	fileQueries.ts	Files
portalQueries	portalQueries.ts	Portal operations
authQueries	authQueries.ts	Authentication
workflowQueries	workflowQueries.ts	Workflows
pdfQueries	pdfQueries.ts	PDF Templates
hubspot-queries	hubspot-queries.ts	HubSpot Integration
adminQueries	adminQueries.ts	Admin Dashboard, Users
dashboardQueries	dashboardQueries.ts	Dashboard statistics
leadQueries	leadQueries.ts	Leads
productQueries	productQueries.ts	Products
formQueries	formQueries.ts	Forms, Form Builder
appointmentQueries	appointmentQueries.ts	Appointments

Rules

• Define in lib/queries/ — never inline useQuery/useMutation in components
• ESLint enforced — warns on useMutation in components/ or pages/
• Key factories — all query keys built via factory functions for consistent invalidation
• Mutations invalidate related queries via onSuccess callbacks

API Client

Query hooks call the API client layer which handles:

• Base URL configuration
• JWT token injection
• Error response parsing

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