SDLC 01: Requirements Specification
Revision history: Updated June 2026 — reflects 19-microservice architecture, Go/Python services, Meilisearch, BullMQ, expanded RBAC, fraud detection, loyalty/coupons, ZRA invoicing, WhatsApp integration, and comprehensive testing infrastructure.
1. Functional Requirements
1.1 B2B Layer (Merchants, Vendors, Distributors)
- Multi-tenant vendor onboarding with KYC (NRC upload, TPIN, business registration via PACRA).
- Product catalogue management: CRUD, bulk import/export, variant support (options & values), six pricing models (fixed, ranged, negotiable, quotation, promotional, wholesale/tiered).
- Inventory management: stock adjustments, stock-taking, low-stock alerts, barcode printing, SKU auto-generation.
- Wholesale tier management: per-product volume discount tiers.
- Order management and fulfilment tracking: delivery status, PIN-based confirmation, digital signature capture.
- Payout and settlement reporting: vendors receive proceeds after delivery confirmation; automated batch payouts.
- Role-based access control:
CUSTOMER,SHOP_OWNER,SERVICE_PROVIDER,DELIVERY_AGENT,PLATFORM_ADMIN,MODERATOR,FRAUD_ANALYST,FINANCE_ADMIN,SUPPORT_AGENT,SELLER,FLEET_MANAGER,SYSTEM. - Seller application workflow: multi-phase review, document upload, admin approval.
- ZRA Smart Invoice integration: per-vendor TPIN, VSDC transmission, configurable on/off, mock mode.
- On-demand reports: PDF/CSV/Excel for sales, settlements, tax, inventory, agent performance.
1.2 B2C Layer (End Consumers)
- User registration and authentication: email/password, OAuth (Google), magic link, OTP via Resend, MFA (TOTP, email, SMS).
- Product browsing, search: full-text via Meilisearch (typo-tolerant, faceted), filtering, category navigation.
- Shopping cart and checkout: Zambia-specific delivery address collection, multi-vendor cart support.
- Payment: MTN Mobile Money, Airtel Money, Zamtel Kwacha (USSD push) and Visa/Mastercard (hosted card page) with automatic failover.
- Coupons and loyalty: percentage/fixed-amount/free-delivery coupons; points-based loyalty per shop (earn, redeem, expire).
- Order history, status tracking, receipt generation: server-side PDF with barcode and QR code.
- File uploads: custom requests or returns via Cloudinary, moderated by Sightengine.
- Email notifications: order confirmations, password reset, welcome, delivery updates (via Resend).
- WhatsApp notifications: order alerts, delivery PINs, cart recovery (via WhatsApp Business Cloud API).
- In-app notifications: real-time via SSE stream.
1.3 Cross-Cutting Functional Requirements
- Unified admin dashboard: user management, order management, seller applications, broadcast notifications, product moderation, fraud review, reconciliation, ZRA transmissions, feature flags, platform analytics.
- SEO integration: Google Search Console; meta tags managed per page;
sitemap.xmlgenerated programmatically. - Email hosting: Zoho Mail (customer support); Resend (transactional).
- Domain: GoDaddy (registrar); DNS/CDN/WAF via Cloudflare.
- Content moderation: Sightengine for NSFW/violence detection; admin review queue.
- Fraud detection: real-time rules engine — velocity checks, amount anomalies, self-dealing, risk scoring; admin review queue.
- Observability: Middleware.io (traces, logs, metrics across all 19 services).
- Feature flags: runtime configuration via
pakashop-configservice without redeployment. - Real-time delivery tracking: WebSocket-based GPS tracking with Kalman filtering, geofencing, ETA calculation.
- Automated reconciliation: internal vs provider settlement comparison.
- Dynamic pricing: commissions, discounts, markups engine.
2. Non-Functional Requirements
| Category | Requirement |
|---|---|
| Performance | API response time < 200 ms (p95); homepage load < 1.5 s (Cloudflare-cached); search < 100 ms (Meilisearch) |
| Availability | 99.9% uptime; multi-service redundancy on AWS EC2; health checks every 15 minutes |
| Security | JWT-based authentication with MFA; WAF via Cloudflare; PCI-DSS SAQ A; OWASP ZAP scanning in CI |
| Scalability | Horizontal EC2 scaling; Redis caching; BullMQ job queue; stateless microservices |
| Compliance | Bank of Zambia NPS Act; Zambia Data Protection Act 2021; PCI-DSS SAQ A; ZRA Smart Invoice |
| Maintainability | Prisma schema versioning; environment separation (dev/staging/prod); structured logging with correlation IDs |
| Observability | OpenTelemetry traces; pino structured logs; Middleware.io dashboards; journald integration |
| Zambian Market | ZMW currency only; 16% VAT displayed; mobile money primary; "delivery" (not "shipping") throughout |
3. Technology Stack
| Component | Technology |
|---|---|
| Frontend | Next.js 15 (App Router), React, Tailwind CSS, Lucide/Heroicons, React Hot Toast, Leaflet, Recharts |
| Backend API | Node.js + Express (hosted on AWS EC2) |
| Languages | Node.js (16 services), Go (search, analytics), Python (moderation, recommendations) |
| Database ORM | Prisma |
| Database | PostgreSQL (AWS EC2 or managed RDS) |
| Search | Meilisearch |
| Job Queue | BullMQ on Redis |
| Caching | Redis (sessions, cart, rate-limiting, payment status, product cache, pub/sub) |
| DNS / CDN / WAF | Cloudflare |
| Domain Registrar | GoDaddy |
| Transactional Email | Resend (OTPs, order confirmations, password reset) |
| Email Hosting | Zoho Mail (customer support) |
| File Storage / CDN | Cloudinary |
| SEO Monitoring | Google Search Console |
| APM / Observability | Middleware.io (OpenTelemetry-based) |
| Content Moderation | Sightengine API |
| Mobile Money (primary) | PawaPay (MTN, Airtel, Zamtel) |
| Card / MoMo Failover | Flutterwave |
| WhatsApp Business Cloud API | |
| Process Management | systemd |
| Reverse Proxy | Nginx |
| CI/CD | GitHub Actions |
| Testing | Jest, Supertest, pytest, React Testing Library, Playwright, k6, OWASP ZAP |
4. Regulatory & Compliance Requirements
| Regulation | Requirement |
|---|---|
| Bank of Zambia NPS Act | Payments routed through licensed providers (PawaPay, Flutterwave); delayed settlement model to avoid escrow licence requirement; funds held by licensed providers, released after delivery confirmation |
| Zambia Data Protection Act 2021 | Consent collection; data minimisation; breach notification within 72 hours; DPA agreements with all processors; data subject rights (access, rectification, erasure, portability) |
| PCI-DSS SAQ A | Card data never collected or stored by Pakashop; all card entry via Flutterwave hosted pages; no raw card data in logs |
| ZRA / VAT | 16% VAT displayed and calculated on all transactions; ZRA Smart Invoice VSDC integration; per-vendor TPIN validation |
| Zambia ECT Act 2021 | Digital signatures legally equivalent to wet ink; SHA-256 tamper-evident hashing for proof of delivery |
5. Infrastructure Requirements
| Requirement | Implementation |
|---|---|
| Hosting | AWS EC2 (Ubuntu 22.04 LTS) for all backend services |
| Process Management | systemd unit files for all 19 services |
| Reverse Proxy | Nginx with TLS termination, WebSocket upgrade support |
| CDN | Cloudflare (Full Strict TLS, WAF, DDoS protection) |
| Database | PostgreSQL (RDS or EC2-hosted); Prisma migrations; nightly backups |
| Search | Meilisearch (dedicated EC2 instance or container) |
| Job Queue | BullMQ on Redis; separate queues per service |
| CI/CD | GitHub Actions: CI (lint, test, Prisma validate), deploy-staging, deploy-production, health-check, db-backup |
| Branch Strategy | main = staging, production = live |
| Environment Isolation | Separate databases, Redis instances, EC2 stacks for staging and production |
| Test Environment | pakashop_test database, Redis DB 1, non-conflicting ports (4000-series) |
6. Security Requirements
| Requirement | Implementation |
|---|---|
| Authentication | JWT access tokens (24h TTL) + rotating refresh tokens (30d); httpOnly, Secure, SameSite cookies |
| MFA | Mandatory for PLATFORM_ADMIN, SHOP_OWNER, DELIVERY_AGENT; optional for CUSTOMER; TOTP (speakeasy), email OTP, SMS (Twilio) |
| API Gateway Security | Dual-key model: x-pakashop-key (external clients) + x-internal-key (inter-service) |
| Rate Limiting | Redis-backed; general 1000 req/15min, auth 20 req/15min, payment 20 req/15min |
| Input Validation | express-validator, Prisma type constraints, request size limits |
| Transport Security | TLS 1.2+ enforced; HSTS header; Cloudflare Origin Certificate |
| CSRF Protection | SameSite=Strict cookies; Bearer token auth on API layer |
| PII Handling | Phone masking (+26097*****56), email masking (jo***@example.com), PAN redaction ([CARD-REDACTED]) |
| Vulnerability Scanning | npm audit in CI; OWASP ZAP; express-sec-audit |
| Fraud Detection | Real-time rules engine: velocity checks, amount anomalies, self-dealing, risk scoring |
| Content Moderation | Sightengine AI + human admin review queue |
For internal use only. Do not distribute outside Pakashop engineering.