# wityliti/witylogix architecture

> Architecture diagram of the GitHub repository wityliti/witylogix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wityliti/witylogix
- Repository: https://github.com/wityliti/witylogix

## Overview

Witylogix is a multi-tenant, open-source e-commerce delivery logistics platform. Its central workflow spans checkout pricing and order intake, route planning and dispatch, driver execution with proof of delivery, and customer tracking. The API server registers domain routes and provides real-time and background-work infrastructure; separate dashboard, driver, and tracking apps serve operators, drivers, and customers. The README documents broad product capabilities, while sampled source confirms only selected runtime connections; unsupported implementation links are omitted.

Main entry points: [`apps/api/src/routes/routes.ts`](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/routes.ts) (Routes & Stops), [`apps/api/src/server.ts`](https://github.com/wityliti/witylogix/blob/main/apps/api/src/server.ts) (Fastify API), [`apps/api/src/lib/queue.ts`](https://github.com/wityliti/witylogix/blob/main/apps/api/src/lib/queue.ts) (Background Jobs), [`apps/tracking-page/src/App.tsx`](https://github.com/wityliti/witylogix/blob/main/apps/tracking-page/src/App.tsx) (Public Tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Platform"]
  node_api_server["Fastify API<br/>[server.ts]"]
  node_realtime["Live Updates<br/>[socket.ts]"]
  node_job_queue["Background Jobs<br/>[queue.ts]"]
  node_notification_worker["Notification Worker"]
end

subgraph group_logistics["Delivery Operations"]
  node_order_routes["Order Management<br/>[orders.ts]"]
  node_route_planning["Routes &amp; Stops<br/>[routes.ts]"]
  node_tracking_routes["Delivery Tracking<br/>[tracking.ts]"]
  node_pod["Proof of Delivery"]
  node_zones["Zone Pricing<br/>[zones.ts]"]
  node_returns["Returns / RMA<br/>[returns.ts]"]
  node_analytics["Analytics<br/>[analytics.ts]"]
end

subgraph group_clients["User Applications"]
  node_dispatch["Dispatch Dashboard<br/>[page.tsx]"]
  node_customer_portal["Customer Portal<br/>[page.tsx]"]
  node_tracking_page["Public Tracking<br/>[App.tsx]"]
  node_driver_app["Driver Mobile App<br/>[RoutesScreen.tsx]"]
end

subgraph group_extensions["Commerce &amp; Integrations"]
  node_checkout_rates["Checkout Rates<br/>[rates.ts]"]
  node_integrations["Integration Catalog<br/>[integrations.ts]"]
  node_shopify_webhooks["Shopify Webhooks"]
end

subgraph group_engines["Domain Engines"]
  node_workflow_engine["Workflow Engine<br/>[engine.ts]"]
  node_optimization["Route Optimization"]
  node_search["Full-Text Search<br/>[search-engine.ts]"]
  node_fleet["Fleet Management"]
  node_crm["CRM Sync"]
end

node_merchant(("Merchant / Dispatcher"))
node_customer(("Customer"))
node_driver(("Driver"))

node_merchant -->|"manages deliveries"| node_dispatch
node_customer -->|"tracks delivery"| node_tracking_page
node_driver -->|"executes route"| node_driver_app
node_api_server -->|"registers routes"| node_order_routes
node_api_server -->|"registers routes"| node_route_planning
node_api_server -->|"registers routes"| node_tracking_routes
node_api_server -->|"initializes sockets"| node_realtime
node_api_server -->|"shuts down queues"| node_job_queue
node_route_planning -->|"enqueues jobs"| node_job_queue
node_route_planning -->|"publishes updates"| node_realtime
node_tracking_page -.->|"loads tracking"| node_tracking_routes
node_tracking_page -->|"receives live updates"| node_realtime
node_driver_app -.->|"loads routes"| node_route_planning
node_checkout_rates -.->|"uses zone pricing"| node_zones
node_shopify_webhooks -.->|"forwards order updates"| node_order_routes
node_notification_worker -->|"consumes jobs"| node_job_queue
node_workflow_engine -.->|"orchestrates work"| node_job_queue
node_returns -.->|"runs return lifecycle"| node_workflow_engine
node_optimization -.->|"optimizes routes"| node_route_planning
node_pod -.->|"updates delivery status"| node_tracking_routes
node_integrations -.->|"configures commerce"| node_shopify_webhooks
node_search -.->|"searches orders"| node_order_routes
node_analytics -.->|"reports performance"| node_route_planning
node_fleet -.->|"supports fleet operations"| node_dispatch
node_crm -.->|"syncs CRM data"| node_integrations

click node_api_server "https://github.com/wityliti/witylogix/blob/main/apps/api/src/server.ts"
click node_order_routes "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/orders.ts"
click node_checkout_rates "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/checkout/rates.ts"
click node_route_planning "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/routes.ts"
click node_tracking_routes "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/tracking.ts"
click node_pod "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/proof-of-delivery.ts"
click node_dispatch "https://github.com/wityliti/witylogix/blob/main/apps/dashboard/src/app/(dashboard)/dispatch/page.tsx"
click node_customer_portal "https://github.com/wityliti/witylogix/blob/main/apps/customer-portal/src/app/page.tsx"
click node_tracking_page "https://github.com/wityliti/witylogix/blob/main/apps/tracking-page/src/App.tsx"
click node_driver_app "https://github.com/wityliti/witylogix/blob/main/apps/driver-app/src/screens/RoutesScreen.tsx"
click node_realtime "https://github.com/wityliti/witylogix/blob/main/apps/api/src/lib/socket.ts"
click node_job_queue "https://github.com/wityliti/witylogix/blob/main/apps/api/src/lib/queue.ts"
click node_notification_worker "https://github.com/wityliti/witylogix/blob/main/apps/api/src/workers/notification-worker.ts"
click node_workflow_engine "https://github.com/wityliti/witylogix/blob/main/packages/framework/src/workflow/engine.ts"
click node_optimization "https://github.com/wityliti/witylogix/blob/main/apps/api/src/workers/optimization-worker.ts"
click node_zones "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/zones.ts"
click node_integrations "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/integrations.ts"
click node_shopify_webhooks "https://github.com/wityliti/witylogix/blob/main/apps/shopify-app/app/routes/app.webhooks.receive.tsx"
click node_search "https://github.com/wityliti/witylogix/blob/main/packages/core/src/search/search-engine.ts"
click node_returns "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/returns.ts"
click node_analytics "https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/analytics.ts"
click node_fleet "https://github.com/wityliti/witylogix/blob/main/packages/core/src/fleet/fleet-management-engine.ts"
click node_crm "https://github.com/wityliti/witylogix/blob/main/packages/core/src/crm/crm-sync-engine-v3.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_server,node_realtime,node_job_queue,node_notification_worker toneBlue
class node_order_routes,node_route_planning,node_tracking_routes,node_pod,node_zones,node_returns,node_analytics toneAmber
class node_dispatch,node_customer_portal,node_tracking_page,node_driver_app toneMint
class node_checkout_rates,node_integrations,node_shopify_webhooks toneRose
class node_workflow_engine,node_optimization,node_search,node_fleet,node_crm,node_merchant,node_customer,node_driver toneIndigo
```

## Components

### API Platform

- [Fastify API](https://github.com/wityliti/witylogix/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Live Updates](https://github.com/wityliti/witylogix/blob/main/apps/api/src/lib/socket.ts): `apps/api/src/lib/socket.ts`
- [Background Jobs](https://github.com/wityliti/witylogix/blob/main/apps/api/src/lib/queue.ts): `apps/api/src/lib/queue.ts`
- [Notification Worker](https://github.com/wityliti/witylogix/blob/main/apps/api/src/workers/notification-worker.ts): `apps/api/src/workers/notification-worker.ts`

### Delivery Operations

- [Order Management](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/orders.ts): `apps/api/src/routes/orders.ts`
- [Routes & Stops](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/routes.ts): `apps/api/src/routes/routes.ts`
- [Delivery Tracking](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/tracking.ts): `apps/api/src/routes/tracking.ts`
- [Proof of Delivery](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/proof-of-delivery.ts): `apps/api/src/routes/proof-of-delivery.ts`
- [Zone Pricing](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/zones.ts): `apps/api/src/routes/zones.ts`
- [Returns / RMA](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/returns.ts): `apps/api/src/routes/returns.ts`
- [Analytics](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/analytics.ts): `apps/api/src/routes/analytics.ts`

### User Applications

- [Dispatch Dashboard](https://github.com/wityliti/witylogix/blob/main/apps/dashboard/src/app/(dashboard)/dispatch/page.tsx): `apps/dashboard/src/app/(dashboard)/dispatch/page.tsx`
- [Customer Portal](https://github.com/wityliti/witylogix/blob/main/apps/customer-portal/src/app/page.tsx): `apps/customer-portal/src/app/page.tsx`
- [Public Tracking](https://github.com/wityliti/witylogix/blob/main/apps/tracking-page/src/App.tsx): `apps/tracking-page/src/App.tsx`
- [Driver Mobile App](https://github.com/wityliti/witylogix/blob/main/apps/driver-app/src/screens/RoutesScreen.tsx): `apps/driver-app/src/screens/RoutesScreen.tsx`

### Commerce & Integrations

- [Checkout Rates](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/checkout/rates.ts): `apps/api/src/routes/checkout/rates.ts`
- [Integration Catalog](https://github.com/wityliti/witylogix/blob/main/apps/api/src/routes/integrations.ts): `apps/api/src/routes/integrations.ts`
- [Shopify Webhooks](https://github.com/wityliti/witylogix/blob/main/apps/shopify-app/app/routes/app.webhooks.receive.tsx): `apps/shopify-app/app/routes/app.webhooks.receive.tsx`

### Domain Engines

- [Workflow Engine](https://github.com/wityliti/witylogix/blob/main/packages/framework/src/workflow/engine.ts): `packages/framework/src/workflow/engine.ts`
- [Route Optimization](https://github.com/wityliti/witylogix/blob/main/apps/api/src/workers/optimization-worker.ts): `apps/api/src/workers/optimization-worker.ts`
- [Full-Text Search](https://github.com/wityliti/witylogix/blob/main/packages/core/src/search/search-engine.ts): `packages/core/src/search/search-engine.ts`
- [Fleet Management](https://github.com/wityliti/witylogix/blob/main/packages/core/src/fleet/fleet-management-engine.ts): `packages/core/src/fleet/fleet-management-engine.ts`
- [CRM Sync](https://github.com/wityliti/witylogix/blob/main/packages/core/src/crm/crm-sync-engine-v3.ts): `packages/core/src/crm/crm-sync-engine-v3.ts`

### Other components

- **Merchant / Dispatcher**
- **Customer**
- **Driver**

## Connections

- Merchant / Dispatcher → Dispatch Dashboard: manages deliveries
- Customer → Public Tracking: tracks delivery
- Driver → Driver Mobile App: executes route
- Fastify API → Order Management: registers routes (evidence: `apps/api/src/server.ts`)
- Fastify API → Routes & Stops: registers routes (evidence: `apps/api/src/server.ts`)
- Fastify API → Delivery Tracking: registers routes (evidence: `apps/api/src/server.ts`)
- Fastify API → Live Updates: initializes sockets (evidence: `apps/api/src/server.ts`)
- Fastify API → Background Jobs: shuts down queues (evidence: `apps/api/src/server.ts`)
- Routes & Stops → Background Jobs: enqueues jobs (evidence: `apps/api/src/routes/routes.ts`)
- Routes & Stops → Live Updates: publishes updates (evidence: `apps/api/src/routes/routes.ts`)
- Public Tracking → Delivery Tracking: loads tracking
- Public Tracking → Live Updates: receives live updates (evidence: `apps/tracking-page/src/App.tsx`)
- Driver Mobile App → Routes & Stops: loads routes
- Checkout Rates → Zone Pricing: uses zone pricing
- Shopify Webhooks → Order Management: forwards order updates
- Notification Worker → Background Jobs: consumes jobs (evidence: `apps/api/src/workers/notification-worker.ts`)
- Workflow Engine → Background Jobs: orchestrates work
- Returns / RMA → Workflow Engine: runs return lifecycle
- Route Optimization → Routes & Stops: optimizes routes
- Proof of Delivery → Delivery Tracking: updates delivery status
- Integration Catalog → Shopify Webhooks: configures commerce
- Full-Text Search → Order Management: searches orders
- Analytics → Routes & Stops: reports performance
- Fleet Management → Dispatch Dashboard: supports fleet operations
- CRM Sync → Integration Catalog: syncs CRM data
