Skip to main content

Comprehensive feature inventory

Every capability the platform exposes today. Grouped by domain. Each feature links to the relevant endpoints in the API Reference so you can go from "what does this do" to "how do I call it" in one click.

Totals: 65 modules, 380 endpoints, 251 permissions, 8 default roles, 151 typed request/response schemas.

Identity, access & security​

Enterprise-grade identity for a Ugandan financial-services platform — JWT + refresh, MFA, WebAuthn passkeys, granular RBAC, tamper-evident audit.

  • JWT authentication with rotating access + refresh token families. Login, refresh, logout-all, password change, forgot/reset flows. Reference: /docs/api/auth-controller-login.
  • Multi-factor authentication (TOTP) with QR-code enrolment, challenge/response verify, and per-user MFA reset by admins.
  • WebAuthn / passkeys — hardware-key second factor. Registration options + verify + authentication options + verify. Enumeration-safe. Reference: /docs/api/passkeys-controller-registration-options.
  • Fine-grained RBAC — 251 hardcoded permissions, 8 seeded roles, and arbitrary custom roles. Every endpoint declares its guard via @RequirePermissions / @RequireAnyPermission / @RequireRoles; a build-time lint fails CI on any unguarded handler.
  • Object-level scoping — agents automatically see only their own referrals, commissions, wallet, and investments via ObjectAuthorizationService.
  • Programmatic API keys — per-key permissions, TTL, IP allow-list, rate limit, and revocation. Reference: /docs/api/api-keys-controller-list.
  • Client-portal magic-link / OTP — separate ClientPortalSession for end-clients who don't have platform accounts (view their own policies and claims). Session tokens are distinct from platform JWTs.
  • Hash-chained audit trail — every state change writes an audit_event carrying previousHash, currentHash, chainSeq. A nightly verifier walks the chain; a mismatched hash pages compliance.
  • Security events — separate stream for login failures, MFA challenges, suspicious IP transitions, session hijack heuristics.
  • Session management — list active sessions per user, revoke one or all.

Agent lifecycle​

The whole introducer / licensed-agent onboarding pipeline, tied to the IRA of Uganda register.

  • IRA Registry pre-check — public GET /public/ira-registry/:iraNumber lookup against the seeded IRA of Uganda register (2,594 licensed agents from the 30 June 2026 publication). Used by the self-registration UI to pre-fill licence data. Rate-limited to 30/min/IP.
  • Public self-registration — introducers can self-register with a sponsor code; licensed agents self-register with their IRA number. Every registration lands as pending. Rate-limit: 3/5min/IP.
  • Staff-created agents — POST /agents for ZFA-side creation.
  • KYC dossier upload — per-agent-type mandatory document sets; per-document review + verify workflow. Verified KYC unlocks approval.
  • Approve / reject / suspend / blacklist — full state machine with audit events on every transition.
  • Agent licences — CRUD for the agent-licence sub-resource, expiry tracking, licence renewal reminders.
  • Sponsor / introducer relationships — licensed agents can sponsor introducers; sponsor sees all downstream referrals for "book of business" management.
  • Agent statements — periodic P&L statement generation per agent.

Insurers & products​

Catalogue of insurance carriers, their product lines, and the underwriting rules.

  • Insurer directory — 27 Ugandan insurers seeded. CRUD, activate, suspend. POST /insurers/:id/activate gates whether the insurer can accept referrals.
  • Insurer contacts and integration endpoints — per-insurer contact book and webhook / SFTP / email delivery configuration.
  • Product categories — top-level product taxonomy (health, motor, marine, business, etc.).
  • Insurer products — carrier-specific products under each category, each activatable.
  • Product plans — versioned plans under a product, each with pricing bands.
  • Underwriting rules — declarative rule engine for accept/refer/reject decisions based on age, coverage, geography, prior claims.

Referrals & policies​

