Backend: Compliance reporting & jurisdiction-aware audit exports

[ludovit-scholtz]

Summary

This issue proposes a backend initiative for the Biatec Tokens API to deliver reliable, compliant, and auditable compliance reporting and jurisdiction-aware enforcement. The current platform vision centers on regulated real‑world asset tokenization with enterprise‑grade compliance, yet backend coverage for compliance reporting, jurisdiction tracking, and automated audit outputs is incomplete. We need a cohesive backend feature set that exposes compliance state, audit artifacts, and readiness signals to the frontend and external integrators in a consistent, secure API. This issue focuses on building the API contracts, data models, and background processing needed for compliance reporting and audit trail export, plus a minimal but extensible jurisdiction rules engine that can be consumed by UI and external systems. The intent is to de‑risk regulatory adoption and reduce the gap between the current MVP state and the Phase 2 enterprise compliance vision outlined in the business owner roadmap.

Business Value

The Biatec Tokens business model targets subscription revenue from enterprise and professional customers who require credible compliance tooling. At present, the roadmap highlights partial implementation of compliance reporting, jurisdiction tracking, and regulatory integration. Without a reliable backend for compliance artifacts, the platform cannot credibly sell enterprise plans, and it risks churn among early adopters who must meet MICA requirements. A backend compliance reporting service becomes a differentiator because competitors often show surface‑level badges but cannot produce auditable proof or machine‑readable compliance exports. This capability directly improves conversion for regulated institutions, accelerates sales cycles, and supports higher pricing tiers. It also reduces support costs by enabling standardized exports that auditors and regulators can consume without bespoke manual effort.

From a market perspective, the RWA tokenization segment is growing rapidly and compliance is a core gating factor for adoption. MICA and FATF guidelines require documented compliance evidence, including issuer attestations and audit trails. If we can generate consistent compliance reports and an audit log that are easily accessible via API and UI, we unlock concrete business value: faster onboarding of enterprise customers, fewer compliance objections, and improved trust. The dashboard and onboarding experiences in the frontend depend on backend APIs that can reliably provide compliance status, readiness flags, and rationale for those statuses. In turn, this data can drive analytics and product insights around which compliance steps correlate with successful token issuance and conversion.

This issue aligns with the roadmap’s Phase 2 Enterprise Compliance objectives, including jurisdiction tracking, compliance reporting, and regulatory integration readiness. Implementing a robust backend foundation now allows the UI to move ahead in parallel and reduces time to revenue by enabling the sales team to demonstrate compliance evidence in pilots. It also sets the groundwork for future KYC and AML integration, without forcing a redesign of core data models later. The outcome is a platform that can legitimately claim enterprise‑grade compliance capabilities, improving competitive advantage and supporting the long‑term subscription revenue goal.

Product overview

See the business owner roadmap: https://raw.githubusercontent.com/scholtz/biatec-tokens/refs/heads/main/business-owner-roadmap.md

Scope

This issue is scoped to the backend API and data layer for compliance reporting, audit trail export, and jurisdiction‑aware compliance status. It does not require a full UI implementation, but it must deliver stable endpoints and data models that the frontend can consume. The work includes data modeling, service logic, API endpoints, and background jobs where necessary, along with a minimal rules engine for jurisdiction tagging.

In scope capabilities:

1. Compliance Report API

   • Create endpoints to generate and retrieve compliance reports for a token, issuer, or issuance event. Reports should summarize MICA readiness, attestation presence, audit trail completeness, and a list of compliance checks with pass/fail status and timestamps.
   • Provide machine‑readable JSON report and downloadable CSV/JSON export formats. A report must have a stable schema version for forward compatibility.

2. Audit Trail Export API

   • Implement an endpoint that returns a normalized audit trail for token issuance, updates, and compliance events. Include event type, actor, timestamp, and associated transaction or attestation IDs.
   • Support pagination and filtering by date range, event type, and token ID. Provide both JSON and CSV export options.

3. Jurisdiction Tagging and Rules

   • Introduce a minimal jurisdiction tagging system for tokens and issuers based on provided metadata (e.g., issuer country, regulatory classification, or explicitly provided jurisdiction label).
   • Implement a rules engine that can map jurisdiction to compliance requirements (e.g., EU MICA baseline) and attach these requirements to compliance report output. Rules should be config‑driven and easy to extend.

