Pakashop Documentation

Version: Pakashop v2 | Last updated: June 2026 Platform: Production-grade Zambian B2B2C marketplace

Introduction

Pakashop is a multi-vendor B2B2C e-commerce platform built for the Zambian market. It connects merchants, distributors, and individual sellers with end consumers through a unified marketplace experience. The platform is engineered for scale, compliance, and reliability — handling everything from mobile-money-first payments to real-time delivery tracking and ZRA tax integration.

Key Differentiators

Feature	Description
Mobile Money Native	Primary checkout via MTN, Airtel, and Zamtel mobile money (USSD push) with automatic card fallback
Escrow-Avoiding Settlement	Delayed settlement model compliant with Bank of Zambia NPS Act — funds held by licensed providers, released only after PIN-verified delivery
Full Logistics Stack	Agent onboarding, hybrid assignment (manual/self-claim/automated), real-time GPS tracking, PIN confirmation, digital signature capture
ZRA Smart Invoice	Direct VSDC integration for automated tax invoice generation and transmission
AI Content Moderation	Automated NSFW/gore detection via Sightengine with admin review queue
Fraud Detection	Real-time rules engine with velocity checks, amount anomalies, and self-dealing detection

Tech Stack at a Glance

Layer	Technology
Frontend	Next.js 15 (App Router), Tailwind CSS, Lucide/Heroicons, React Hot Toast, Leaflet, Recharts
Backend API	Node.js / Express, Prisma ORM, PostgreSQL
Languages	Node.js (16 services), Go (2 services — search, analytics), Python (2 services — moderation, recommendations)
Process Management	systemd (every service is a unit)
Reverse Proxy	Nginx with TLS termination
CDN/DNS/WAF	Cloudflare
Hosting	AWS EC2 (Ubuntu 22.04 LTS)
Search	Meilisearch
Job Queue	BullMQ on Redis
Caching	Redis (sessions, product cache, pub/sub, rate limiting)
Monitoring	Middleware.io (OpenTelemetry), pino structured logging, journald
CI/CD	GitHub Actions (CI, staging deploy, production deploy, health checks, DB backups)
Payments	PawaPay (mobile money USSD), Flutterwave (cards + mobile money fallback)

Microservices (19 Total)

#	Service	Language	Port	Purpose
1	`pakashop-gateway`	Node.js	8000	API gateway — routing, dual-key security, rate limiting, WebSocket upgrades
2	`pakashop-backend`	Node.js	3080	Core business logic — auth, orders, products, shops, payments
3	`pakashop-config`	Node.js	3085	Centralised feature flags & runtime configuration
4	`pakashop-notifications`	Node.js	3090	Email, in-app notifications, SSE real-time stream
5	`pakashop-tracking`	Node.js	3120	Real-time delivery tracking — WebSocket server, Redis Pub/Sub
6	`pakashop-moderation`	Python	3110	Sightengine AI content moderation pipeline
7	`pakashop-recommendations`	Python	3100	Collaborative filtering engine (Jaccard + k-NN)
8	`pakashop-scheduler`	Node.js	3004	Background job infrastructure (BullMQ)
9	`pakashop-search`	Go	3005	Full-text product search via Meilisearch
10	`pakashop-fraud`	Node.js	3006	Rules-based fraud detection engine
11	`pakashop-analytics`	Go	3007	Business intelligence — vendor/admin dashboards
12	`pakashop-coupon`	Node.js	3008	Promotions & discount engine
13	`pakashop-loyalty`	Node.js	3010	Points-based loyalty & rewards
14	`pakashop-whatsapp`	Node.js	3009	WhatsApp Business Cloud API integration
15	`pakashop-reports`	Node.js	3011	PDF/CSV/Excel report generation
16	`pakashop-reconciliation`	Node.js	3012	Automated financial reconciliation
17	`pakashop-invoicing`	Node.js	3013	ZRA Smart Invoice VSDC integration
18	`pakashop-pricing`	Node.js	3014	Dynamic pricing engine — commissions, discounts, markups
19	`pakashop-settlement`	Node.js	3016	Automated batch vendor & agent payouts

Core SDLC Documents

#	File	Description
01	`SDLC/REQUIREMENTS`	Functional & non-functional requirements; tech stack; regulatory constraints
02	`SDLC/DESIGN`	System architecture; key design decisions; data flow examples
03	`SDLC/DEVELOPMENT`	Development standards, coding conventions, local setup
04	`SDLC/TESTING`	Test strategy, types of tests, coverage requirements
05	`SDLC/DEPLOYMENT`	CI/CD pipelines, environment mapping, release procedures
06	`SDLC/MAINTENANCE`	Monitoring, incident response, system operations

Specialised Reference Documents

File	Description
`microservices`	Comprehensive reference for all 19 services
`roles-permissions`	Full role hierarchy and permissions matrix
`api-design`	Full API endpoint reference; request/response contracts
`data-models`	Prisma schema for all key models; enum reference; ER diagram
`payment-architecture`	PawaPay + Flutterwave flows, webhook processing, settlement model
`checkout-flow`	Step-by-step checkout UX, polling logic, error handling
`order-lifecycle`	Order & payment status machines, settlement states, refund scenarios
`inventory-system`	Stock management, SKU generation, barcode, wholesale tiers
`caching-strategy`	Redis key conventions, TTLs, cache invalidation rules
`content-moderation`	Sightengine integration, moderation flow, admin review
`fraud-detection`	Rules engine, risk scoring, admin queue, API endpoints
`loyalty-coupons`	Coupon types/validation/redemption, loyalty points
`delivery-tracking`	WebSocket architecture, Redis Pub/Sub, GPS tracking
`delivery-signing`	PIN confirmation, digital signature capture, ECT Act compliance
`zra-invoicing`	VSDC integration, mock mode, TPIN, transmission logging
`hosting-infrastructure`	EC2 topology, Nginx config, systemd units, networking
`ci-cd-pipeline`	GitHub Actions workflows, branching strategy, migrations
`security-compliance`	PCI-DSS, BoZ NPS Act, Zambia DPA 2021, fraud, MFA
`observability`	Middleware.io, pino, journald, tracing, alerts
`testing-strategy`	Testing pyramid for backend, microservices, frontend, E2E
`deployment-operations`	Step-by-step deploy process, systemd management, rollback