Microservices Reference

Related docs: SDLC/DESIGN · Hosting Infrastructure · API Design

---

1. Service Registry

Pakashop comprises 19 microservices, each with a dedicated responsibility, language, and port. All services are hosted on AWS EC2 (Ubuntu 22.04 LTS) and managed by systemd.

#	Service	Language	Port	Purpose	Health Endpoint
1	pakashop-gateway	Node.js	8000	API gateway — routing, dual-key security, rate limiting, WebSocket upgrades	GET /health
2	pakashop-backend	Node.js	3080	Core business logic — auth, orders, products, shops, payments, users	GET /health
3	pakashop-config	Node.js	3085	Centralised feature flags & runtime configuration (Redis-cached)	GET /health
4	pakashop-notifications	Node.js	3090	Email (Resend/SMTP), in-app notifications, SSE real-time stream	GET /health
5	pakashop-tracking	Node.js	3120	Real-time delivery tracking — WebSocket server, Redis Pub/Sub, GPS ingestion	GET /health
6	pakashop-moderation	Python	3110	Sightengine AI content moderation pipeline for uploaded images	GET /health
7	pakashop-recommendations	Python	3100	Collaborative filtering engine (Jaccard + k-NN) on Redis	GET /health
8	pakashop-scheduler	Node.js	3004	Background job infrastructure (BullMQ) — periodic cleanup, retries	GET /health
9	pakashop-search	Go	3005	Full-text product search via Meilisearch — typo-tolerant, faceted	GET /health
10	pakashop-fraud	Node.js	3006	Rules-based fraud detection — velocity checks, anomalies, self-dealing	GET /health
11	pakashop-analytics	Go	3007	Business intelligence — vendor/admin dashboards, hourly/daily/weekly aggregation	GET /health
12	pakashop-coupon	Node.js	3008	Promotions & discount engine — creation, validation, redemption	GET /health
13	pakashop-loyalty	Node.js	3010	Points-based loyalty & rewards — earn, redeem, expire	GET /health
14	pakashop-whatsapp	Node.js	3009	WhatsApp Business Cloud API — order alerts, delivery PINs, cart recovery	GET /health
15	pakashop-reports	Node.js	3011	PDF/CSV/Excel report generation	GET /health
16	pakashop-reconciliation	Node.js	3012	Automated financial reconciliation — internal vs provider settlements	GET /health
17	pakashop-invoicing	Node.js	3013	ZRA Smart Invoice VSDC integration — configurable on/off, mock mode	GET /health
18	pakashop-pricing	Node.js	3014	Dynamic pricing engine — commissions, discounts, markups	GET /health
19	pakashop-settlement	Node.js	3016	Automated batch vendor & agent payouts	GET /health

---

2. Communication Patterns

2.1 External Traffic Flow

Client (Browser/App)
  │
  ▼
Cloudflare (DNS/WAF/CDN)
  │
  ▼
Nginx (TLS termination, port 443)
  │
  ▼
pakashop-gateway (port 8000)
  │
  ├──► pakashop-backend (port 3080)     — /api/v1/auth, /api/v1/orders, etc.
  ├──► pakashop-search (port 3005)      — /api/v1/search
  ├──► pakashop-tracking (port 3120)    — /api/v1/tracking (WebSocket upgrade)
  ├──► pakashop-notifications (port 3090) — /api/v1/notifications (SSE)
  └──► ... other services

2.2 Inter-Service Communication

All service-to-service calls go through the gateway with the x-internal-key header:

// Example: backend calling search service
const response = await fetch('http://localhost:8000/api/v1/search/products', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-internal-key': process.env.INTERNAL_API_KEY
  },
  body: JSON.stringify({ query: 'phone', filters: { category: 'electronics' } })
});

2.3 Redis Pub/Sub

Used for real-time event broadcasting (primarily tracking):

pakashop-tracking
  │ PUBLISH order:{orderId}:location
  ▼
Redis Pub/Sub
  │
  ├──► WebSocket clients (buyer browser)
  ├──► WebSocket clients (vendor dashboard)
  └──► WebSocket clients (admin panel)

2.4 BullMQ Job Queues

Used for asynchronous background processing:

Queue	Producer	Consumer	Purpose
email	backend, notifications	notifications	Send transactional emails
moderation	backend	moderation	Process image moderation
reports	backend, admin	reports	Generate PDF/CSV/Excel reports
settlement	backend, scheduler	settlement	Batch vendor payouts
reconciliation	scheduler	reconciliation	Daily settlement reconciliation
zra-invoice	backend	invoicing	Transmit Smart Invoices to ZRA
whatsapp	backend	whatsapp	Send WhatsApp messages
inventory-alerts	backend, scheduler	backend	Low-stock notifications

---

3. Internal API Key Usage

3.1 Dual-Key Security Model

Key Type	Header	Purpose	Scope
External client key	x-pakashop-key	Identifies external clients	Frontend, mobile apps, third-party integrations
Internal service key	x-internal-key	Authenticates inter-service requests	All microservices

3.2 Gateway Routing Logic

// services/gateway/src/middleware/routing.js
const serviceMap = {
  '/api/v1/auth': 'http://localhost:3080',
  '/api/v1/orders': 'http://localhost:3080',
  '/api/v1/payments': 'http://localhost:3080',
  '/api/v1/products': 'http://localhost:3080',
  '/api/v1/search': 'http://localhost:3005',
  '/api/v1/tracking': 'http://localhost:3120',
  '/api/v1/notifications': 'http://localhost:3090',
  '/api/v1/analytics': 'http://localhost:3007',
  '/api/v1/coupons': 'http://localhost:3008',
  '/api/v1/loyalty': 'http://localhost:3010',
  '/api/v1/reports': 'http://localhost:3011',
  '/api/v1/fraud': 'http://localhost:3006',
  '/internal': 'http://localhost:3080',  // Internal-only routes
};

