Technology & Architecture

Tech stack, API integrations, credit scoring, mobile money connectivity, security, and scalability considerations

1. Architecture Overview

The platform follows a multi-layered architecture with clear separation between the borrower-facing app, the bank/MFI integration layer, and the internal scoring/engine components.

Layer 1 — Borrower Interface📱 React Native Mobile App (Android primary, iOS secondary) + USSD Gateway

Layer 2 — API Gateway🔐 Authentication · Rate Limiting · Request Routing · API Versioning

Layer 3 — Core Services⚙️ Loan Origination · KYC Verification · Credit Scoring · Repayment Processing · Notifications

Layer 4 — Bank/MFI Integration🏦 Partner Bank APIs · Loan Disbursement · Repayment Reconciliation · Compliance Reporting

Layer 5 — Payment Rails💳 Telebirr · M-Pesa · Bank Transfer · EthSwitch · Mobile Money APIs

Layer 6 — Data & Intelligence🧠 Alternative Credit Scoring · Fraud Detection · Analytics · Reporting

Layer 7 — Infrastructure🖥️ In-Country Data Center · PostgreSQL · Redis · Monitoring · Backup/DR

2. Technology Stack

Frontend (Borrower App)

Component	Technology	Rationale
Mobile Framework	React Native	Single codebase for Android + iOS. Team already skilled (per original proposal). Large ecosystem.
UI Library	React Native Paper or NativeBase	Material Design components. Good accessibility. Amharic font support.
State Management	Redux Toolkit or Zustand	Predictable state for complex loan workflows.
Offline Support	WatermelonDB or AsyncStorage	Critical for areas with intermittent connectivity. Queue KYC submissions for later sync.

Frontend (Admin/Bank Portal)

Component	Technology	Rationale
Web Framework	React + Next.js	Server-side rendering for performance. Admin dashboards, reporting views.
UI Library	Tailwind CSS + shadcn/ui	Fast development, consistent design system, dark mode support.

Backend

Component	Technology	Rationale
API Framework	Node.js (Hono or Express) or Python (FastAPI)	Hono for lightweight API gateway. FastAPI for credit scoring services (Python ML ecosystem).
Primary Database	PostgreSQL	ACID compliance for financial data. JSON support for flexible KYC documents. Proven in Ethiopian context.
Cache	Redis	Session management, rate limiting, real-time credit score caching.
Message Queue	BullMQ or Redis Streams	Async processing for loan applications, disbursement triggers, notification dispatch.
Search	PostgreSQL FTS or Meilisearch	Loan application search, applicant lookup. Meilisearch for Amharic text search.
Document Storage	MinIO or PostgreSQL large objects	KYC documents (ID photos, trade licenses). In-country storage mandatory.

ML / Credit Scoring

Component	Technology	Rationale
ML Framework	scikit-learn + XGBoost	Proven for tabular credit scoring. Fast inference, good explainability.
Deep Learning (optional)	PyTorch	If using image data for KYC or NLP for Amharic text analysis.
Model Serving	FastAPI + ONNX Runtime	Low-latency inference. ONNX for production model portability.
Feature Store	PostgreSQL + Redis	Real-time features from transaction data, cached for fast scoring.

Infrastructure

Component	Technology	Rationale
Hosting	Ethio Telecom DC or local provider	Data localization mandate. Evaluate Ethio Telecom's cloud offerings.
Containerization	Docker + Docker Compose (or K3s)	Simple deployment. K3s for lightweight Kubernetes if scaling.
CI/CD	GitHub Actions or GitLab CI	Automated testing and deployment. In-country runner for deployment.
Monitoring	Grafana + Prometheus	System health, API latency, error rates. Alerting for incidents.
Logging	Loki or ELK Stack	Centralized logging for audit trails and debugging.
Backup	pg_dump + offsite within Ethiopia	Daily backups with off-site storage. RTO < 24 hours.

3. API Integrations Required

Mobile Money Integration

ℹ️ Critical integration. Disbursement and repayment MUST go through mobile money to reach the mass market. Direct bank transfers are too slow and require bank account ownership.

Service	Purpose	Integration Method
Telebirr API	Disbursement + repayment	Through partner bank's Telebirr integration (e.g., CBO API). Direct API may require PII-level access.
M-Pesa API	Alternative disbursement channel	Safaricom Developer Portal. Growing user base in Ethiopia.
EthSwitch	Interoperability hub	National switch for bank-to-bank and bank-to-mobile transfers. Required for PII interoperability.
Telebirr USSD	Non-smartphone access	USSD gateway for loan applications and status checks without a smartphone.

Identity & KYC

Service	Purpose	Notes
National ID verification	Primary identity document	National Digital ID system is in development. Current: OCR + AI verification of ID photos.
Trade License verification	Business existence proof	OCR extraction + manual or API verification with trade office.
Liveness check	Selfie match to ID photo	Face recognition API (e.g., FaceTec, or open-source alternatives).
Kebele ID	Supplementary ID	For borrowers without National ID. Photo capture + OCR.

Payment & Banking

