# HamerzPay SRS (MVP Baseline)

## 1. Scope
HamerzPay provides a centralized BNPL and credit payment core for:
- Retail customers
- Merchants
- Organizations
- Internal operations/admin teams

## 2. System Context
- Backend: Laravel 12 (PHP)
- Database: MySQL 8
- Cache/Queue/Session: Redis
- Storage: S3-compatible (MinIO/S3)
- API-first design with independent panel scopes

## 3. Panels
- Customer Panel (`app.hamerzpay.test`)
- Merchant Panel (`merchant.hamerzpay.test`)
- Organization Panel (`org.hamerzpay.test`)
- Admin Panel (`admin.hamerzpay.test`)

Each panel has independent:
- Authentication scope
- Session policy
- Route namespace
- Dashboard capabilities

## 4. Functional Requirements (MVP)
1. Customer onboarding with OTP and KYC status tracking
2. Credit account creation and credit limit lifecycle
3. Merchant onboarding and operator management
4. Organization onboarding, member management, and budget assignment
5. Credit purchase flow with installment schedule generation
6. Repayment tracking with due-date and status management
7. Double-entry compatible ledger event storage
8. Admin KPI and operational monitoring endpoints

## 5. Non-Functional Requirements
- Security: role-based authorization, auditability, signed merchant requests
- Scalability: asynchronous processing for scoring, settlement, reminders
- Reliability: idempotent transaction endpoints and replay-safe webhooks
- Observability: structured logs, request tracing IDs, panel-level metrics

## 6. Integrations
- Shahkar adapter (mobile + national ID validation)
- Credit bureau adapter (pluggable providers)
- Banking/funding adapter layer for multi-provider orchestration
- Merchant-facing gateway APIs and webhooks

## 7. KPI Definitions
- Registration completion rate
- KYC approval rate
- Credit approval rate
- Credit GMV
- On-time repayment rate
- Delinquency/default rate
- Active merchant count
- Active organization count

## 8. Delivery Phases
1. Phase 1 (MVP): customer + merchant + credit purchase + installments + admin KPI
2. Phase 2: organization payroll models + advanced rule engine + settlement expansion
3. Phase 3: multi-bank orchestration + anti-fraud automation + BI pipelines