3.3 Internal-Only Endpoints

Endpoints under /internal/* are never exposed through the external gateway. They are used for:

• Service health checks
• BullMQ job processing
• Database migration triggers
• Cache invalidation

---

4. Service Dependencies

4.1 Startup Order

Services must start in the following order to avoid dependency failures:

Phase 1: Infrastructure
  ├── PostgreSQL
  ├── Redis
  └── Meilisearch

Phase 2: Core Services
  ├── pakashop-config (feature flags needed by all)
  ├── pakashop-gateway (depends on config)
  └── pakashop-backend (depends on config, PostgreSQL, Redis)

Phase 3: Supporting Services (no strict order within phase)
  ├── pakashop-search (depends on Meilisearch)
  ├── pakashop-analytics (depends on PostgreSQL)
  ├── pakashop-notifications (depends on Redis for SSE)
  ├── pakashop-tracking (depends on Redis for Pub/Sub)
  ├── pakashop-moderation (depends on Sightengine API)
  ├── pakashop-recommendations (depends on Redis)
  ├── pakashop-scheduler (depends on Redis for BullMQ)
  ├── pakashop-fraud (depends on PostgreSQL, Redis)
  ├── pakashop-coupon (depends on PostgreSQL, Redis)
  ├── pakashop-loyalty (depends on PostgreSQL, Redis)
  ├── pakashop-whatsapp (depends on Redis for BullMQ)
  ├── pakashop-reports (depends on PostgreSQL, Redis)
  ├── pakashop-reconciliation (depends on PostgreSQL)
  ├── pakashop-invoicing (depends on PostgreSQL)
  ├── pakashop-pricing (depends on PostgreSQL, Redis)
  └── pakashop-settlement (depends on PostgreSQL, Redis)

4.2 Dependency Graph

---

5. Service-Specific Details

5.1 pakashop-gateway (Port 8000)

• Language: Node.js
• Framework: Express with http-proxy-middleware
• Key Responsibilities:
  • Validate x-pakashop-key or x-internal-key
  • Apply rate limiting (Redis-backed)
  • Route requests to upstream services
  • Handle WebSocket upgrades for tracking
  • TLS termination (delegated to Nginx)
• Health Check: GET /health → {"status":"ok","service":"gateway"}

5.2 pakashop-backend (Port 3080)

• Language: Node.js
• Framework: Express + Prisma ORM
• Key Responsibilities:
  • Authentication (JWT + MFA)
  • Order management
  • Product/shop CRUD
  • Payment orchestration (PawaPay + Flutterwave)
  • User management
  • Inventory management
  • Seller application workflow
• Health Check: GET /health → {"status":"ok","service":"backend"}

5.3 pakashop-search (Port 3005)

• Language: Go
• Framework: Standard library + meilisearch-go
• Key Responsibilities:
  • Index product catalog in Meilisearch
  • Handle search queries (typo-tolerant, faceted)
  • Sync index on product create/update/delete
• Health Check: GET /health → {"status":"ok","service":"search"}

5.4 pakashop-tracking (Port 3120)

• Language: Node.js
• Framework: Express + ws (WebSocket library)
• Key Responsibilities:
  • Ingest GPS location updates from agent devices
  • Apply Kalman filter for GPS smoothing
  • Calculate ETA using Haversine formula
  • Geofence detection (400m radius)
  • Redis Pub/Sub for real-time location broadcast
  • WebSocket server for live tracking UI
• Health Check: GET /health → {"status":"ok","service":"tracking","websocket":{"connectedClients":N}}

5.5 pakashop-moderation (Port 3110)

• Language: Python
• Framework: FastAPI + httpx
• Key Responsibilities:
  • Receive image URLs from backend
  • Call Sightengine API (nudity, violence, offensive detection)
  • Apply retry logic (3 attempts, exponential backoff)
  • Return moderation results to backend
• Health Check: GET /health → {"status":"ok","service":"moderation"}

5.6 pakashop-fraud (Port 3006)

• Language: Node.js
• Framework: Express
• Key Responsibilities:
  • Real-time transaction evaluation
  • Velocity checks (payments per IP/hour)
  • Amount anomaly detection
  • Self-dealing detection (buyer = seller)
  • Risk scoring (0-100 composite score)
  • Admin review queue management
• Health Check: GET /health → {"status":"ok","service":"fraud"}

5.7 pakashop-invoicing (Port 3013)

• Language: Node.js
• Framework: Express
• Key Responsibilities:
  • Generate ZRA Smart Invoice payloads
  • Transmit to ZRA VSDC API
  • Mock mode for testing
  • Retry logic (3 attempts, exponential backoff)
  • Per-vendor TPIN validation
• Health Check: GET /health → {"status":"ok","service":"invoicing"}

---

6. Scaling Considerations

Service	Scaling Strategy	Notes
pakashop-gateway	Horizontal (load balancer)	Stateless; sticky sessions for WebSocket
pakashop-backend	Horizontal (load balancer)	Stateless; session data in Redis
pakashop-search	Vertical (Meilisearch scales vertically)	Consider Meilisearch Cloud for large catalogs
pakashop-tracking	Horizontal (sticky sessions)	Kalman filter state per-order per-process
pakashop-moderation	Horizontal	Stateless; Sightengine API is the bottleneck
pakashop-reports	Vertical	PDF generation is CPU-intensive
All others	Horizontal	Stateless with Redis/PostgreSQL

---

For internal use only. Do not distribute outside Pakashop engineering.