Real-time analytics & BI platform (aggregation engine, trends, drill-down, alerts, exports) — full-stack EPIC

[grantfox-oss]

DESCRIPTION

The TSE and parties have no analytical view of the bond ecosystem — no metrics, trends, breakdowns, drill-downs, or exports. This epic builds a real-time analytics & business-intelligence platform (full-stack): a pure aggregation engine over bonds/transfers/reports, time-series and trend analysis, per-country/per-party breakdowns with drill-down, configurable dashboards with saved views, threshold alerting, scheduled report generation, and CSV/PDF exports — with RBAC and a dense, accessible dashboard UI. Everything is verifiable locally with fixtures/mocks — no VELAR database, secrets, or external APIs required.

GOAL

Authorized users get an interactive BI dashboard: KPIs, many chart types, time-series trends, per-party/per-country breakdowns with drill-down, saved views, threshold alerts, and exports — all computed by pure, fixture-tested aggregation functions.

REQUIREMENTS

Aggregation engine (apps/api/src/analytics/)

• A comprehensive aggregation engine as PURE functions over bonds/transfers/reports (fixture-fed): totals by status (emitido/activo/en_escrow/transferido/...), breakdowns by party and by country, transfer funnel/conversion, time-series (issuance, transfers, escrow throughput) with configurable bucketing, compliance metrics (from reports), and value/volume aggregates. Deterministic and exhaustively unit-tested.
• Trend/analysis helpers: period-over-period deltas, moving averages, top-N, and simple anomaly/threshold detection.
• Endpoints (guarded, TSE/admin + party-scoped variants where relevant); controller fetches via SupabaseService (mocked in tests) and delegates to the pure engine. Add analytics/query/result types to @velar/types. Optionally a pre-aggregation/materialized-view migration FILE for performance (append-only).

Alerting & scheduled reports

• Threshold alerting (rules over metrics) that emits notifications when breached (via the notifications module; mocked in tests).
• Scheduled report generation hook (interface + stub) that produces periodic CSV/PDF summaries — no external scheduler/vendor required to test.

Frontend (apps/web/app/tse/analytics/, party dashboards)

• A BI dashboard: KPI cards, multiple chart types (bar/line/area/pie/stacked), a filter bar (date range, country, party, status), drill-down from a chart into the underlying set, saved views, and CSV/PDF export. Light-weight, license-clean charting.
• RBAC-aware (TSE/admin vs party sees only its own). Localized, responsive, and accessible (chart text/table fallbacks, aria, keyboard). Empty/loading/error states; no service_role key or secret in the client.

ACCEPTANCE CRITERIA

• Pure-engine unit tests over fixtures assert correct totals, breakdowns, funnels, time-series buckets, trend deltas/moving-averages/top-N, and threshold detection — including edge cases (empty, single item, sparse periods).
• Backend tests (mocked SupabaseService/notifications) prove RBAC/party-scoping, typed responses, alert emission on breach, and the scheduled-report stub.
• CSV/PDF exports are deterministic from fixtures and unit-tested.
• Frontend (fixtures): dashboard renders KPIs + charts, filters + drill-down + saved views work, exports produce files, and RBAC hides/shows the right data.
• New types exported from packages/types; any migration present + append-only.
• npm run build, npm run lint, npm run test pass in apps/api and apps/web with NO VELAR credentials.
• Docs updated (docs/BACKEND.md, docs/FRONTEND_GUIDE.md).

NOTES

Relevant files: apps/api/src/analytics/, apps/api/src/notifications/notifications.service.ts, apps/api/src/common/supabase/supabase.service.ts, apps/web/app/tse/analytics/, apps/web/app/partido/, apps/web/components/, apps/web/lib/, packages/types/src/index.ts, supabase/migrations/. Bond/transfer state values come from docs/AGENTS.md §4. Keep aggregation logic pure and fixture-tested so it needs no live data. Authorization is backend-owned (docs/AGENTS.md §5).

No VELAR credentials required: verifiable locally with fixtures/mocks — do NOT use VELAR's database, passwords, service_role, or any external API/provider key.

Difficulty: Expert / Epic (very heavy, full-stack, many subsystems)
Priority: High

CAMPAIGN REQUIREMENTS (FWC26)

To be eligible for the reward on this issue, the contributor must:

• Follow Velar on X: https://x.com/VelarApp
• Star the repository: https://github.com/Velar-Bonds/Velar
• Follow the Velar-Bonds organization on GitHub: https://github.com/Velar-Bonds

[KevinLatino]

My name is Kevin Latino. I am a Software Engineer with 3 years of experience building scalable web applications and software systems. I have experience across the full stack, with a strong interest in backend engineering, APIs, and developing robust, maintainable solutions. I enjoy working on challenging technical problems and delivering high-quality software.

[grantfox-oss]

🦊 GrantFox — @KevinLatino 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 #44)
2. Your PR will be reviewed by the Velar-Bonds maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@KevinLatino's PR #70 was approved and merged by @josueazc.

🏆 @KevinLatino: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (96 total points). Track your full progress on GrantFox.

👏 Great work, @KevinLatino! Keep contributing to Velar-Bonds.