Service	Purpose	Notes
Partner Bank API	Loan disbursement, balance check, repayment reconciliation	Each partner bank will have different API capabilities. Build adapter pattern.
SMS Gateway	OTP, notifications, repayment reminders	Integrate with local SMS providers (e.g., Africa's Talking, Ethio Telecom SMS).
Push Notifications	Real-time app notifications	Firebase Cloud Messaging (Android), APNs (iOS).

4. Credit Scoring Engine

This is the core IP and competitive differentiator. With CRB inaccessible, the scoring engine must rely entirely on alternative data.

Data Sources for Scoring

Data Source	What It Tells You	Availability
Mobile money transactions	Income patterns, cash flow stability, spending behavior	High — with borrower consent via Telebirr/M-Pesa APIs
POS / merchant data	Business revenue, transaction volume, seasonality	Medium — via payment processor partnerships
Trade license	Business existence, registration type, years active	High — collected during KYC
National ID data	Age, location, identity verification	High — collected during KYC
Phone metadata	Device age, usage patterns (NOT contacts — avoid Kenya mistake)	Medium — with explicit consent
App behavior	Engagement, consistency, feature usage	High — first-party data
Employer data	Income stability, employment tenure	Medium — for salaried borrowers
Geographic data	Urban vs. rural, regional risk factors	High — from device GPS (with consent)

Scoring Model Architecture

Feature engineering: Transform raw transaction data into behavioral features (avg monthly income, income volatility, expense-to-income ratio, transaction frequency, cash flow trends)
Model training: XGBoost ensemble for primary scoring. Logistic regression as interpretable baseline.
Score bands: Map scores to credit tiers — determines maximum loan amount and interest rate
Explainability: SHAP values for each decision — required for transparency and regulatory compliance
Feedback loop: Repayment outcomes feed back into model retraining. Model improves over time.
Fraud detection: Separate model for application fraud (identity mismatch, synthetic identities, document forgery)

⚠️ Model risk: Alternative data scoring is less established than traditional credit bureau scoring. Initial models will have higher uncertainty. Plan for: conservative initial limits, manual review queue for edge cases, and gradual model expansion as data accumulates.

5. Security Requirements

Requirement	Implementation	Priority
Encryption at rest	AES-256 for all stored data (PostgreSQL TDE, document encryption)	Critical
Encryption in transit	TLS 1.3 for all API communications. Certificate pinning in mobile app.	Critical
Authentication	JWT + refresh tokens. Biometric auth (fingerprint/face) for sensitive operations.	Critical
Authorization	Role-based access control (RBAC). Admin portal: loan officer, compliance officer, admin.	Critical
Rate limiting	API rate limiting to prevent abuse. Stricter limits on loan application endpoints.	High
Intrusion detection	IDS/IPS on network perimeter. Log anomaly detection.	High
Penetration testing	Annual third-party pentest. Quarterly internal security review.	High
Audit trails	Immutable logs for all financial transactions and admin actions. 5+ year retention.	High
Incident response	Documented IR plan. 72-hour breach notification to ECA (PDPP requirement).	High
KYC document security	Encrypted storage with access logging. Auto-expiry for expired documents.	Medium

6. Scalability Considerations

Horizontal scaling: Stateless API services behind a load balancer. PostgreSQL read replicas for reporting queries.
Database partitioning: Partition loan data by region/partner bank as the dataset grows.
CDN for static assets: App bundles, images, and documentation via CDN (within Ethiopia if required).
Async processing: Non-critical operations (notifications, report generation, model retraining) via message queues.
Multi-tenant design: If expanding to other countries later, design the data model for multi-tenancy from day one.
API versioning: Version all APIs to allow partner bank integrations to evolve independently.

7. Development Timeline Estimate

Phase	Duration	Deliverables
Discovery & Design	3-4 weeks	Requirements finalization, UX research (Amharic), architecture design, bank/MFI partner selection
Core Platform MVP	8-10 weeks	KYC flow, loan application, credit scoring engine v1, admin dashboard, bank API integration
Payment Integration	3-4 weeks	Telebirr disbursement/repayment, mobile money reconciliation, EthSwitch integration
Testing & QA	3-4 weeks	UAT with partner bank, security audit, performance testing, compliance review
Pilot Launch	2-3 weeks	Limited release to selected MSMEs, monitoring, feedback collection, iteration
Full Launch	Ongoing	Public release, marketing, partner bank onboarding, model improvement
Total to MVP	~16-20 weeks	Up from 14 weeks in original proposal — additional time for compliance and banking integrations

8. Cost Implications (vs. Original Estimate)

The original proposal estimated ETB 292,500 for a driver-focused microcredit app. The expanded scope significantly increases requirements:

Item	Original (Driver App)	Expanded (Full Platform)	Delta
Design & Planning	ETB 30,000	ETB 80,000-120,000	3-4× (UX research, multi-language, bank portal)
Development	ETB 206,250	ETB 600,000-900,000	3-4× (scoring engine, bank APIs, admin portal)
Testing	ETB 56,250	ETB 150,000-200,000	3× (security audit, compliance testing, UAT)
Compliance & Legal	Not included	ETB 100,000-200,000	New (ECA registration, legal counsel, AML setup)
Infrastructure	Not included	ETB 200,000-400,000/yr	New (in-country data center, monitoring, backup)
Total (Year 1)	ETB 292,500	ETB 1,130,000-1,820,000	~4-6×

ℹ️ Note: These are rough estimates. Actual costs depend on team size, partner bank API complexity, and compliance requirements. The expanded platform is a significantly larger undertaking than the original proposal. Consider phased delivery to manage cash flow.

9. Key Technical Decisions to Make

Node.js vs. Python for core API? — Node.js for speed/real-time, Python for ML integration. Consider Hono (Node) for API gateway + FastAPI for scoring services.
Single bank or multi-bank from MVP? — Start with 1 bank partner for MVP, add more in phase 2. Multi-bank adds significant integration complexity.
USSD from day one? — Critical for non-smartphone users but adds development cost. Consider phase 2.
Amharic-only or multi-language from launch? — Amharic-first with Oromo support as priority phase 2 addition.
Build vs. buy credit scoring? — Build (Kifiya-style) vs. partner with existing scoring provider. Build is higher upfront but owns the IP.
Hosting provider? — Evaluate Ethio Telecom DC, local private DCs, and emerging Ethiopian cloud providers.