imexrps/.ai/data-graphql-hasura.md

Data, GraphQL, Hasura, and Auth Guide

GraphQL Client

Apollo setup lives in src/graphql/GraphQLClient.js.

Links:

• HttpLink uses import.meta.env.VITE_APP_GRAPHQL_ENDPOINT.
• authLink reads Firebase current user token and attaches Authorization: Bearer <token>.
• RetryLink retries transient failures.
• onError logs GraphQL/network errors.
• SentryLink records Apollo operations/errors.
• apollo-link-logger is included in development.

Default options:

• query.fetchPolicy = "network-only"
• watchQuery.fetchPolicy = "network-only"
• connectToDevTools enabled outside production

Cache:

• Query.jobs uses offset merge policy.
• Query.search_jobs uses offset merge policy.

This avoids Apollo "Cache data may be lost when replacing the jobs field" warnings during pagination.

GraphQL Operation Files

• src/graphql/jobs.queries.js: job insert, latest pagination, search pagination, job by id, job by claim number, close date lookup, update/delete, estimate scrubber query.
• src/graphql/joblines.queries.js: jobline update.
• src/graphql/bodyshop.queries.js: current bodyshop, shop update, notifications.
• src/graphql/user.queries.js: user upsert/login association.
• src/graphql/reporting.queries.js: report data.
• src/graphql/notification.queries.js: accept notification.
• src/graphql/veh_group.queries.js: vehicle group lookup.

Hasura Layout

Hasura project files:

• hasura/config.yaml
• hasura/config.yaml.prod
• hasura/metadata/
• hasura/migrations/default/
• hasura/migrations_backup/

Important metadata:

• hasura/metadata/databases/default/tables/
• hasura/metadata/databases/default/functions/public_search_jobs.yaml

Important tables:

• users
• bodyshops
• associations
• jobs
• joblines
• targets
• veh_groups
• groupings
• notifications

Important function:

• search_jobs

Core Relationships

• users.email links to associations.email.
• associations.bodyshopid links users to bodyshops.
• jobs.bodyshopid links jobs to bodyshops.
• joblines.jobid links joblines to jobs.
• Notifications can target a bodyshop.

Schema Evolution Notes

The jobs and joblines schema has grown significantly over time. Do not assume the original create-table migrations show the current shape.

Recent-ish/important fields include:

• jobs: close_date, loss_date, v_age, v_mileage, group, group_verified, requires_reimport, ins_rule_set-related usage through bodyshop settings, owner fields, impact fields, totals/rates JSON, vehicle stage, theft/tlos/insp fields, supplement/betterment amounts, ES fields.
• joblines: line_no, db_ref, price_diff, price_diff_pc, ignore, ADAS/claims clerk/ruleset fields, labor/part flags, tax/cert/glass flags, line refs, modified labor/price fields.
• bodyshops: accepted_ins_co, targets, groups, features, channel, phone, zip_post, es_api_key, mpi_count_quantity, carfax_exclude, ins_rule_set.

Use Hasura metadata and current GraphQL query selections to confirm exact field names before changing queries or migrations.

Authentication

Firebase auth utilities live in src/firebase/firebase.utils.js.

Renderer startup:

1. src/index.jsx mounts Redux and App.
2. src/App/App.jsx dispatches checkUserSession.
3. User sagas validate/load user state.
4. Apollo auth link uses the current Firebase token for GraphQL.

If a user has no shop access, RoutesPage renders a "No shop access" error result.

Data Import Boundary

Electron main decodes local DBF files. Renderer writes decoded results to Hasura. This means import bugs may straddle:

• DBF decoding in electron/decoder/decoder.js.
• IPC payloads in src/ipc/ipc-renderer-handler.js.
• GraphQL upsert helpers in src/ipc/ipc-estimate-utils.js.
• Hasura insert/update permissions and constraints.

When debugging import issues, inspect all four layers.