4. Compliance Status Aggregation

   • Implement a service that aggregates compliance checks into a single status used by the UI: compliant, partially compliant, non‑compliant, or unknown. Provide rationale fields that list missing items or failed checks.
   • Ensure status recalculation occurs on relevant events (new attestation, audit entry, or token update).

5. Security and Access Control

   • Enforce access control for report and audit exports. Reports should be available to authorized users only (issuer owners or admin roles). Ensure tokens are filtered by permissions.
   • Add rate‑limiting or query restrictions as appropriate to protect large report exports.

6. Observability

   • Include structured logging for report generation and export. Provide metrics hooks if existing observability patterns are present.

Out of scope:

• Full KYC/AML provider integration (should be stubbed for future extension only).
• New frontend UI components (though API contract changes should be documented for frontend consumption).
• Changes to subscription/billing systems.
• Major refactoring unrelated to compliance and audit outputs.

Technical approach and dependencies:

• Reuse existing database or persistence patterns for audit logs and token metadata.
• Use existing API routing and controller conventions in BiatecTokensApi.
• Prefer configuration‑driven rule definitions (e.g., JSON or database seeded table) rather than hard‑coded logic.
• Define a versioned schema for compliance report output. Keep it backward compatible for future extension.
• If background jobs exist for report generation, hook into them; otherwise, implement report generation synchronously with caching as needed.
• Provide clear API documentation or comments in code where the report schema and fields are defined.

Acceptance Criteria

1. Compliance Report Endpoint

   • An API endpoint exists to generate or retrieve compliance reports by token or issuer.
   • The report includes a versioned schema, summary status, list of compliance checks, and timestamps.
   • Report retrieval supports JSON output and optional CSV export.

2. Audit Trail Export Endpoint

   • Audit trail API supports filtering by token ID, date range, and event type.
   • The response is paginated and provides JSON and CSV output options.
   • The audit trail includes at least: event type, actor, timestamp, reference ID, and token ID.

3. Jurisdiction Rules

   • Tokens and issuers can be tagged with a jurisdiction label.
   • Compliance report output references jurisdiction rules and lists required checks.
   • Rules can be updated without code changes (configuration or database‑driven).

4. Compliance Status Aggregation

   • A service aggregates compliance checks into a single status with rationale.
   • Status updates occur when new audit events or attestations are added.
   • The frontend can request status for a token without heavy recomputation.

5. Security

   • Endpoints enforce permissions to prevent unauthorized access to reports or audit exports.
   • Unauthorized access attempts are logged with appropriate error responses.

6. Documentation

   • Inline API documentation or README note describes report schema and usage.
   • A minimal example response is included in documentation to aid frontend integration.

Testing

Testing must align with TDD expectations and ensure the reliability of compliance outputs. At a minimum:

• Unit tests for report generation logic, jurisdiction rules evaluation, compliance status aggregation, and audit event formatting.
• Integration tests for API endpoints, verifying permissions, pagination, filtering, and export formats.
• Contract tests validating that the report schema remains stable and includes required fields. If a schema version is used, tests should assert versioned output.
• Security tests to confirm unauthorized users cannot access compliance reports or audit exports.
• Performance tests (lightweight) to ensure report generation on typical datasets completes within acceptable time thresholds, or verify caching if implemented.
• Manual testing to validate CSV exports and confirm proper encoding, date formatting, and ordering.

Additional context and rationale:

This work is intentionally foundational. The frontend’s compliance badges and readiness signals depend on high‑quality, explainable backend data. If the backend can provide a canonical compliance report, the UI can display badges with confidence and allow users to drill into evidence. It also reduces ambiguity for support and sales: when a customer asks “Why is this token marked as partially compliant?” we can point to a specific report section rather than a vague UI state.

The rules engine should be minimal but extensible. Do not over‑engineer complex regulatory logic; start with a baseline mapping for MICA‑aligned checks and leave space for future FATF and SEC requirements. The goal is to deliver a credible, inspectable compliance status for token issuers and to expose a transparent audit trail that can be shared with regulators or partners. This aligns with the roadmap’s focus on enterprise compliance and the stated gap between current MVP readiness and the compliance needs of target customers.

The final implementation should prioritize clarity, correctness, and predictable API semantics. Favor stability over experimental design. Ensure that compliance report output remains consistent for the same data inputs, and that any changes are versioned so downstream clients can adapt without breaking.