# 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.

