01 Executive Summary

Michaelsoft Procurement is a production-grade, multi-tenant procurement orchestration platform purpose-built for small to medium businesses in Kenya and emerging markets. It transforms the fragmented, paper-based procurement lifecycle — supplier sourcing, price negotiation, purchase ordering, goods receiving, invoicing, and reconciliation — into a unified, intelligent, real-time digital workspace.

The system serves as a central nervous system for procurement operations, connecting business owners, purchasing managers, suppliers, and accounting teams through a shared data model with granular role-based access control.

Key Capabilities

	Capability	Description
●	Inventory Management	Product catalog with Excel bulk import, margin analytics, price history
●	Supplier Directory	Contact management, logo uploads, preferred supplier marking, status flags
●	Supplier Price Matrix	Global price book with bulk entry, cheapest-price lookup, margin badges
●	Purchase Orders	Full lifecycle: draft → quoted → allocated → delivered → closed
●	Supplier Quotations	Per-order item pricing via secure shareable links, approval workflow
●	Cost Allocation Engine	Automatic cheapest-supplier allocation across multi-item orders
●	Invoice Management	Multi-order linking, payment status, auto expenditure creation
●	Sales Reconciliation	Daily cash + paybill + POS tracking with variance detection
●	M-Pesa Reconciliation	Daily cash + float + expected amount tracking
●	Executive Dashboard	KPIs, margin pie charts, order trends, quotation comparisons
●	Reports Module	Cost distribution, item allocation, price trends, delivery status
●	Export Hub	PDF and Excel exports for orders, invoices, expenditures, reconciliations
●	Real-Time Chat	1-on-1 and group messaging via Ably with reactions, replies, presence
●	Delegation System	Amber notification dots when teammates create or modify data
●	Granular Permissions	Module:subModule access control via invitation-based permission matrices
●	M-Pesa Payments	Daraja STK Push and IntaSend integration for license purchase/renewal
●	License System	Duration tiers (1 month to lifetime), auto-activation, expiration countdown
●	Demo Mode	Multi-industry fixture data (pharmacy, food, hardware, retail, fashion)

Technology Stack

---

02 The Procurement Challenge

2.1 The Problem Space

Small and medium businesses in emerging markets face a distinct set of procurement challenges:

Fragmented Data. Supplier price lists sit in WhatsApp messages, handwritten notebooks, and scattered spreadsheets. There is no single source of truth for what items cost across different vendors.

Manual Allocation. Choosing which supplier to buy each item from requires manually comparing prices across multiple quotations — a laborious, error-prone process that discourages proper price comparison.

Delayed Visibility. Business owners learn about stock deliveries, invoice statuses, and cash positions days or weeks after the fact. There is no real-time operational picture.

Trust Deficit. In delegated procurement environments (owner → purchasing manager), the owner has limited visibility into pricing decisions and supplier selections, leading to micromanagement or unchecked spending.

Payment Fragmentation. Licensing and subscription payments must work through M-Pesa — Kenya’s dominant mobile money platform — which adds integration complexity not addressed by global SaaS payment solutions.

No Graceful On-Ramp. Procurement software typically requires a full subscription commitment before users can evaluate whether the system fits their workflow.

2.2 Design Principles

Michaelsoft Procurement was designed around five core principles:

1. Offline-Resilient UX. Kenya’s internet connectivity is variable. The system uses optimistic UI updates extensively — every mutation is reflected instantly in the interface, with background reconciliation against the server.

2. Supplier-First Architecture. Unlike traditional procurement systems that treat suppliers as secondary metadata, this platform elevates suppliers to first-class entities with their own portal (via secure quotation links), delivery tracking, and price submission workflows.

3. Real-Time by Default. Every state change — a new quotation, a delivery confirmation, a chat message — propagates instantly to all authorized participants via Ably WebSocket channels. There is no "refresh to see updates."

4. Graceful Licensing. Unlicensed users can explore a full-featured multi-industry demo environment with realistic fixture data. The read-only mode for expired licenses ensures data is never locked away.

