A full-stack subscription scheduling, routing, and operations system for commercial kitchens, featuring automated calendar compensations and route optimization for Addis Ababa.
Commercial meal subscription services face complex logistical hurdles:
- Dynamic Scheduling: Handling religious fasting periods (e.g., Orthodox fasting) and menu preferences (hybrid/fasting/non-fasting) dynamically.
- Calendar Exceptions: Processing holidays and kitchen closures while automatically generating compensatory delivery extensions on subsequent working days.
- Dispatch Logistics: Coordinating drivers and optimizing delivery routes across a sprawling city.
Oz Kitchen solves this with a deterministic scheduling engine and dynamic route optimization, integrated into a unified portal simulating the customer, administrative, and driver workflows.
The project is structured into three specialized portals, backed by a unified heuristic engine:
- Telegram Mini-App Client: Emulates the mobile customer interface, allowing users to subscribe, choose dietary preferences (Fasting, Non-Fasting, Hybrid), customize menus, track orders, and upload Telebirr payment screenshots.
- Kitchen & Admin Dashboard: A control panel for kitchen managers to track daily prep metrics, log operational holidays/closures, manage menus, track the active driver fleet, and review customer subscriptions.
- OzDrive Driver Dispatch Portal: A delivery worker companion that tracks driver location, maps drops in real-time, and optimizes delivery sequences.
- Calendar Compensation & Scheduling Heuristics: The core engine that calculates delivery schedules and inserts offsets/extensions based on kitchen availability rules.
This project is a TypeScript monorepo combining a modern React frontend and a robust Express backend.
┌──────────────────────────────────────────────────────────────┐
│ Vite Dev Server (Frontend) │
│ ┌───────────────────┬─────────────────┬────────────┐ │
│ │ Telegram Mini-App │ Admin Dashboard │ OzDrive │ │
│ └───────────────────┴─────────────────┴────────────┘ │
└──────────────────────────────┬───────────────────────────────┘
│ JSON API / Port 3000
┌──────────────────────────────▼───────────────────────────────┐
│ Express Backend Server │
│ ┌───────────────────────────────────────────────┐ │
│ │ Calendar Compensation Engine │ │
│ ├───────────────────────────────────────────────┤ │
│ │ Route Sequence Optimization (TSP) │ │
│ └───────────────────────┬───────────────────────┘ │
└───────────────────────────────┼──────────────────────────────┘
│ pg pool connection
┌───────────────────────────────▼──────────────────────────────┐
│ PostgreSQL Database │
└──────────────────────────────────────────────────────────────┘
- Frontend: React 19, Vite 6, Tailwind CSS 4, Lucide React (icons), Motion (micro-animations).
- Backend: Express 4, Node.js, TSX (TypeScript execution).
- Database: PostgreSQL 16 with the
pgclient pool.
This repository features two notable computer science implementations addressing real-world domain logic:
Located in src/utils/calendar.ts, this module implements:
generateDeliveryTasks: A pure function that calculates active delivery tasks by scanning subscription ranges, skipping kitchen holidays/closures, and calculating the exact offsets to prepend "compensatory deliveries" on subsequent open weekdays.isFastingDay: Processes hybrid subscription logic, resolving Wednesday/Friday fasting days alongside floating kitchen fasting period exceptions.
Located in src/components/DriverApp.tsx, the driver dispatch portal implements route sequencing:
- Translates Addis Ababa districts (Bole, Wollo Sefer, Kazanchis, Piassa, Mexico, Saris, CMC) to coordinate mappings.
- Computes distances using Havesine-like approximations.
- Runs a Greedy Nearest Neighbor Traveling Salesman heuristic to sort deliveries, presenting drivers with optimized
📍 Stop #1,📍 Stop #2sequences and displaying total mileage savings.
- server.ts — Main Express backend server defining APIs.
- db.ts — PostgreSQL wrapper and helper functions.
- schema.sql — PostgreSQL database schemas.
- seed.ts — Seeding file initializing dummy database content.
- src/ — Single-page React application containing layouts, components, context, and calendar utils.
- Node.js (v18 or higher)
- PostgreSQL database service (running locally or remotely)
Copy .env.example to .env and fill out your variables:
cp .env.example .env| Variable | Description | Default |
|---|---|---|
PORT |
Local server port for Express (reverse-proxied traffic) | 3000 |
DATABASE_URL |
PostgreSQL connection string | postgres://oz_admin:oz_password_2026@localhost:5432/oz_kitchen |
JWT_SECRET |
Token secret for security | oz-kitchen-secret-2026 |
GEMINI_API_KEY |
Optional API key for generative features | your_gemini_api_key_here |
Build schemas and seed initial data using the CLI tool:
npx tsx seed.tsStart the development build. This launches the Express server and Vite frontend concurrently:
npm run devVisit the app in your browser at http://localhost:3000.
- Administrative Slate: Sleek, clean off-white canvas (
bg-slate-50) using high-contrast slate headers and charcoal borders to represent a modern back-office feel. - Mobile Cosmetology: Both the Telegram Mini-App and the Driver dispatch portal use high-contrast dark panels (
bg-slate-900) tailored to simulate mobile device viewport frames and minimize distraction during active operations.
This project is licensed under the MIT License - see the LICENSE details for info. MIT © 2026 Oz Kitchen.