Hyperion-L

Hyperion-L is a horizontally decomposed platform built on a Python async microservices backend (FastAPI + psycopg3 + PostgreSQL) paired with Next.js 16 App Router frontends. All services communicate via a CloudEvents event bus; no service holds cross-domain state.

Backend

• Python 3.12+, async throughout, Pydantic v2 validation
• FastAPI services — one per bounded domain
• PostgreSQL primary + hot standby
• psycopg3 connection pool (singleton per DSN)
• CloudEvents-native event bus (situ-cloudevents)
• UUID7 identifiers — time-ordered, k-sortable
• uv workspace — all Python packages in one lock-file
• Pyright strict type checking across all services

Frontend

• Next.js 16 App Router (React Server Components default)
• Turbopack build (LMS) / webpack (Superapp, Executive)
• pnpm workspaces — 10 shared packages
• Design token system (CSS custom properties) — no hard-coded hex values
• WCAG 2.2 AA — full aria labels, focus traps, contrast verified
• Standalone Next.js output — rsync + systemd deployment

Data & Events

• Raw SQL migrations — no ORM, schema versioned
• CloudEvents for all state transitions (loan lifecycle, payments, compliance)
• Read-API pattern — single read-optimised API aggregates across write services
• Event replay support for cold archive drill and audit chain reconstruction

Every product is identified by a versioned product code (e.g. logbook-v1). The internal M-series numbering maps to specification phases; the table below lists the full product taxonomy.

A Next.js progressive web app for retail borrowers, chama members, SME owners, and investors. Designed for mobile-first usage with offline-capable tracking and M-Pesa-native repayment.

Loan Journey

• Multi-product application wizard — phone + OTP signup, no account required
• Application tracking by reference (APL-2026-XXXXXX) — OTP-gated, no login
• Live status timeline — submitted → assessed → approved → disbursed
• M-Pesa STK push repayment — 75s hard timeout, full Daraja error handling
• Loan schedule viewer — amortisation table, next due date, payoff quote
• Repayment allocation planner — partial payment waterfall
• Restructure / decline receipt download
• SLA commitment display — CBK DCP-mandated response times

Financial Superapp Features

• Wallet — top-up, balance, transaction history
• Bill payments — utility, government, merchant
• Savings goals — target, auto-debit, progress tracking
• Insurance — motor renewal, trade credit, claims initiation
• Chama membership — draw requests, quorum voting, revolving facility
• Cooperative / SACCO — share balance, loan eligibility
• Group procurement — member of buying group, RFQ tracking
• Vehicle intelligence — logbook valuation, NTSA status
• Guarantor portal — consent, exposure view, withdrawal
• Business / merchant tools — till linkage, revenue tracking
• Daftari integration — shop attestation, credit line
• Wealth / retail investment — LP participation, returns
• Loyalty programme — referral rewards, tier status
• AI coaching — conversational financial guidance (LiteLLM-backed)
• SME score — self-service credit health indicator
• Sector index — sector benchmarking for SMEs
• Compliance view — ODPC consent registry, data usage
• Support — live ticket, SLA tracking

Deposits

• Goal-based savings with auto-debit scheduling
• Term deposits with tenor-based rate cards
• Sweep accounts — linked to credit facilities for automatic repayment
• SACCO savings — share ledger integration

Payment Rails

• M-Pesa Daraja B2C / C2B / STK Push / B2B
• M-Pesa STK error code handling: 1037 (no response), 1032 (cancelled), 2001 (wrong PIN), 1 (insufficient balance)
• Remittance assignment — cross-border incoming payment matching
• Multi-currency wallet — FX conversion, cross-border settlement
• Disbursement batch engine — pending float, FX desk pre-approval
• Teller / cashier — cash allocation, settlement receipts

The primary operational surface for loan officers, compliance staff, and back-office teams. Accessed at lms.situ.datacraft.co.ke. The command center provides a live pipeline Kanban, SLA watchdog, PAR summary, and float breach alerts on a single screen.

Specialist Workbenches

Application Pipeline