5. Mobile-First for Emerging Markets. The interface is responsive and optimized for the smaller screens and slower connections typical of African SMB environments.

---

03 System Architecture Overview

3.1 High-Level Architecture

---

04 Core Domain Model

4.1 Entity Relationship Diagram

Core procurement entities and their relationships

Financial & accounting entities

Licensing, chat & access entities

4.2 Entity Definitions

Products

The central catalog entity. Products have a name (stored in UPPERCASE for consistent lookups), selling_price (the retail price), buying_price (the cost price from suppliers), and unit (the unit multiplier, e.g., 100 for a pack of 100 tablets).

The marginStatus is a computed field derived from the buying and selling prices:

Suppliers

Contacts with status tracking (active, inactive, on_hold), optional logo uploads (stored in Supabase Storage), and a is_preferred flag for quick reference.

Supplier Prices (Global Price Matrix)

A many-to-many relationship between products and suppliers storing unit_price and out_of_stock status. This is the "price book" — the global reference for what each supplier charges for each product.

Orders

The core workflow entity. Orders have a unique human-readable ref (generated as ORD-XXXX), a date, notes, and a status that progresses through a state machine (see Section 5).

Orders belong to a user_id (the effective business owner) and track created_by (the specific user who created it) for audit purposes.

Order Items

Line items within an order, linking to a product with a quantity and selling_price (the price at which the business intends to sell the item).

Order Supplier Prices (Quotation-Scoped Prices)

This is the system’s most sophisticated data structure. It captures:

• order_id, product_id, supplier_id: The unique combination
• unit_price: The price quoted by this supplier for this item in this order
• previous_unit_price: The price from the most recent previous quotation (for trend tracking)
• out_of_stock, delivered: Fulfillment tracking at the item-supplier level
• is_selected: Manual override to select a non-cheapest supplier
• price_updated_at: When this specific price was last changed
• source: ‘manual’ or ‘submission’ (from supplier portal)
• submission_id: Links to the supplier’s quotation submission

Supplier Price Submissions

A secure, token-gated mechanism for suppliers to submit prices:

• submission_token: A unique UUID sent to the supplier via a shareable link
• token_expires_at: Token validity window (default 24 hours)
• status: pending → under_review → approved | rejected
• Items: Individual product prices submitted by the supplier

Invoices & Expenditures

Invoice records link to one or more orders via order_ids (JSON array). When an invoice is created, the system can optionally auto-create a linked expenditure record, connecting the procurement and accounting sides of the business.

License Keys & Subscription Orders

The monetization layer. License keys have a duration (1 month, 3 months, 6 months, 1 year, lifetime), a status (active, used, expired, paused, suspended, revoked), and an expires_at timestamp. Subscription orders capture the payment intent via M-Pesa STK Push.

Profiles & Invitations

The multi-tenant access control system. Users have a role (admin, user, invited) and invited_by to establish the delegation hierarchy. Invitations carry a permission matrix — a JSON array of Category:Permission strings that gate access to every UI section.

Chat Messages

Real-time messages with delivery tracking:

• delivery_state: sending → sent → delivered → read (for DMs)
• Group messages use aggregate delivered_count / read_count / member_count
• Reactions: JSON object mapping emoji → array of user IDs
• Reply chain: reply_to_id with a cached reply_to snapshot for offline access

---

05 Order Lifecycle & State Machine

5.1 State Transitions

5.2 Effective Status Computation

The system uses a dual-status model. The database stores the canonical status (set by the user/process), but the UI computes an effective status via getEffectiveOrderStatus() that reflects the actual delivery state based on item-level data:

