Technical Architecture

Kolshee is not an application stack. It is a cognitive stack. Each layer perceives a different scale; the policy engine reconciles them into a single coherent action.

The system reads the chain from its tail, not its head. A scan at the register updates a household-level demand vector, rolls into a block-level read, and produces a pooled purchase recommendation across stores sourcing from the same importer. The same signal travels further up: forecast container size, suggested ETA window, factory production slot. Physical movement stays with operators already in the market; what we own is the decision layer that ties them together.

The Brain is structured to mirror the three scales at which food commerce operates: the household, the storefront, and the planet. Each layer ingests events, emits inferences, and exposes APIs to the layers above and below it.

• ▸Perception: app interactions, receipts, household composition signals, cultural-calendar features, substitution behavior.
• ▸Inference: per-household demand vectors, replenishment cadence, price elasticity, basket-completion probability.
• ▸Output: reorder suggestions, "skip / save" prompts, intelligent batching with neighbors, surfaced Heritage SKUs.

The store is not a POS terminal with an AI layer on top. It is a complete business intelligence node that emits operational signals across six categories simultaneously.

Perception — what the store layer reads:

• ▸POS scans: every product sold, price, quantity, timestamp.
• ▸Purchase records: every product bought, supplier, unit cost, date.
• ▸Inventory events: restocks, expiry, returns, damaged goods, write-offs.
• ▸HR signals: clock-in/out events, shift assignments, performance records.
• ▸Operating costs: rent cycles, utility readings, payroll runs, miscellaneous expense entries.
• ▸Physical signals: smart-shelf weight & RFID, refrigeration telemetry, door sensors, camera-based shelf occupancy.

Inference — what the store layer produces:

• ▸Gross margin per SKU: real-time, updated on every sale and every purchase.
• ▸Labour efficiency: revenue per staff hour, by shift, by employee.
• ▸Operating cost ratio: total operating cost as percentage of revenue, tracked daily.
• ▸Waste forecast: products approaching expiry with insufficient remaining velocity to clear before the date.
• ▸Supplier price drift: whether a supplier's unit cost has changed over time for the same SKU.
• ▸Dead-shelf detection: shelf sections or SKU slots with zero velocity over a configurable window.

Output — what the store layer does:

• ▸Full income & expense ledger, continuously updated.
• ▸Employee scheduling recommendations based on demand forecasts.
• ▸Automatic payroll calculation from clock-in/out records.
• ▸Supplier invoice reconciliation against purchase orders.
• ▸Daily P&L summary pushed to the store-owner dashboard.
• ▸Cross-store price-anomaly alerts when the network detects the store is overpaying for a SKU.

• ▸Perception: importer manifests, factory output, farm yield estimates, FX rates, port congestion, customs latency, weather, conflict signals.
• ▸Inference: lane health, supplier reliability, landed cost projection, geopolitical risk, harvest forecast.
• ▸Output: sourcing recommendations, cross-border lane selection, hedging triggers, alternate-supplier failover.

Layered cognition is necessary but not sufficient. The Brain becomes useful only when a unified policy engine can take the three perception streams and emit a single coordinated action: "Order 220 kg of basmati from Lane B, route via NYC, pre-position 420 kg at the Quincy mesh node by Thursday 0800, drop the in-app price by 4.2% to clear remaining stock, alert the staffing model to add one shift Friday."

The engine is a hybrid of supervised forecasters (gradient-boosted demand models per SKU × geo × time), a reinforcement-learning scheduler for inventory + logistics, and an LLM-based planner for the long-tail merchant-facing actions and exception handling.

Every node in the system writes to a single append-only event log (Kafka-style) keyed by store, SKU, lane, household, and supplier. Downstream processors include forecasters, anomaly detectors, regulators, and the policy engine. The log is the single source of truth; all surfaces are projections.

type KolsheeEvent =
  | { kind: "scan"; storeId: string; sku: string; qty: number; price: number; ts: number }
  | { kind: "reorder"; storeId: string; sku: string; qty: number; supplierId: string; ts: number }
  | { kind: "expire"; storeId: string; sku: string; qty: number; ts: number }
  | { kind: "shipment"; lane: string; supplierId: string; payload: SkuQty[]; eta: number }
  | { kind: "household.signal"; hhId: string; vec: number[]; ts: number }
  | { kind: "supply.tick"; supplierId: string; reliability: number; landedCost: number; ts: number }
  // L2 · Store Business Intelligence events
  | { kind: "purchase"; storeId: string; sku: string; supplierId: string; unitCost: number; qty: number; invoiceId: string; ts: number }
  | { kind: "expense"; storeId: string; category: string; amount: number; period: string; ts: number }
  | { kind: "hr.clockin"; storeId: string; employeeId: string; shiftId: string; ts: number }
  | { kind: "hr.clockout"; storeId: string; employeeId: string; hoursWorked: number; ts: number }
  | { kind: "price.anomaly"; storeId: string; sku: string; storePaid: number; networkMedian: number; potentialSaving: number; ts: number }
  | { kind: "demand.gap"; storeId: string; sku: string; searchCount: number; stockLevel: number; nearestSupplier: string; ts: number };

Each store is a sensor node. Edges between stores represent shared cohorts (same metro, same diaspora cluster, same lane). The AI sits at the center of a mesh whose density determines forecast accuracy. Beyond a critical density (~35% of stores in a corridor), the marginal store contributes more to the system than it costs to onboard.

The fourth cognitive layer operates at last-mile delivery. Where L1–L3 coordinate supply upstream, L4 coordinates delivery downstream — across platforms that do not currently share operational state. Kolshee does not own drivers. It coordinates the drivers that DoorDash, Uber Eats, Instacart, and independent fleets already have, making every active driver more productive and every delivery cheaper.

01 · Cross-Platform Order Batching. A DoorDash driver waiting at a restaurant; an Uber Eats order at the same restaurant heading the same direction. The mesh proposes a match. One driver completes both. Each platform pays Kolshee a coordination fee smaller than the cost of a dedicated second dispatch.

02 · Wait-Time Utilisation. When a driver idles at a restaurant, the mesh scans for nearby pickups on any connected platform heading the same direction and assigns the secondary task. The driver earns during dead time. Repeated delays reduce the offending restaurant's priority — a commercial incentive without regulatory intervention.

03 · Supply-Side Driver Redistribution. When a restaurant has three orders ready and no nearby drivers, the mesh draws available drivers from adjacent zones across any connected platform. Ready orders clear; drivers earn without added mileage; platforms improve completion rates at no added cost.

• ▸Platforms: lower cost per delivery on matched routes.
• ▸Drivers: 30–50% higher earnings per active hour.
• ▸Customers: 10–20% lower delivery fees on matched orders.
• ▸Kolshee: coordination fee on every successful match.

Legal note: platform integration requires API partnership agreements and review of contractor classification in each state of operation (MA, CA, NY) before Phase 3 activation.

// L4 · Cross-Platform Logistics Mesh
type LogisticsMeshEvent =
  | { kind: "driver.wait"; driverId: string; restaurantId: string; platformId: string; estimatedWaitMins: number; ts: number }
  | { kind: "match.proposed"; orderId1: string; orderId2: string; driverId: string; platform1: string; platform2: string; directionScore: number; ts: number }
  | { kind: "match.accepted"; matchId: string; platform1Fee: number; platform2Fee: number; driverBonus: number; kolsheeFee: number; ts: number }
  | { kind: "restaurant.delay"; restaurantId: string; orderId: string; delayMins: number; platformId: string; ts: number };