ZFA-direct channel
Design for the second business flow where a client contacts ZFA directly for insurance services, bypassing the agent leg entirely.
Auth / RBAC / MFA
Feature reference for the auth surface — email + password login, session + refresh-token lifecycle, TOTP MFA, forgot / reset / change password, step-up flow. Reviewed against DPPA 2019 §21 (Argon2id at rest, key isolation), §17 (subject-erasure cascade to sessions + reset tokens + MFA secrets), AML §14 (audit trail on login / logout / password / MFA / step-up), NIST SP 800-63B (session lifecycle, TOTP AAL2, replay + reuse detection, password-history reuse guard), BOU cybersecurity §5.4 (throttle + failed-attempt back-pressure + rotation ledger). Sibling authenticator surfaces reviewed separately: identity-credentials (credential rotation), passkeys (WebAuthn AAL2), api-keys (partner tokens).
Auth security runbook
Operational procedures for JWT key rotation, incident response (leaked JWT secret, compromised admin account, refresh-token theft), and step-up MFA. Companion to auth-security-review.md.
KYC / Identity / AML
Feature reference for the agent-KYC + agent-license surface — CDD document collection, verification, license expiry, periodic KYC refresh. Reviewed against AML 2013 §6 (CDD), §17 (periodic refresh + license expiry), §14 (audit trail), IRA §17 (agent licensing), DPPA 2019 §21 (NIN + license document encryption), §11 (KYC doc retention past 7 y), BOU cybersecurity §5.4 (throttle + per-entity ceilings + audit).
Sanctions / Fraud
Feature reference for the joint sanctions + fraud surface — subject screening on onboarding + payout, provider registry, webhook ingress, fraud-rule engine, alert lifecycle, STR promotion path. Reviewed against AML 2013 §6 (CDD at intake), §17 (ongoing due-diligence), §14 (audit trail), DPPA 2019 §21 (PII in hit metadata + fraud evidence), §11 (retention past 7 y), §16 (cross-border consent), BOU cybersecurity §5.4 (throttle + provider circuit-breaker + rotation ledger), FATF Recommendation 6 (UN sanctions / PEP / sectoral / STR filing).
Referrals
Feature reference for the referrals surface — agent submits a referral, ZFA reviews, insurer quotes, client accepts, premium is paid, POP verified, policy issued, commission approved, payout. 20-state machine with immutable status history. Reviewed against AML 2013 §6 (CDD at intake), §14 (audit on every transition), IRA §12 (product filing validity), CPA §37 (pre-issuance disclosure + commission transparency), DPPA 2019 §13 (client consent capture BEFORE processing), §21 (client PII cipher on name / phone / email / NIN), §17 (subject-erasure cascade to referral rows).
Policies / Quotations / POP
Feature reference for the policy-issuance cluster — quotation, POP, policy issue / amend (endorsement) / cancel / reinstate / lapse. Reviewed against IRA §12 (product filing validity at issue AND amend), Insurance Act §31 (30-d non-renewal notice) + §78 (statutory notices) + §48 (endorsement categorisation), CPA 2022 §37 (pre-issuance disclosure + cooling-off + policy schedule + T&Cs), DPPA 2019 §21 (policy narrative + applicant PII masking on read), §11 (7-y retention past terminal event), AML §14 (audit on issue / amend / cancel / reinstate + sanctions rescreen on endorsement).
Claims
Feature reference for the claims surface — file, acknowledge, investigate, settle / repudiate, disburse, appeal. Reviewed against Insurance Act 2017 §138 (5-day acknowledge + 30-day decide + 15-day-post-decision pay), CPA 2022 §37 (consumer notice + plain-language repudiation), DPPA 2019 §21 (PII in narrative + supporting docs at rest), §11 (retention of closed claims), §17 (subject-erasure cascade), AML §14 + §17 (audit trail on every transition + sanctions rescreen on payout), IRA IT Controls (four-eyes on high-value payouts + segregation of duties), and BOU cybersecurity §5.4 (throttle + audit on file / decide / pay endpoints).
Commissions / Wallets
Feature reference for the commissions + wallets + deductions joint surface — agent commission accrual, wallet ledger, deduction rule engine, WHT / VAT tax payables. Reviewed against AML 2013 §14 (audit trail on every ledger movement), IRA agent-commission rules + §112 (deduction cap enforcement), URA §116 (WHT on interest / agent-fee payouts) + §80 (tax-payable atomicity), DPPA 2019 §21 (agent PII in transaction descriptions), §11 (retention past 7 y), BOU cybersecurity §5.4 (ledger-invariant enforcement + rotation ledger), IRA IT Controls §3.2 (segregation-of-duties on ledger writes).
Payment gateway
Feature reference for the payment-gateway surface — payment batches, provider registry (mobile money + bank + Flutterwave + Airtel + MTN), webhook ingestion, wallet-withdrawal path. Reviewed against PCI-DSS adjacency (no PAN on server), AML 2013 §6 (sanctions rescreen on every payout), §17 (ongoing due-diligence), §14 (audit trail on debit/credit), DPPA 2019 §21 (PII at rest on payer/payee), §11 (retention past 7 y), BOU cybersecurity §5.4 (throttle + provider circuit-breaker + rotation ledger), IRA IT Controls (four-eyes on above-threshold payouts + segregation of duties).
Collections
Feature reference for the collections surface — MTN MoMo / Airtel Money / Flutterwave / Pesapal request-to-pay + bank-statement reconciliation + webhook ingest. Reviewed against AML 2013 §6 (sanctions on payer + CTR/STR at high-value thresholds), §14 (audit trail on every credit), DPPA 2019 §21 (payer PII at rest), §11 (retention past 7 y), BOU cybersecurity §5.4 (throttle + provider circuit-breaker + reconciliation SLA), URA §41 (VAT invoice on collection), IRA (premium-in receipt tracking).
Insurer webhooks
Feature reference for the insurer webhook + integration-settings surface. Covers inbound event ingest (quotation, policy, claim), HMAC signature verification, replay protection, idempotency, state-machine routing, and per-insurer secret rotation. Aligned to Insurance Act 2017 §128 statutory returns, DPPA 2019 §21 shared-secret safeguards, BOU Cybersecurity Guidelines §5.4 integration monitoring, and NPS Act 2020 §36 payment-system agent obligations.
Investments
Feature reference for the agent investment surface (fixed-term + call deposits with daily interest accrual) and the claims-side reserve trail. Covers URA Income Tax Act §116 (WHT on interest), Financial Institutions Act 2004 (deposit-taking authorisation), Consumer Protection Act 2011 §37 (cooling-off), IRA Insurance Act §100 (prescribed investments + reserve reporting), DPPA 2019 §21 (agent financial data at rest), BOU Cybersecurity Guidelines (financial-ledger integrity).
Subscriptions & billing
Feature reference for the agent-facing SaaS billing surface. Covers SubscriptionPlan + AgentSubscription lifecycle, Invoice + Receipt double-entry, DunningEvent ladder, and VAT + WHT recognition against URA Income Tax Act §80 (VAT), Tax Procedures Act §39 (sequential invoicing), Consumer Protection Act §37 (cooling-off), AML Act §6 (screening on inbound payments), and DPPA §21 (agent financial data at rest).
Documents / Storage
Feature reference for the documents surface — upload with malware scan, at-rest encryption, signed URL issuance, download access log, retention purge. Reviewed against DPPA 2019 §21 (blob encryption at rest), §11 (7-y retention past terminal policy/claim link), AML 2013 §14 (audit on upload / download / signed-url / purge), CPA 2022 §37 (integrity of consumer-facing docs), BOU cybersecurity §5.4 (malware scan + throttle + scanner TLS).
Notifications / Comms
Feature reference for the dispatch infrastructure — Africa's Talking SMS, WhatsApp Cloud, SMTP + console providers, BullMQ queue, cross-channel rate limiter, provider webhooks, communications timeline. Complements the notification-templates + notification-preferences reviews (both already closed). Reviewed against DPPA 2019 §16 (cross-border via SMS/WhatsApp — already gated), §21 (rendered PII at rest via NOTIFICATION_BODY_KEY + key-version tracking), AML §14 (send-log + provider-webhook audit), BOU cybersecurity §5.4 (provider circuit-breaker + throttle + queue back-pressure + graceful degradation).
DSAR
Feature reference for the DSAR surface — subject-access, rectification, erasure, portability, objection under DPPA 2019 §17 (statutory 30-day response), §11 (retention of DSAR artefacts), §16 (cross-border transfer disclosure), §20 (objection right), AML §14 (audit trail on request lifecycle), BOU cybersecurity §5.4 (throttle on public request submission), NIST SP 800-63B (subject verification before irreversible erasure).
Complaints / SARs / Breaches
Feature reference for the consumer-complaints + suspicious-activity-report + data-breach lifecycles — intake, SLA escalation, MLRO review, goAML XML, breach notification, postmortem. Reviewed against CPA 2022 §37 (5-day acknowledgement + 30-day resolution), Insurance Act §138 (IRA complaints register), FIA / goAML (SAR narrative fidelity), DPPA 2019 §17 (72-h breach notification + subject notification), AML 2013 §13 / §17 (STR / SAR reporting), BOU cybersecurity §7 (incident-response postmortem).
Bordereau / Warehouse
Feature reference for the joint bordereau + warehouse-export surface — periodic insurer bordereau generation + delivery + reconciliation, plus warehouse export to analytics/BI targets. Reviewed against IRA §64 (bordereau filing SLA + §132 delivery evidence), CPA §37 (aggregate consumer data disclosure), DPPA 2019 §16 (cross-border export consent), §21 (PII masking on export), §11 (retention of export artefacts), AML §14 (audit trail on every export), BOU cybersecurity §5.4 (throttle + audit).
Audit / SIEM
Feature reference for the audit-chain + SIEM export + compliance surface — hash-chained AuditEvent, SIEM push with mTLS, DPPA §17 audit-erase with legal justification, SAR / breach / postmortem lifecycle. Reviewed against AML 2013 §14 (immutable 7-y chain), DPPA 2019 §17 (audit-erase with legal-hold reference), §21 (PII redaction on SIEM egress), BOU cybersecurity §5.4 (SIEM host allowlist + mTLS + receiver confirmation), FIA / goAML (SAR narrative fidelity).
Regulator reports & requests
Feature reference for the outbound regulator-reporting surface (FIA goAML CTR/STR, IRA quarterly returns, URA VAT + WHT remittance) plus the inbound `RegulatorRecordRequest` lifecycle. Reviewed against AML Act 2013 §6 + §12, IRA Insurance Act 2017 §102 + §112, URA Income Tax Act §80 + Tax Procedures Act 2014 §41, and DPPA 2019 §11 + §21.
Underwriting lifecycle
Feature reference for the quote-to-decision insurance lifecycle. Covers Quotation (shopping + acceptance), Rating (feedback + placeholder for rating-factor logging), and Underwriting (rule-based accept / decline / refer). Reviewed against IRA Insurance Act 2017 §35 (underwriting standards) + §36 (fair pricing / anti-discrimination), CPA 2011 §37 (cooling-off), AML Act 2013 §6 (CDD at policy issuance), and DPPA 2019 §11 (automated-decision transparency + explainability).
Renewals
Feature reference for the policy-renewal surface. Covers `RenewalQuote` lifecycle, auto-renewal consent capture, non-renewal notice (Insurance Act 2017 §31), cooling-off on renewal (CPA 2011 §37), AML §6 CDD at rebind, and DPPA §11 automated-decision transparency.
Agent lifecycle
Feature reference for the agent-lifecycle surface. Covers `Agent` onboarding + activation + suspension + blacklist, `AgentLicense` IRA-licence registration + expiry, and `AgentKycDocument` KYC dossier + verification. Reviewed against IRA Insurance Act 2017 §17 (valid licence to intermediate) + §18 (code of conduct) + §19 (grounds for licence cancellation), AML Act 2013 §6 (CDD on intermediary), and DPPA 2019 §11 (PII storage limitation) + §17 (right to erasure).
Identity & credentials
Feature reference for the identity + credentials surface — `User` lifecycle, `Role` + `Permission` grants, `ApiKey` issue / rotate / revoke, `Passkey` WebAuthn enrolment, and the `SecretRotation` metadata ledger. Reviewed against DPPA 2019 §11 + §17, BOU Cybersecurity Guidelines §5 + §7.4, NIST SP 800-63B AAL2, OWASP ASVS Level 2, and IRA IT Controls Guidance §4 (access revocation on termination). Complements — doesn't duplicate — the auth-security review which covered the auth *flow* (login, MFA challenge, session).
Insurer & product catalogue
Feature reference for the insurer + product-catalogue surface — `Insurer` lifecycle, `InsurerProduct` filing, `InsurerSubresource` (contact + integration settings), `ProductCategory` taxonomy, `ProductPlan` (with `ProductPlanVersion` rate-card snapshots), and the `IraLicensedAgent` IRA-registry lookup. Reviewed against IRA Insurance Act 2017 §12 (product approval + insurer licensing), §35 (rate-card filing), §102 (quarterly returns), AML Act 2013 §6 (CDD on counterparty), and DPPA 2019 §21 (insurer-contact PII). Complements — doesn't duplicate — the insurer-webhooks review which covered the *inbound* webhook surface.
Client Portal
Feature reference for the client-facing portal surface — OTP login, session lifecycle with UA / country drift detection, self-service policy list + profile + DSAR intake. Reviewed against DPPA 2019 §11 (client access to own data), §13 (marketing-consent gate + version proof), §17 (client-initiated DSAR + revocable session), §21 (session / OTP encryption), CPA 2022 §37 (pre-issuance disclosure + policy schedule + T&Cs viewable), BOU cybersecurity §5.4 (OTP throttle + session TTL + step-up + drift response), AML 2013 §14 (audit on login + document access + drift + consent change), IRA (endorsement history readable by insured).
Clients
Feature reference for the client-subject surface — Client CRUD, KYC tier tracking, consent capture, duplicate merge. Distinct from client-portal (self-service surface — separately audited). Reviewed against DPPA 2019 §11 (subject PII storage-limitation), §13 (consent evidence at capture), §17 (subject erasure cascade), §21 (name / phone / email / NIN cipher at rest), AML 2013 §6 (CDD at first-touch) + §17 (periodic refresh), CPA 2022 §37 (disclosure at data capture), BOU cybersecurity §5.4 (throttle + PII-read audit), IRA (identifiability before policy issuance).
NIRA
Feature reference for the NIRA integration — statutory identity verification of subjects (clients / agents) against the Uganda National Identification and Registration Authority. Reviewed against AML 2013 §6 (identity verification at CDD onboarding) + §17 (periodic refresh), DPPA 2019 §11 (retention of NIRA verification records past 7-y AML floor), §13 (subject consent to identity check), §16 (cross-border transit), §21 (NIN + returned identity payload at rest), IRA §12 / §17 (identifiability of policyholder + agent), BOU cybersecurity §5.4 (throttle NIRA lookups + circuit breaker + rotation ledger for NIRA API key), FATF Rec 10 (verify + risk-based EDD re-verify).
Disputes
Feature reference for the disputes surface — the central `Dispute` + `DisputeNote` lifecycle covering referral, commission, payment, and claim disputes. Reviewed against IRA Insurance Act 2017 §129 (dispute-resolution SLA + regulator escalation), CPA 2022 §37-39 (consumer dispute rights, notice, cooling-off), AML Act 2013 §13 (CDD on money-affecting workflows), and DPPA 2019 §11 (retention) + §21 (minimisation) on the free-text reason/note/resolutionNote columns.
Payout accounts
Feature reference for the payout-accounts surface — every agent's bank + mobile-money destination for commission payouts, wallet withdrawals, and claim disbursements. Reviewed against AML Act 2013 §6 (CDD on payment counterparty) + §17 (payment-operator screening duty), NPS Act 2020 (Bank of Uganda payments framework, internal-control + payment-accuracy obligations), IRA §102 (commission-payout audit traceability), and DPPA 2019 §21 (PII minimisation) + §11 (retention) on the account number + account holder fields.
Secret rotations
Feature reference for the secret-rotations surface — the platform-wide ledger of encryption keys, webhook secrets, provider tokens, and API credentials that need periodic rotation. Reviewed against BOU cybersecurity framework §7 (90-day crypto rotation + audit trail), DPPA 2019 §22 (secure processing of PII, including key management), AML Act 2013 §14 (record integrity), and ISO 27001 / PCI-DSS-aligned secret-management practices.
Support tickets
Feature reference for the support-tickets surface — the client-facing generic-issue lifecycle that sits alongside complaints and disputes. Reviewed against CPA 2022 §37 (consumer notice + resolution SLA + reconsideration right), IRA §129 (dispute-adjacent handling + graduation), DPPA 2019 §11 + §21 (retention + PII minimisation on free-text `subject` / `body` / `message.body`), AML Act 2013 §13 (CDD on raiser if ticket resolution triggers money movement), and BOU cybersecurity §5.4 (throttle + audit trail).
Organizations
Feature reference for the organizations surface — the top-of-tenancy `Organization` model that carries brokerage / agency / partner / ZFA-internal entities, their parent-child hierarchy, and their contact PII. Reviewed against IRA Insurance Act 2017 §12 (licensed-entity registration + uniqueness), AML Act 2013 §6 (CDD on organization onboarding), DPPA 2019 §16 (cross-org data isolation) + §21 (PII minimisation on contact fields), and BOU cybersecurity §5.4 (throttle + audit trail + granular field diffs).
Content assets
Feature reference for the content-assets surface — the platform-wide CMS that carries terms of service, privacy policy, product brochures, training material, and marketing content in versioned form. Reviewed against CPA 2022 §37 (consumer notice — the platform must prove which version was shown to a client), IRA Insurance Act 2017 §35 (rate-card + product-disclosure versioning), DPPA 2019 §16 (cross-border serve of published content), and BOU cybersecurity §5.4 (throttle + audit trail on both authenticated + public surfaces).
Notification templates
Feature reference for the notification-templates surface — the template store that renders every email / SMS / WhatsApp / in-app notification the platform sends. Reviewed against CPA 2022 §37 (consumer notice — the platform must prove which template version generated which sent message), DPPA 2019 §16 (cross-border render + rate) + §21 (PII in variable interpolation + body-at-rest), AML §14 (audit-trail integrity on template edits), and BOU cybersecurity §5.4 (throttle + audit on both edit + dispatch).
Ratings
Feature reference for the ratings surface — consumer star + free-text reviews of insurers, agents, and products. Reviewed against CPA 2022 §37 (published-review provenance + moderation), DPPA 2019 §11 (retention / storage-limitation), §17 (subject-erasure / rectification), §21 (PII in the free-text comment), AML §14 (moderation audit trail), and BOU cybersecurity §5.4 (throttle + audit on both authenticated + public surfaces).
Notification preferences
Feature reference for the notification-preferences surface — the store of per-user + per-client opt-in / opt-out state for every notification category × channel, plus the DPPA §16 cross-border data-transfer consent ledger (`sms_kenya` / `whatsapp_us` / `email_smtp`) that gates every non-transactional send that leaves Uganda. Reviewed against DPPA 2019 §11 (retention / storage-limitation), §13 (purpose-scoped consent lifecycle), §16 (cross-border transfer), §17 (subject-erasure / rectification / portability), §21 (PII in preference + consent metadata), CPA 2022 §37 (marketing opt-out + consumer notice), AML §14 (consent-transition audit trail), and BOU cybersecurity §5.4 (throttle + replay-protection on the public unsubscribe endpoint).
API keys
Feature reference for the api-keys surface — the store of long-lived platform tokens issued to partner integrations, insurer connectors, and internal automation. Reviewed against DPPA 2019 §21 (secret storage — hashed, never plaintext), §17 (subject-erasure cascade to issued keys), §11 (retention scrub past the AML §14 window), CPA 2022 §37 (least-privilege scope enforcement), AML §14 (audit trail on issue / rotate / revoke / use), NIST SP 800-63B §5 (authenticator lifecycle — expiry, warning, replay, revoke on compromise), and BOU cybersecurity §5.4 (throttle on issuance + rotation ledger + IP-based forensics).
Passkeys
Feature reference for the passkeys surface — WebAuthn credentials issued to platform users (ZFA staff, agents, admins) for passwordless AAL2 login. Reviewed against DPPA 2019 §21 (credential storage — publicKey opaque, private key never on-server), §17 (subject-erasure cascade to registered credentials), §11 (retention scrub past the AML §14 window), CPA 2022 §37 (consumer-safe device labels), AML §14 (audit trail on register / authenticate / revoke / clone-detect / retention), NIST SP 800-63B §5.2.1 (attestation verification) + §5.2.5 (signature-counter replay + clone detection) + §5.2.9 (deprecated-algorithm refusal), and BOU cybersecurity §5.4 (throttle on registration + authentication + audit trail).