Documentation Hub

Welcome to the official documentation for KHOLO, the automated B2B WhatsApp order-processing and ERP integration platform for wholesale and FMCG distributors.

Core Value Proposition: Turn chaotic WhatsApp customer messages, informal trade slang, and voice notes into clean, validated, ready-to-approve ERP sales orders in under 35 seconds.

---

️ Documentation DirectoryCopy Anchor Link

1. ️ Architecture & ConceptsCopy Anchor Link

• System Architecture & Data Flow: End-to-end technical pipeline (Meta WhatsApp $\rightarrow$ Fastify Webhook $\rightarrow$ Redis/Background Task Queue $\rightarrow$ Gemini/OpenAI $\rightarrow$ Vector Database Matcher $\rightarrow$ Sage ERP).
• The Learning Loop & Alias Engine: How KHOLO resolves South African trade jargon, brand abbreviations, packaging units, and learns customer-specific slang dynamically.

2. User Guides (Operations)Copy Anchor Link

• Order Clerk Control Centre Guide: Daily order inbox workflow, 3-tier confidence badges (Green / Amber / Red), "Resolve & Teach" corrections, handling voice notes, and order splitting.
• Warehouse & Dispatch Operations: Accessing the warehouse view, generating standardized pick slips with aisle/bin locations, and packing verification.
• Catalog & Inventory Management: Managing SKUs, multi-tier pricing, pack sizes, stock allocations, safety stock, and manual alias mapping.
• Customer Master & Credit Control: Customer phone number registration (E.164), credit hold enforcement (ACTIVE vs. HOLD), and primary delivery locations.

3. Integrations & ConnectivityCopy Anchor Link

• Sage 200 Evolution ERP Integration: Freedom Service REST SDK connection, Agent credentials, Sales Order payload structure, and idempotency key mapping.
• Meta WhatsApp Cloud API Setup: Business Portfolio verification, dedicated phone number provisioning, permanent system tokens, and webhook configuration.
• Outbound Webhooks & REST API: Subscribing external systems to order events and issuing scoped API keys for custom ERP connectors.

4. Pilot Rollout & OperationsCopy Anchor Link

• The 3-Day Pilot Playbook: The phased operational runbook for onboarding a live distributor: Day 1 (Shadow Mode), Day 2 (Hybrid Clerk Review), Day 3 (Full Live Automation).
• Pre-Flight Verification & Smoke Tests: Running the 5-point automated readiness audit (verify-readiness.ts) and catalog ingestion script (import-pilot-catalog.ts).

5. Developer & DevOps GuideCopy Anchor Link

• Local Development Quickstart: Monorepo layout, Docker Compose setup (PostgreSQL + Vector Database, Redis 7), database migrations, seed scripts, and running dev servers.
• Using the WhatsApp Simulator: Testing text orders and audio voice notes locally without needing a live Meta Cloud API account.
• Production Deployment & Security: Docker Compose production deployment, reverse proxies, environment variables, authentication, audit trails, and POPIA compliance.
• REST API Reference: Comprehensive endpoint catalog for orders, items, products, customers, kiosk mode, and tenant administration.

---

Quick Navigation by RoleCopy Anchor Link

---

️ Support & ContributingCopy Anchor Link

• For security vulnerabilities or suspicious account activities, refer to Production Deployment & Security.
• To run automated tests across API and web: npm test inside apps/api.