function getEffectiveStatus(order, orderPrices) {
  // Closed and Draft pass through
  if (order.status === 'closed') return 'closed';
  if (order.status === 'draft') return 'draft';

  // Analyze each item's fulfillment state
  const fulfillmentItems = order.items.map(item => {
    const itemPrices = orderPrices.filter(p => p.productId === item.productId);
    const deliveredPrice = itemPrices.find(p => p.delivered);
    const selectedPrice = deliveredPrice || itemPrices.find(p => p.isSelected);
    const winningPrice = selectedPrice || cheapestPrice(itemPrices);
    return { item, winningPrice };
  });

  const anyDelivered = fulfillmentItems.some(x => x.winningPrice?.delivered);
  const anyPending = fulfillmentItems.some(x => !x.winningPrice?.delivered);

  if (anyDelivered && anyPending) return 'partial';
  if (anyDelivered) return 'delivered';
  return order.status; // Fall through to quoted/allocated
}

This computation ensures that even if a user forgets to update the order status, the dashboard and reports always reflect the true operational state.

5.3 Order Audit Trail

Every significant order mutation is logged to order_audit_logs:

interface OrderAuditLog {
  id: string;
  orderId: string;
  orderRef: string;
  actionType: 'EDIT' | 'DELETE' | 'CLOSE';
  reason: string;        // User-provided reason for the change
  userId: string;
  userName: string;
  createdAt: string;
}

The audit trail is visible from the Reports page and serves as a compliance record for procurement decisions.

---

06 Supplier Quotation Engine

6.1 Architecture

The supplier quotation system enables procurement teams to securely share order details with suppliers and receive priced quotations — without the supplier needing an account on the platform.

6.2 Secure Link Generation

When a procurement user clicks "Generate Link" for a supplier:

1. The system creates a supplier_price_submissions record with a unique UUID token
2. A cryptographically random 32-char hex submission_token is generated server-side
3. The link format is: https://procurement.michaelsoft.co.ke/supplier-quote/{token}
4. The link auto-copies to the clipboard
5. The token expires after 24 hours (configurable)

// Token generation (server-side)
const submissionToken = crypto.randomUUID();
const tokenExpiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours

6.3 Supplier Price Submission Portal

The supplier-facing page is a lightweight, no-auth form that displays:

• The order reference number
• A list of products with quantity fields
• Price input fields with KSH formatting
• Optional notes per item
• Review and submit actions

Submitted data flows through Zod validation and rate limiting before being written to the database.

6.4 Approval Workflow

When a submission is approved:

1. All submitted prices are written to order_supplier_prices via upsert
2. The order’s status is updated (at least one item now has a price → quoted)
3. The supplier’s previous unit_price is preserved in previous_unit_price
4. A delegation notification is created for the approval action

6.5 Price Comparison Matrix

The dashboard features a "Quotation Comparison" matrix that displays, for each product in an order, the prices from all suppliers who have quoted:

Product	Supplier A	Supplier B	Supplier C
Item 1	KSH 1,200	KSH 1,350	KSH 1,180
Item 2	KSH 800	KSH 750	KSH 850
Item 3	KSH 2,000	KSH 2,200	KSH 1,950
Cheapest	1 item	1 item	1 item

Green = Cheapest price for this product

6.6 Allocation Engine

The cheapest-supplier allocation logic:

function allocateOrder(order, orderPrices) {
  for (const item of order.items) {
    const cheapest = findCheapestSupplier(item.productId, orderPrices);
    if (cheapest) {
      allocate(item, cheapest);
    }
  }
}

For each product, the engine:

1. Prioritizes delivered prices (already fulfilled by this supplier)
2. Falls back to manually selected (is_selected) prices
3. Falls back to cheapest available price
4. Excludes out-of-stock items
5. Returns a structured allocation report showing which supplier gets which items, total values, and coverage percentages

---

07 Financial Reconciliation Framework

7.1 Sales Reconciliation

The sales reconciliation module tracks daily sales across three channels:

Date	Cash	Paybill	POS Total	Variance
2026-06-15	25,000	12,000	35,000	+2,000
2026-06-14	22,000	15,000	38,000	-1,000
2026-06-13	28,000	10,000	36,000	+2,000

Variance = (Cash + Paybill) − POS Total. Positive = more cash collected than expected. Negative = cash shortage (requires investigation).