The core business flow — introducer captures a lead, licensed agent converts it, insurer issues a policy, commission is calculated, wallet is credited.

  • Referrals (9-state workflow) — draft → submitted → assigned → in_review → sent_to_insurer → quotation_shared → client_accepted → premium_confirmed → policy_issued. Plus rejected, cancelled, disputed. Reference: /docs/api/referrals-controller-create.
  • Idempotent create — Idempotency-Key header dedupes replays inside a 24-hour window.
  • Auto-generated referenceNumber — human-readable REF-YY-XXXXXXXXX used in all correspondence.
  • Client PII encryption at rest — PiiCipher encrypts email/phone/national ID; PiiCipherHmac produces search hashes so you can filter without decryption. clientEmailHash, clientPhoneHash, clientNationalIdHash are populated automatically.
  • Client consent recording — clientConsentAt + clientConsentEvidenceId for a document capturing the client's consent.
  • Attach documents to a referral.
  • Referral timeline — full history of every state change with the actor + timestamp.
  • Quotations — insurer quotation capture, share with client, expire.
  • Policies — issued policies with the full lifecycle.
  • Policy endorsements — mid-term amendments requiring underwriter approval.
  • Policy cancellation with pro-rata premium refund.
  • Policy reinstatement on lapse.
  • Renewals — sweeps at 60/30/7 days-to-expiry; generate renewal offer, convert accepted offer to a policy on the next term.
  • Communications — per-policy timeline of every SMS / email / letter sent to the client.
  • Leads — inbound public lead form and staff-side lead assign / convert / dismiss.
  • Disputes — client-raised or agent-raised disputes on referrals with triage → resolve workflow.

Commissions, wallets & payouts​

Where money moves. All numeric operations use decimals, not floats.

  • Commission rules — versioned, activatable rules mapping (insurer, product, agent tier) to a commission rate. POST /commission-rules/simulate previews the effective rate for a given referral shape.
  • Commissions ledger — every referral produces a commission row. Recalculate, approve, adjust, reverse, dispute.
  • Deduction engine — ZFA-configurable fees, taxes and levies. Seeded: 5% ZFA fee, 6% URA withholding tax, UGX 500 IIU membership (min gross UGX 10,000). Priority-ordered — tax after fee taxes the post-fee value. POST /deduction-types/preview previews a specific gross amount.
  • Agent wallets — one wallet per licensed agent, credited net of active deductions when a commission is approved. Full ledger of every transaction.
  • Multi-currency + FX — UGX, USD, EUR, GBP, KES supported. fx_rates table drives conversion; admins publish rates.
  • Payout accounts — bank + mobile money accounts registered against a wallet, each verified before it can receive a payout.
  • Wallet withdrawals — user-initiated withdrawal request, admin approval, then paid out via PaymentBatch.
  • Payment batches — group payouts into a submission to a payment provider (Flutterwave / Pesapal / etc.). Approve → submit → gateway callback → settle.
  • Invoices & receipts — full billing sub-system for subscriptions (see below), including issue, record-payment, write-off, cancel.
  • Payment provider webhooks — HMAC-signature verified inbound webhook ingestion at POST /payment-webhooks/{provider}. Idempotency by (provider, eventId).

Investments​

Wallet balances can be locked into fixed-term or call investments that compound daily.

  • Investment products — admin-defined tenor, rate, minimum amount, compounding frequency. 4 seeded defaults.
  • Investments — agent-initiated, admin-approved. Fixed-term investments are locked until maturity; call investments are redeemable on demand with a penalty rate.
  • Daily compounding — nightly cron accrues interest, updates currentValue.
  • Redemption — early redemption (with penalty) or maturity redemption (credits the wallet with principal + accrued interest).
  • Administrative controls — pause, cancel, adjust investments.

Subscriptions & billing​

Optional recurring subscriptions for premium tiers.

  • Subscription plans — admin-defined pricing plans.
  • Agent subscriptions — enrol an agent, renew, cancel.
  • Automatic invoice generation on billing cycle.
  • Dunning workflow on failed payments.

Claims​

End-to-end claim lifecycle for issued policies.

  • File a claim as an agent or client.
  • 9-state workflow — filed → triaged → assigned → investigating → settled | repudiated | withdrawn | appealed.
  • Documents & notes attached to any claim.
  • Investigator assignment and case-worker workload views.
  • Settlement — records payout amount + method; triggers wallet transaction if the payout goes through the platform.
  • Repudiation — records grounds + evidence.
  • Client appeal — clients can appeal a repudiated claim via the client portal.

Compliance, sanctions & fraud​

