Admin Services

The Admin Services provide the management plane for system operators and merchant integrations. They manage organizations, users, sites, providers, domains, API keys, invoices, reporting, tax, data import/export, and license activation.

Admin Backend

The Admin Backend is a Go service using Gin, MongoDB, WebAuthn, JWT sessions, API-key authentication, OpenTelemetry middleware, structured logging, and field-encryption support.

Key Subsystems

1. Authentication and access control: Browser users authenticate with WebAuthn/JWT. Merchant integrations use API keys with scoped permissions, for example checkout:create. The secured route group accepts either auth mode, then applies user context, audit logging, license checks, permissions, and scope middleware.
2. Checkout creation: POST /api/v1/checkouts/{siteId}/create creates checkout sessions for merchant server integrations. The service validates API-key scope, site/provider configuration, tax inputs, and initializes provider-side payment data where required, such as Stripe PaymentIntents.
3. Domain management: Public GET /api/v1/domains/verify is used by Caddy's on-demand TLS ask check. Authenticated domain routes manage CNAME verification, ACME HTTP challenges, activation retry, Apple Pay files, and CRUD operations.
4. Licensing: /api/v1/system/licensing and its activation, heartbeat, and deactivation endpoints are deliberately exempt from runtime license blocking so global admins can activate or recover an installation.
5. Tax Management: Organizations configure seller context, rate schedules, EU OSS / IOSS flags, small-business exemptions, and rounding. The service materializes canonical tax records for audit and drives by-country, revenue-by-country, and VAT OSS reports.
6. Invoicing and documents: Invoice issue, void, correction, credit note, recurring schedule, payment checkout, PDF regeneration, ZUGFeRD/PDF, XML, and Peppol BIS 3.0 XML routes are owned by the admin backend. Slow document generation is queued to the worker.
7. System settings: Global encryption, API-key auth policy, portal settings, user-management policy, notifications, templates, and licensing are separate from organization settings.

Observability

Every request receives a request ID and structured JSON log context. Health endpoints include MongoDB, cache, and encryption checks. Swagger is exposed under /api/v1/docs for integration visibility.

Admin Frontend

The Admin Frontend is a React single-page application served by a Node/Express server. The browser calls /api/v1/*; the frontend server proxies /api/* to the configured Admin Backend target.

Key Interface Areas

• Dashboard: Transaction volume, revenue, and failure metrics.
• Transactions: Searchable ledger with filtering by status, provider, site, and date range.
• Invoicing: Invoice lifecycle, credit notes, corrections, document templates, e-invoicing, and payment links.
• Recurring: Schedule creation, pause/resume/cancel, upcoming invoice previews, and generation.
• Clients: Customer records, VAT validation status, documents, and history.
• Settings: Organization checkout, tax, notification, template, retention, geolocation, portal, and encryption configuration.
• System: Global encryption, system API keys, portal defaults, notifications, templates, user-management policy, and licensing.
• API Keys: Organization and system API keys with scope assignment, rotation, and revocation.

License Guarding

The route configuration distinguishes licensed routes from the global admin licensing route. /system/licensing uses a global-admin route without requiresLicense, so it remains reachable for activation and recovery. Most other global-admin and organization routes require a usable license before the page is rendered.