• Multi-product application intake — borrower app, agent, USSD, or API
• OTP-gated identity verification (Africa's Talking or WhatsApp)
• eCitizen integration — national ID verification
• Metropol CRB bureau pull — automated, logged in audit trail
• KRA PIN verification and tax compliance check
• Bank statement analysis (PDF/API) — income, volatility, obligations
• Satellite NDVI scoring for agricultural applicants
• SME scorecard — 12-variable weighted model
• Fraud signal assessment — device, behavioural, identity
• Co-signing / guarantor consent workflow
• ODPC-compliant DPA consent capture at application

Decision Engine

• Automated pre-scoring → manual review queue routing
• Configurable scorecard weights and override registry
• Champion/challenger A-B model split
• Decision explainability — feature importances, reason codes
• Contestability workflow — borrower can challenge decline
• SLA scheduler — CBK DCP mandated decision timelines
• Capacity breach monitor — portfolio concentration limits
• Repo-readiness check before disbursement approval

• Aging bucket dashboard — 1–30, 31–60, 61–90, 90+ DPD
• Promise-to-Pay (PTP) pipeline — commitment tracking, follow-up scheduling
• Field agent dispatch — GPS proximity routing, visit logging
• WhatsApp / SMS automated reminders (situ-whatsapp, situ-at)
• USSD self-cure channel — borrower-initiated restructure
• Telegram notifications for agent-captain communications
• Repayment allocation waterfall — fees → interest → principal
• In-duplum enforcement — auto-cap on interest accumulation
• Write-off workflow — vintage analysis, credit committee approval
• Recovery tracking post write-off

• Float account management — real-time position, breach alerts
• Disbursement batch engine — M-Pesa B2C / bank EFT
• FX desk — multi-currency positions, conversion requests
• Multi-currency wallet — KES, USD, EUR positions
• Cross-border settlement — remittance assignment
• Pending batch queue — maker-checker approval
• Disbursement-to-event correlation via CloudEvents
• Debt capital markets — DCM facility management

Hyperion-L supports a hierarchical field agent network: clusters → captains → agents. Agents originate loans, collect repayments, and conduct KYC visits. The presence beacon service tracks agent activity in real time.

• Cluster management — geographic grouping, quota assignment
• Captain KPI dashboard — team performance, disbursement volume
• Commission payout engine — per-loan, tier-based rates
• Presence beacon — agent check-in, GPS timestamping
• Agent portal — dedicated UI for field staff
• Portfolio visibility — agent's own book, collection targets
• Workload balancing — queue assignment by capacity

• PAR30 / PAR60 / PAR90 — real-time calculation
• Portfolio concentration limits — sector, geography, product
• Vintage analysis — cohort-level loss rate trends
• Model validation workbench — PSI, Gini, KS statistic
• Champion/challenger model splits — live A/B scoring
• Sector index — comparative risk benchmarking
• NDVI risk overlay — agricultural portfolio climate risk
• Telematics safety scoring — motor loan risk adjustment
• Fraud signal integration — real-time decision enrichment
• Capacity breach monitor — automated hard-stop on breached limits

The ECL engine implements IFRS 9 §5.5 expected credit loss calculation natively. Provisions are computed per-loan on a nightly batch and reported to the executive dashboard, examiner portal, and CBK returns.

Stage Classification

• Nightly stage migration engine — automatic reclassification
• PD / LGD / EAD parameter management
• Collateral haircut schedules per product
• In-duplum enforcement — caps loss exposure at outstanding principal
• Stage migration waterfall — forward and backward migration tracking
• ECL dashboard in examiner portal (§9.4 adequacy view)
• Provision movements fed to GL and board pack

• Double-entry chart of accounts — configurable per entity
• Automated journal entries from loan lifecycle events
• Trial balance — period-end report with drill-down
• Period close workflow — maker-checker, lock, reopen
• ECL provision entries auto-posted from nightly batch
• Fee income recognition — origination, processing, late fees
• Interest income accrual and recognition
• Co-lending participation accounting — senior/subordinated splits

Hyperion-L was built ground-up for CBK DCP compliance. The situ-cbk-returns library handles all return formats; the examiner portal provides regulators with direct read access.

Return Formats Supported

• BS-1 — Balance sheet return (monthly)
• PG/04 — Credit information return (quarterly)
• DCP return pack — full digital credit provider submission
• NDTCP threshold declaration — KES 20M capital classification
• PAR report — quarterly portfolio-at-risk
• AML/CFT statistical return — CBK §44

Submission Pipeline

• Automated data aggregation from loan and GL services
• Validation layer — catches cross-field errors before submission
• CBK API direct submission (where available)
• PDF/XLSX export for manual upload flows
• Submission history and acknowledgement tracking
• Examiner portal — regulators view same data in read-only workspace

• Sanctions screening — OFAC SDN list, UN consolidated list
• CBK §44 AML compliance queue
• PEP (Politically Exposed Person) flag detection
• Transaction monitoring — large-value alerts (KES 1M+)
• Suspicious activity report (SAR) workflow
• Enhanced due diligence (EDD) for high-risk borrowers
• AML officer dedicated queue in LMS
• eCitizen national ID verification at onboarding
• KRA PIN validation for business borrowers
• Metropol CRB check — mandatory at application

Hyperion-L implements the Kenya Data Protection Act (2019) via the situ-consent library and the Dignity consent framework (situ-dignity). All personal data processing is purpose-bounded and consent-gated.

• DPA consent capture at every data-sharing touchpoint
• Purpose-bound consent ledger — dignity.consent.purpose.* namespace
• Granular consent types: credit scoring, bureau sharing, marketing, analytics
• Withdrawal workflow — borrower-initiated consent revocation
• ODPC consent log in both borrower app and officer console
• Data subject access request (DSAR) workflow
• Retention schedule enforcement — auto-archive at period end
• NDTCP (National Data Transfer and Cross-border Policy) compliance
• Cross-border data transfer controls for international loan products

A read-only portal issued exclusively to Central Bank of Kenya examiners. Provides direct visibility into portfolio health, ECL adequacy, enforcement status, and regulatory return submissions without requiring any data extracts.

• ECL §9.4 adequacy review — stage distribution, provision coverage
• Enforcement actions register — open, escalated, resolved
• Risk matrix — product × segment heat map
• Examination workspace — structured examination workflow
• CBK returns history — submission timestamps, validation status
• Audit chain — cryptographically-ordered event log
• Institution-level portfolio view — all loans, stages, products
• Loan-level drill-down — full history, documents, decisions
• Findings log — examiner notes and recommendations
• Structured export — XLSX / CSV for CBK analytical tools
• Events feed — real-time platform activity log

A dedicated portal for C-suite and board members. Surfaces KPIs, financial performance, risk posture, and compliance status without operational noise.

• KPI sparklines — 12-month trend per metric
• Cluster / geographic breakdown
• Audit trail — all executive actions logged
• Compliance status panel — CBK, ODPC, NDTCP
• Owner equity view — cap table, dividend position
• Board pack viewer — latest and historical

Serves institutional investors (LPs) and retail investors participating in debt or equity instruments. The explainability service (situ-investor-explainability) translates credit decisions and portfolio movements into LP-digestible narratives.

• MOIC / DPI / TVPI — fund-level and cohort-level
• Vintage IRR — per deployment cohort
• Covenant compliance dashboard — LTV, PAR30, concentration caps
• IFRS 9 stage migration narrative — investor-friendly ECL explanation
• Cash distribution schedule — projected and actual
• Retail investment portal — individual LP participation
• Dataroom export — secure document bundle for due diligence
• Retail investment marketplace — secondary liquidity interface

• Monthly board pack composer — automated data pull from all services
• Configurable sections — CEO letter, financials, risk, compliance, pipeline
• Digital distribution — secure link, access log, read receipts
• Dataroom export — encrypted bundle for investor / auditor access
• Credit committee workflow — formal approval with recorded votes
• Attestation service — board member confirmation of receipt
• Historical archive — all past packs, version-controlled

External Integrations

LaaS (Lending as a Service)

Hyperion-L exposes an embedded credit API for partner lenders, banks, and fintech companies. Partners integrate via the LaaS module without building underwriting infrastructure:

• Rate card configuration per partner
• Partner credit limit management
• White-label origination API
• Webhook delivery for all loan lifecycle events
• Per-partner reporting and reconciliation

Public API

GET  /v1/applications/{id}          Application status
POST /v1/applications                  New application
GET  /v1/loans/{id}/schedule           Amortisation schedule
POST /v1/loans/{id}/repayments         Repayment initiation
GET  /v1/consent/{uid}                 Consent registry
POST /v1/events/webhook                CloudEvent delivery
GET  /v1/ecl/summary                   ECL provision summary

M-Pesa is the primary payment rail for both disbursement and collection. The situ-mpesa service handles all Daraja API interactions with full error taxonomy.

Error Handling

• Caddy — automatic HTTPS, zero-downtime reload, Caddyfile routing
• systemd — all services managed as units; journald log aggregation
• uv — Python package management, reproducible environments
• Docker Compose — full local dev stack
• CI: pytest (3,447 tests, 0 failures) · pyright · ruff
• Deploy: local build → rsync .next/standalone → systemd restart
• OpenBao (HashiCorp Vault fork) — secrets management
• Prometheus + Grafana — latency, error rate, DB pool saturation
• Loki — structured log aggregation across all services

Authentication Model

• JWT-based sessions — situ_session httpOnly cookie
• Role claims in JWT: borrower, officer, examiner, executive, investor, agent
• LMS proxy.ts — Edge-runtime JWT decoding, role header injection; no middleware.ts co-existence
• SpiceDB — fine-grained relationship-based authorisation for resource-level access
• Rate limiting library (situ-rate-limit) — per-IP and per-user throttling
• Demo mode — unsigned JWT (alg:none) valid only when SITU_DEMO_MODE=1 + SITU_DEMO_KEY set

Security Controls

• OWASP Top 10 mitigated — SQL injection via parameterised queries, XSS via React, CSRF via SameSite cookies
• Prod DSN guard — CI hard-fails if production DSN appears in test code
• Secrets via OpenBao — no credentials in code or environment at rest
• Audit log — every officer action, every decision, every data access timestamped
• HTTPS everywhere — Caddy automatic certificate renewal
• Content Security Policy on all Next.js apps
• WCAG 2.2 AA — accessible to screen readers, keyboard navigation