Built for a regulated financial platform in Uganda.

  • DSAR — GDPR-adjacent data-subject access requests. Export a subject's data or execute right-to-erase.
  • Regulator reports — aggregate reporting (agent counts, product mix, insurer summaries) with a regulator-scoped role.
  • Regulator record requests — request → fulfil / deny workflow for IRA / URA record subpoenas.
  • Sanctions screening (OFAC-style) — every referral is screened against a sanctions & PEP list at creation time.
  • Fraud rule engine — declarative rules over referral / claim patterns. Rules produce fraud alerts; triage → resolve workflow.
  • Bordereau (insurer reporting) — periodic bordereau generation, share with insurer, reconcile, dispute.
  • Compliance cases — investigations across audit events, security events, and fraud alerts.

Communications​

  • Notification templates — 8 seeded (referral submitted, KYC verified, commission approved, etc.). Variables substituted at send time.
  • Multi-channel dispatch — SMS + email + in-app. Templates specify which channels apply.
  • Per-user preferences — opt in / out per channel per category.
  • Client portal — magic-link login flow (OTP request → OTP verify → session token) so clients can view their own policies and claims without a full account.

Content & configuration​

  • Content assets — versioned publication of Terms of Service, Privacy Policy, Data Protection, KYC requirements docs, etc. Public GET /public/content/{code}/in-force returns the version in force at a given point in time.
  • Operational policies — 15 seeded ZFA-configurable policies: password requirements, session timeouts, MFA requirements, KYC validity, retention windows, etc.
  • ID patterns — 7 seeded reference-generation patterns (national ID, IRA licence number, business registration, tax PIN, InsureLink agency number, etc.). Used across DTOs for validation.

Integrations​

  • Insurer inbound webhooks — HMAC-verified ingestion of policy / claim events from insurer systems. Signature mismatch is logged as a security event and rejected.
  • Insurer outbound integrations — per-insurer webhook / SFTP / email delivery of referrals, bordereau, and claim events.
  • Payment provider integrations — Flutterwave, Pesapal, Bank of Uganda RTGS, and mobile money (MTN, Airtel) via a common PaymentProvider interface.
  • SIEM export — HMAC-signed cursor-based push of audit and security events to your SIEM.
  • Warehouse export — Postgres → BigQuery / Snowflake export runner.

Reporting​

  • Standard reports — agent, referral pipeline, insurer performance, product performance, commission, payment reconciliation, audit events.
  • CSV / XLSX / PDF export — every report can be exported.
  • Regulator aggregates — separate report-set scoped to a regulator role.

Support​

  • Support tickets — customer support ticketing with assign, reply, resolve. Agents can raise tickets from the client portal.
  • Cross-entity search — a single endpoint that federates search across agents, referrals, policies, claims, and clients. Powered by trigram indexes on PII search hashes.

Documents​

  • Object storage — PUT /documents/:id/blob and GET .../blob back storage of KYC dossiers, claim evidence, policy schedules. Supports S3 and local disk (configurable per environment).
  • Metadata & tagging — document type, subject entity, uploader, retention window.
  • Retention & deletion — driven by operational policy; documents past retention window are auto-deleted with an audit record.

Ratings​

  • Product & insurer ratings — end-clients rate insurers post-claim; admins can moderate abusive reviews.

Platform infrastructure​

  • Health probes — /health, /health/live, /health/ready. Ready probe tests the DB connection.
  • System info — /system/info returns the running commit, env, release timestamp.
  • Scheduled jobs — cron-triggered jobs (renewal sweeps, daily interest accrual, audit-chain verifier, deferred payment retry).
  • Job scheduler admin — pause, resume, run-now.
  • Global rate limiting — 120/min/IP default, per-endpoint tighter limits on auth flows, OTP, self-register, IRA lookup, and public leads.
  • Idempotency middleware — Idempotency-Key header supported on POST /referrals, wallet withdrawals, payment batches, and inbound webhooks.
  • Structured logging — every request gets req_<uuid> returned in meta.requestId for cross-log correlation.
  • Response envelope — { data, meta } on success, { error } on failure; error.code is a stable machine-readable string.

Where next​

  • Prefer to explore by endpoint? All endpoints has the clickable matrix (public / restricted / client-session, per-permission).
  • Want to try a real request? The Sandbox has a KYC-verified demo agent and 3 active insurer/product pairs ready.
  • Need to onboard a new insurer or agent operationally? See the runbooks.