[5a] Compliance Reporting Engine — SAT/UIF Monthly Aggregation

[grantfox-oss]

Context

LFPIORPI post-reform requires monthly notices to SAT/UIF (day 17), including "zero reports" when nothing is reportable, plus a 24-hour alert window for unusual operations. None of this exists yet. Issue #314 ("[4a] Tiered KYC Gate Engine") gives us the raw material (the kyc_gate.decision audit trail, tiered operation records) but nothing aggregates or reports on it.

What this issue proposes

Build the periodic aggregation and reporting layer on top of #314's audit trail, decoupled from how a user got their tier (Etherfuse, Didit, or any future provider — see the Didit integration issue, #315).

Monthly aggregation & SAT filing

• Scheduled job (day 17 monthly) aggregates operations ≥ 210 UMA per user from the audit trail / trade records
• Generates the SAT-required output format for reportable operations
• Generates a "zero report" automatically when nothing is reportable that period (actual submission stays manual — see Out of scope)
• Threshold (210 UMA) read from the same config [4a] Tiered KYC Gate Engine + Operation-Level Audit Trail #314 established — not hardcoded

Unusual-operation alerting

• Provides a compliance_alerts table and a query/admin endpoint that exposes each entry's 24-hour SLA deadline (an admin UI is out of scope — this issue is backend-only)
• Any source (a rule engine, manual review, or [4a] Tiered KYC Gate Engine + Operation-Level Audit Trail #314's own gate block/downgrade decisions) can insert into this table — this issue owns the alert pipeline, not the detection rules themselves
• Detection rules (structuring/velocity/geography) are a separate, later issue that writes into this table

Audit retention

• Audit records (and any new reporting tables) enforce no-delete / no-update at the DB layer (append-only already required by [4a] Tiered KYC Gate Engine + Operation-Level Audit Trail #314) and are covered by encrypted backups
• Document the 10-year retention requirement in the migration/README so it isn't accidentally shortened by a future cleanup job

Acceptance criteria

• Monthly job aggregates ≥210-UMA operations per user, config-driven threshold
• SAT report output generated in the required format; zero-report path when nothing reportable
• compliance_alerts table exists with a documented insert contract; each entry's 24h SLA deadline is exposed by the query endpoint
• Query/admin endpoint to review pending and past filings/alerts
• No new mutation path allows editing/deleting past audit, report, or alert records
• Retention policy documented (10 years, encrypted at rest)
• Unit tests for aggregation logic (reportable, zero-report, threshold edge cases)
• Integration test for the scheduled job end to end
• tsc --noEmit / backend build passes

Out of scope

• Anomaly/structuring detection rules themselves (future issue: automated screening)
• Actual SAT/UIF submission channel (manual filing by a compliance officer is fine for v1 — this issue produces the file/report, not the submission)
• OFAC/PEP list screening (future issue: automated screening)

Related

• Depends on: [4a] Tiered KYC Gate Engine + Operation-Level Audit Trail #314 (needs the gate's audit trail / tier-gated operation records to aggregate) — merged; see kyc-gate.service.ts's getKycAuditTrail for the query pattern already in place
• Independent of: the Didit provider-integration issue ([4b] KYC Provider Integration — Didit for Level 1/2 Verification #315) — this issue doesn't care which provider verified the user, only their tier and operations
• The automated-screening issue depends on this one (it writes into compliance_alerts)
• Compliance context: docs/KYC_COMPLIANCE_PLAN_2026-07.md, Fase 3 / Option C items 3 and 5

[codewithzubair07]

i would like to work on this issue

[ShantelPeters]

I have experience building backend services with TypeScript and JavaScript, and I’m comfortable working with scheduled jobs, data aggregation, API integrations, and reporting workflows. I understand the importance of keeping the reporting layer independent from the KYC provider while relying on the audit trail as the single source of truth.

For this task, I’ll implement the monthly aggregation job, generate the required SAT/UIF reporting output, support zero-report generation when appropriate, and ensure the reporting pipeline is modular, maintainable, and well-tested. I’ll also follow the existing project conventions and provide clear documentation throughout the implementation.

Looking forward to contributing to this issue.

[grantfox-oss]

🦊 GrantFox — @ShantelPeters has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #317)
2. Your PR will be reviewed by the Micopay maintainers

Good luck! Track your progress on GrantFox.