7.2 M-Pesa Reconciliation

Tracks mobile money agent float against expected balances:

Date	Cash	Float	Expected	Total	Variance
2026-06-15	28,000	50,000	80,000	78,000	-2,000
2026-06-14	32,000	50,000	80,000	82,000	+2,000

7.3 Invoice-Expenditure Linkage

Invoices and expenditures are bidirectionally linked:

// When an invoice is created:
const invoice = await createInvoice(data);
if (createExpenditure) {
  await createExpenditure({
    date: invoice.date,
    description: `Invoice ${invoice.invoiceNumber} - ${invoice.company}`,
    amount: invoice.amount - invoice.discount,
    category: 'Purchase',
    invoiceId: invoice.id,
    paid: invoice.paid,
  });
}

// When an invoice's paid status changes:
// → Linked expenditure is auto-updated in the background
// → Dashboard profit calculation reflects the change instantly

This ensures the profit calculation on the executive dashboard (Revenue − Expenditure = Potential Profit) is always accurate without manual double-entry.

---

08 Real-Time Collaboration Infrastructure

8.1 Architecture

Real-time features are powered by Ably Realtime (WebSocket), replacing an earlier Supabase Realtime implementation that proved unreliable for chat workloads.

8.2 Channel Layout

Channel	Events	Purpose
chat:{hostId}	message	New message persistence & broadcast
chat:{hostId}	reaction	Reaction add/remove
chat:{hostId}	delivery	DM delivery state changes
chat:{hostId}	delivery_count	Group message aggregate counts
typing:{hostId}	typing	Ephemeral typing indicators

8.3 Message Delivery Tracking

The system implements a dual delivery tracking model:

Direct Messages (1-on-1):

Group Messages:

Idempotent Message Sending: Each message send includes a clientNonce — a unique 32-character hex string generated client-side. The server uses (sender_id, client_nonce) as a unique constraint, ensuring that network retries never create duplicate messages.

8.4 Presence System

The presence system tracks online/offline status with three layers:

1. Ably Presence: Real-time enter/leave/update events on the chat channel
2. DB Heartbeat: A 30-second setInterval writes last_seen_at to the profiles table
3. Leave Handling: On page unload, the system calls presence.leave() AND writes last_seen_at to DB as a fallback

When a user comes back online, a background task identifies unacknowledged messages and publishes delivery events for them.

8.5 Delegation Notifications

When an invited user creates or modifies data, an amber notification dot appears in the inviter’s sidebar:

The system intelligently routes notifications:

• Invited user → Host: Always notifies
• Host → Delegates: Only notifies for shared sections (products, suppliers, prices), NOT for personal sections (orders, expenditures, reconciliation)

---

09 Licensing & Monetization

9.1 License Model

9.2 Duration Tiers

Duration	Use Case	Price Point
1 month	Monthly subscription	Low
3 months	Quarterly commitment	Mid-High
6 months	Semi-annual	High
1 year	Annual commitment	Higher
Lifetime	Perpetual license	Premium

9.3 Read-Only Mode

When a license expires, is paused, or is revoked, the system enters read-only mode:

// Event listener on the dashboard layout
document.addEventListener('click', handleBlockedClick, true);

function handleBlockedClick(event) {
  // Allow sidebar, chat, pagination, and sign-out
  // Block all other interactive elements
  // Show "License Required" toast with shake animation
}

This ensures businesses never lose access to their data, even when payment lapses.

9.4 Payment Integration

Two payment providers are supported:

Safaricom Daraja API (Primary):

---

10 Multi-Industry Demo Environment

10.1 Architecture

The demo mode provides a full-featured environment for prospective users to evaluate the system without a license:

// Demo mode determination (synchronous, safe anywhere)
function isDemoMode(): boolean {
  return (
    !authState.isInitializing &&
    authState.hasLicenseKey === false &&
    !authState.isAdmin &&
    licenseStatus === 'none' &&
    demoState.isDemoOptedIn === true
  );
}

