# Supervin Core Backend

> GraphQL API backend for Supervin's custom ERP system. Built with Bun, TypeScript, Elysia.js, GraphQL Yoga, and Drizzle ORM on PostgreSQL. Admin-managed authentication via Google/Microsoft OAuth. Full RBAC with permission-gated access on every operation. Append-only audit log on all mutations and sensitive reads.

Important notes for frontend agents:

- All data access goes through the GraphQL API at `/graphql`. There are no REST endpoints for business data.
- Authentication is token-based: after OAuth login, include `Authorization: Bearer <sessionToken>` on all GraphQL requests.
- Every query and mutation is permission-gated. If the user lacks a required permission, the API returns a GraphQL error with message `Missing required permission: <key>`.
- Users cannot self-register. An admin must create their account via the `createUser` mutation, after which they can log in with Google or Microsoft.
- The Superadmin role is immutable — it cannot be modified, deleted, or stripped of permissions.
- Frontend e2e runs can use `X-Test-run-id` together with `ENABLE_E2E_TEST_MODE=true` for isolated test schemas and `devLogin(email: "cra@supervin.dk")` for baseline login.

## Docs

- [System overview](/docs/llms/overview.md): Architecture, tech stack, module boundaries, and deployment model
- [Authentication](/docs/llms/auth.md): User creation, Google/Microsoft OAuth login, session management, and edge cases
- [GraphQL API](/docs/llms/graphql.md): Schema conventions, all queries and mutations, input/output types, pagination, and filtering
- [Visma order sync](/docs/llms/visma-order-sync.md): Hourly order pull and manual backfill from Visma Business, the extraction/parse/projection/write pipeline, the five test layers and what each cannot catch, and the health counters that surface unmapped Visma values
- [Magento order sync](/docs/llms/magento-order-sync.md): Hourly order pull and manual backfill from Magento's getOrders API, how a Magento order and a Visma order merge into one row, which system wins on which field, and the health counters that show whether the merge is actually happening
- [Product bulk sync](/docs/llms/product-sync.md): `syncProducts` mutation, Visma-number matching, section semantics, warnings vs failures, and n8n verify replacement
- [Search query syntax](/docs/llms/search-query-syntax.md): GraphQL `query` string grammar, operators, limits, warnings, and `includeTotalCount`
- [Search query fields](/docs/llms/search-query-fields.md): Runtime-generated compact field list for searchable GraphQL connections
- [Testing guide](/docs/llms/testing.md): Frontend e2e contract, X-Test-run-id isolation, baseline login, cleanup flow, and local test setup
- [Translations](/docs/llms/translations.md): Generic AI translation engine, entity registration, manual translations as a lock, storefront locales, backfill schedule, and metrics
- [Campaigns](/docs/llms/campaigns.md): Frontend-facing campaign contract, optional product linking, stored title/vintage/color fields, and reusable color palette behavior
- [RBAC & Permissions](/docs/llms/rbac.md): Role model, permission keys, Superadmin rules, and authorization enforcement
- [Audit Log](/docs/llms/audit.md): What is logged, audit entry fields, query interface, and access rules
- [Payments](/docs/llms/payments.md): Gateway adapters and capabilities, capture/refund/cancel and the modification ledger, order-reference ingestion, the `notifyPaymentChanged` entry point Visma uses to report a capture and the `visma_payment_prefix` that routes it to an account, background jobs, and provider-specific gotchas
- [Error handling](/docs/llms/errors.md): Standard error shapes, auth errors, permission errors, and validation errors