# 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
- [Markets](/docs/llms/markets.md): The storefronts as data — what a market drives (order classification, sales channel, translations, visibility, "sælges på", Magento hosts), validation, Magento's listed flag, the order for opening a new market, and the per-market field value import from Magento
- [Durable jobs](/docs/llms/durable-jobs.md): Workers v2 — one queue ordered by priority, exclusive keys, the adaptive limit per external resource (latency, 429s, provider budget headers), isolation of slow APIs, the governor that sizes the worker, statuses, metrics, overrides, rollback, and the benchmark
- [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
- [Novin customer portal](/docs/llms/customer-portal.md): Customer users and portal accounts, the closed-by-default portal principal, what an account may see and where each figure comes from
- [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
- [Object storage](/docs/llms/object-storage.md): Hetzner Object Storage in production and a MinIO emulator locally, the two buckets and their very different access models, the single addressing switch and why it is single, which database columns hold absolute media URLs, and the contract test that keeps emulator and production honest
- [Error handling](/docs/llms/errors.md): Standard error shapes, auth errors, permission errors, and validation errors