10.2 Industry Datasets

Industry	Example Products	Suppliers
Pharmacy	Paracetamol, Amoxicillin, Metformin	Pharmacy Solutions Ltd, Global Pharma Distributors
Food & Grocery	Rice 5kg, Cooking Oil 2L, Wheat Flour	Food Solutions Ltd, Metro Wholesalers
Hardware	Cement 50kg, Steel Rebar, Gloss Paint	Hardware Solutions Ltd, Global Hardware Distributors
Retail	LED TV 43", Bluetooth Headphones, Kettle	Retail Solutions Ltd, Metro Retail Wholesalers
Fashion	Denim Jeans, Cotton T-Shirts, Sneakers	Fashion Solutions Ltd, Global Apparel Distributors

10.3 Dataset Characteristics

Each industry dataset includes:

• 7 products with realistic pricing (including one loss-making item and one without a selling price)
• 3 suppliers with varied pricing tiers
• 5 orders in different states (draft, quoted, allocated, partial, delivered)
• 5 invoices with mix of paid/pending statuses
• 5 expenditures linked to invoices or standalone
• 7 days of sales reconciliation data
• 7 days of M-Pesa reconciliation data

10.4 Switching Experience

When a user switches industries, the system:

1. Clears all Zustand stores
2. Loads the new industry’s fixture data
3. Shows a full-screen overlay with spinner during the transition
4. All charts and reports reflect the new data instantly

---

11 Security & Governance

11.1 Authentication

The system uses Supabase Auth with Google OAuth (PKCE flow):

11.2 Authorization Model

Role Hierarchy:

Admin: Bypasses all license checks. Can manage users, invitations, license keys, and view all data.

Owner: Has full access by default. Can invite teammates with granular permissions.

Invited User: Access gated by permission matrix from their invitation.

11.3 Permission System

Permissions are structured as Category:Permission strings:

// Example permission matrix for an invited user
[
  "General",              // Category-level: grants access to ALL General sub-modules
  "General:Dashboard",    // Module-level: grants access to Dashboard specifically
  "Inventory:Products",
  "Inventory:Suppliers",
  "Sales:Orders",
  "Accounts:Invoices",
  "Analytics:Reports"
]

Permission checking:

11.4 Row-Level Security (Supabase RLS)

All database tables have Supabase RLS policies that restrict access to:

• The user’s own data (where user_id = auth.uid())
• Data belonging to the effective host (user_id = getEffectiveUserId())
• Admin access via service client (API routes)

11.5 Server-Side License Enforcement

API routes use requireLicense() middleware:

11.6 Rate Limiting

Applied to: quotation link generation (10/minute), email sending (5/minute), chat messages (30/minute).

11.7 Input Validation

All API boundaries use Zod schemas:

// Example: Chat message validation
const chatMessageSchema = z.object({
  content: z.string()
    .min(1, 'Message cannot be empty')
    .max(5000, 'Message too long'),
  groupId: z.string().uuid().optional(),
  replyToId: z.string().uuid().optional(),
});

// Example: Payment initiation
const initiatePaymentSchema = z.object({
  pricingTierId: z.string().uuid('Invalid pricing tier ID'),
  phoneNumber: z.string()
    .transform(s => s.replace(/\D/g, ''))
    .refine(s => s.length === 10 || s.length === 12, 'Invalid phone'),
});

---

12 Performance & Scalability

12.1 Data Fetching Strategy

The system employs a stale-while-revalidate pattern for data fetching:

12.2 Optimistic Updates

All mutation operations follow this pattern:

async function updateOrder(id, updates) {
  // 1. Snapshot current state
  const snapshot = get().orders;

  // 2. Apply optimistic UI update
  set(state => ({
    orders: state.orders.map(o =>
      o.id === id ? { ...o, ...updates } : o
    ),
  }));

  try {
    // 3. Persist to DB
    await supabase.from('orders').update(dbUpdates).eq('id', id);
  } catch (error) {
    // 4. Rollback on failure
    set({ orders: snapshot });
    throw error;
  }
}

