docs: add GraphQL schema draft for the catalog

[ronjalh]

Summary

Adds the first draft of the GraphQL API, written schema first, together with the documentation of the choices behind it. No server code yet: this is the contract that the frontend and the backend can build on.

• backend/src/schema.graphql: the catalog (apparatus, element groups, elements and vaults behind a CatalogItem interface, variants), searchCatalog with search, filter, sort and cursor pagination, the user data (coach, gymnast, routine), login, and the mutations for gymnasts and routines.
• docs/API.md: why GraphQL and not REST, how the schema differs from the database, search and pagination, scalability, login, error handling, images, tooling, configuration and a test plan for the API.
• docs/USER_LIST_PAGINATION.md: why the lists of gymnasts and routines are plain lists with limits and not cursor connections, and when to change that.
• README.md: a "Why GraphQL and not REST" section.
• docs/DATA_MODEL.md and docs/AI_USAGE.md: the image decision, the derived search tables, and how AI was used for this work.

Main decisions

• Cursor pagination for the catalog (first/after, totalCount only calculated when asked for), with a page size of 1–100.
• Errors are GraphQL errors with a code in extensions.code (UNAUTHENTICATED, NOT_FOUND, NAME_TAKEN, INVALID_ITEMS, BAD_USER_INPUT, LIMIT_REACHED). me returns null when nobody is logged in. Other coaches' data gives NOT_FOUND, so ids cannot be probed.
• imageUrl instead of a file name: the database keeps the file name and the API gives a full URL.
• Elements and vaults share one list through the CatalogItem interface, so one search covers both.

Open point for review: how the search is implemented

docs/API.md currently describes a search that never uses raw SQL: a read-only CatalogEntry table and a CatalogWord table, queried with Prisma startsWith. Issue #24 plans a different search: ILIKE on search_text with a trigram index, a three character minimum, and suggestions from trigram similarity when nothing is found. Issue #22 plans a catalog_items view for the combined list.

These need to be reconciled before the backend is built. The questions are listed on #24. Once the team has decided, API.md and DATA_MODEL.md will be updated to match, so this PR should be read as a draft of the schema and the reasoning, not as the final word on the search.

How to review

• Read backend/src/schema.graphql first, then docs/API.md.
• Check that the fields are what the frontend needs, and that the limits and error codes are acceptable.
• The schema parses with graphql@16 (buildSchema). Nothing else can be run yet, because there is no server.

Related to #28.

🤖 Generated with Claude Code