IntelliPharma: Planning, Selling and Delivering Medicine from One Platform

• Pain

  Reps plan their day from habit and memory

  What it costs the business

  Fuel and hours lost to backtracking; high-value pharmacies get visited as often as low-value ones

• Pain

  Know-how and history live with the experts

  What it costs the business

  When an expert leaves, the history leaves with them

• Pain

  Visits are self-reported

  What it costs the business

  Coaching and performance reviews rely on what reps say happened, with nothing to check it against

• Pain

  Expiry dates live in a spreadsheet nobody opens

  What it costs the business

  Slow-moving batches are written off instead of pushed while there is still time

• Pain

  Cash is collected at the door and reconciled from a notebook

  What it costs the business

  Partial payments and proof of receipt are the first things to go missing

• Pain

  Targets are measured only at period close

  What it costs the business

  Neither rep nor manager can course-correct while it still matters

• Pain

  Every analytics question is a ticket to whoever has database access

  What it costs the business

  "Which region ordered the most antibiotics last winter?" gets answered days later, if at all

• Admin

  Web dashboard

  Owns catalogue, stock, promotions, staff, targets; plans the field team's days; watches the live map; asks the AI assistant business questions

• Sales representative

  Mobile app

  Gets an optimized route each morning, checks in on site, books orders, tracks their own target

• Distributor

  Mobile app

  Generates a delivery route from assigned tasks, records receiver and amount collected, marks stops completed / skipped / failed / blocked

• Pharmacy

  None (beneficiary)

  Has a location, opening hours, visit history, notes, and a 0–100 value score

1. 01

   Plan the day instead of guessing it. Every rep and driver gets an ordered route with predicted travel and service time per stop, with high-value pharmacies prioritized.

2. 02

   One transaction, one record. Booking an order moves stock, the rep's target and the pharmacy's balance in the same step.

3. 03

   Record what actually happened. Arrival, departure, time on site and the outcome of every stop, together with its cause.

4. 04

   Improve with use. Feed real travel and service times back to the optimizer.

5. 05

   Let managers question the data directly, in Arabic or English, without filing a request.

• A small team deploying to a single server.
• Arabic and English stored natively at the data level, not as a translation layer.
• Damascus geography, including dense old-city districts where walking beats driving.
• The route optimizer is an external service whose responses can take up to 120 seconds.
• Field apps are online-first.

Almost every write crosses contexts. One order touches stock, targets and debt, and those changes have to commit together. Splitting into services would have meant distributed transactions and a heavy operational load for a small team on one server. The modular monolith keeps the boundaries that microservices would give while keeping ACID transactions and a single deployment. Because modules talk only through gateway interfaces, one can still be extracted later.

• Ports and adapters between modules

  Where

  Planner depends on its own ErpGatewayInterface; ERP implements it and returns a Planner-owned DTO, not an Eloquent model

  What it bought

  CRM value scores flow into route optimization without Planner knowing CRM exists

• One use case per class

  Where

  CreateOrder, InitiatePlan, OptimizeNextLeg, PostDriverOutcomes

  What it bought

  Delivery planning reuses InitiatePlan unchanged; the nightly job and a console command share one use case

• Caching as a decorator

  Where

  CachedOrderService, CachedMedicineService etc., Redis tags keyed per permission scope

  What it bought

  Cheaper list endpoints with zero changes to business logic; invalidation lives in one place

• Optimizer behind an interface

  Where

  RouteOptimizerInterface

  What it bought

  Swappable and mockable; optimizer contract changes are absorbed in one gateway class

• Stateless permission checks plus ownership policies

  Where

  perm: middleware reads permissions from JWT claims; policies compare record owner on *.view.own

  What it bought

  Row-level "own vs. all" rules with no extra database queries on the hot path

• Unified envelope and central exception mapping

  Where

  ApiResponse, bootstrap/app.php

  What it bought

  Web and both mobile apps parse exactly one response shape, and business errors arrive as readable messages

• Pharmacies are resolved through the ERP gateway with coordinates and their CRM composite score (0–100). The score is normalized into a 0–1 priority, and pharmacies scoring 80 or more are flagged VIP.
• The rep's current GPS position is the start; the rep is modelled as one agent with an 8-hour working limit.
• Two travel modes: driving, and walking for dense districts. Walking uses a GraphHopper pedestrian matrix.
  Travel modes

  • driving
  • walking
• Eight optimization profiles:
  • balanced
  • fastest
  • cheapest
  • priority_first
  • vip_first
  • time_window_first
  • pedestrian_light
  • all_factors

The optimizer can take up to 120 s, and at first that held every HTTP request open. I moved generation onto the queue and delivered the result over WebSockets:

• Idempotent by design.

  A second request while one is in flight returns the same request_id. A unique-job lock on {user}:{date} adds a second guard, and in-flight rows older than 10 minutes are ignored, so a dead worker cannot block a rep from replanning.

• Retries are safe.

  InitiatePlan deletes its own plan row if optimization throws, so a second attempt starts clean. Failure is reported only from failed(), so the client never sees an error from an attempt that is about to be retried.

• Never fail after persisting.

  Once the plan is saved, broadcast and push-notification errors are logged rather than retried, because a retry would build a duplicate plan.

• Locale restored in the worker.

  Pharmacy and region names are translatable, and workers never pass through the locale middleware.

• Notify the right people.

  When an admin plans a rep's day, the result is broadcast to both, and the rep also gets a push notification.

When a stop is marked skipped, failed or blocked, the backend removes that stop's inbound leg and replans only the remaining pending stops from the rep's current position. It then places the already-completed stops back at the front, so the app always shows the whole day. A lighter optimize-next-leg endpoint recomputes just the next leg and updates the plan totals incrementally. Every replan is recorded with its reason and details, so disruptions also become data.

A scheduled job runs at 23:00 (Asia/Damascus) and posts the previous day's legs to the optimizer's ingest API. One record per driven leg carries predicted and actual travel time, predicted and actual service time, the stop outcome, and the driver-reported cause.

Privacy

user IDs are replaced with salted SHA-256 pseudonyms before anything leaves the system.

Data quality

legs outside the Damascus bounding box, without timestamps, or without a predicted value are filtered out.

Idempotency

a stable outcome_uid per leg makes resends harmless. Plans are stamped outcomes_posted_at, and plans with no eligible legs yet are left for a later run.

Observability

each batch is logged with accepted, rejected and duplicate counts, there is a warning above a 20% reject rate, and every run writes a JSON snapshot.

Guardexecutes only a single SELECT or WITH, no write or DDL keywords

• JWTs carry permission claims, which middleware checks with no database queries, supporting AND/OR permission groups.
• Ownership policies give "a rep sees only their own plans and orders; an admin sees everything" in one reusable place.
• Refresh tokens are hashed at rest (SHA-256), rotated on every use, and expire after 14 days.
• Private WebSocket channels are authorized with the same bearer token.

Driving tours, with the system's route compared against the same stops visited in list order:

• Median 43.9% shorter than list order, and 48.2% shorter than a random order.
• Median 8.1% above the exact optimum, and exactly optimal in Al-Midan.
• Against a careful planner working by eye (nearest-neighbour), the system is 37% ahead in Al-Midan, tied in Jaramana, and 7.9% behind in Shaalan. On small tours it matches a careful local planner on median. The real gain is that every rep gets that quality automatically, including new reps with no local knowledge, while value score, VIP status and working hours are weighed at the same time.
• For scale: the median saving is about 6.9 km and 7.4 minutes of driving per tour. Over 22 working days that is roughly 150 km and 2.7 hours per rep per month. This is an extrapolation from the median, assuming one tour a day.