12.3 Large Dataset Handling

Products use pagination-through for large catalogs:

// Fetch all products in 1000-record chunks
let from = 0;
let to = 999;
let hasMore = true;

while (hasMore) {
  const { data: chunk } = await supabase
    .from('products')
    .select()
    .range(from, to);

  if (chunk.length === 1000) {
    from += 1000; to += 1000;
  } else {
    hasMore = false;
  }
}

12.4 Real-Time Performance

• Ably WebSocket: Single persistent connection per client
• Heartbeat interval: 30 seconds
• Typing indicator timeout: 3 seconds auto-clear
• Message size limit: 60 KB (Ably’s 64 KB limit with safety margin)
• Presence updates: Batched and debounced

12.5 Database Indexes

Key performance indexes (from migration scripts):

• orders(user_id, date DESC) — Dashboard recent orders
• order_items(order_id) — Item lookups
• order_supplier_prices(order_id, product_id, supplier_id) — Price lookups (unique constraint)
• chat_messages(host_id, created_at DESC) — Chat history queries
• profiles(invited_by) — Delegate lookups

---

13 Deployment & Operations

13.1 Deployment Architecture

13.2 Environment Configuration

13.3 Backup Strategy

The scripts/db-backup.sh script provides automated backups:

• Full database dump
• Schema-only dump
• Data-only dump
• Auth users dump (separate, for GDPR compliance)
• 7-day retention with rotation
• Optional S3 upload for offsite storage

13.4 Security Headers

const securityHeaders = [
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
];

---

14 Roadmap

Achieved (v1.0)

In Progress

• Multi-language support (Swahili, French for regional expansion)
• Mobile native app (React Native)
• Advanced analytics (ML-based demand forecasting, anomaly detection)
• Supplier self-service portal (full account creation, not just token-based)
• Bulk order processing (CSV upload for multi-item multi-supplier orders)

Future

• POS Integration (direct connection to point-of-sale systems for automatic sales data capture and inventory sync)
• Procurement API (RESTful API for third-party integrations)
• Inventory barcode scanning (camera-based SKU recognition)
• Automated reorder triggers (low-stock alerts with auto-PO generation)
• Multi-currency support (USD, EUR for cross-border procurement)
• Advanced contract management (volume discounts, tiered pricing)
• ESG compliance tracking (supplier sustainability scores)
• Offline-first PWA (service worker with IndexedDB sync)

---

Appendix A: Key Performance Indicators

The executive dashboard computes the following KPIs:

	KPI	Formula	Source
●	Revenue	Σ(Cash + Paybill) for period	Sales Reconciliation
●	Total Expenditure	Σ(Amount) for period	Expenditures
●	Potential Profit	Revenue − Expenditure	Computed
●	Active Orders	Count of orders in period	Orders
●	Good Margin Products	Count where marginStatus = ‘good’	Products
●	Supplier Coverage	(Items with prices / Total items) × 100	Order Prices
●	Delivery Rate	(Delivered orders / Total allocated) × 100	Orders

Appendix B: PDF Export Templates

The system generates professional PDFs using client-side HTML + window.print():

	Template	Content	Purpose
●	Quotation Request	Items with blank price columns	Share with suppliers
●	Purchase Order	Allocated items by supplier with prices	Issue to suppliers
●	Invoice	Multi-order billing with items	Send to clients
●	Invoice Report	All invoices with summaries	Accounting
●	Expenditure Report	All expenses categorized	Financial review
●	Product Price List	Catalog with margin analysis	Internal review
●	Product Analysis	Single product with price trend	Deep dive
●	Allocation Summary	Cheapest supplier by item	Procurement decision
●	Orders List	All orders with item details	Operations
●	Sales Reconciliation	Daily sales with variances	Daily close
●	M-Pesa Reconciliation	Mobile money daily tracking	Financial control

Appendix C: Data Flow Summary

Real-Time Data Flow (Chat):

---

☽☼ ↑