🔐 Owner / Admin Manual

1Creating a new company

New customers sign up themselves at the signup page. Every signup gets a free 30-day trial (extendable by one more month upon request) — no manual approval needed.

The signup page is at /signup. The new owner fills in:

• Company name (English + optional Arabic)
• Specialty (e.g. food, pharmacy, e-commerce)
• Contact phone
• Email + password

After signup, the owner is signed in automatically and lands on the onboarding page. The company gets status: trial with a 30-day countdown. If the client requests more time, the superadmin can extend the trial by another 30 days from the Admin dashboard. When the trial expires, API access is blocked until you activate them.

2Understanding tenants

One company = one isolated world. A dispatcher in Company A cannot see orders, drivers, stores, or anything else from Company B. This is enforced at the database layer.

Every row in orders, drivers, stores, audit_events, customers has a company_id foreign key. A SQLAlchemy before_flush guard in database.py (_tenant_guard) refuses any write that doesn't match the session user's company_id. There is no escape hatch in the API layer.

What this means practically:

• An accountant in Company A cannot read, list, or affect Company B data — even if they guess the order ID.
• The owner of Company A cannot accidentally delete Company B's drivers.
• You as a platform operator (direct DB access via psql on the server) bypass this guard. Use with care.
• Audit events are also tenant-scoped — one company's audit page shows only their own events.

3Inviting staff

Owners invite team members from the Team page. Each invite generates a one-time link.

On the Team page (/users-page):

1. Click Invite user.
2. Enter their email and pick a role: dispatcher, accountant, or driver.
3. For driver invites, you can link to an existing driver record or auto-create a new one.
4. Copy the invite link and send it to the new team member (e.g. via WhatsApp).
5. They open the link, set their password, and they're in.

Valid roles: owner, dispatcher, accountant, driver. See section 11 for what each can do.

4Managing stores

A "store" in Tariq is a depot — the starting point for route optimization. Every company has at least one.

1. Name — a short identifier (e.g. "Baghdad Main" or "Basra Branch").
2. Address — human-readable, just for your records.
3. Coordinates — paste a Google Maps / WhatsApp location link into the GPS field, or click on the map. The green checkmark confirms extraction worked.
4. Click Add Store. The store is immediately available as a depot in the Routes page.

5Managing drivers + token rotation

Each driver gets a unique URL that they open in their phone browser. No app install, no password. If that URL leaks, you rotate it.

Adding a driver on the Drivers page: name + phone + vehicle + commission per stop (IQD). On save, the server generates a URL like /driver?t=abc123.... Send it to the driver via WhatsApp.

Rotating the token when a phone is stolen, a driver leaves, or the URL was shared outside your team:

The rotation modal. Close is disabled until you check the acknowledgement.

1. Open the Drivers page.
2. Click Rotate token on the driver's row.
3. The modal shows the plaintext URL once. Copy it, send it to the driver on WhatsApp.
4. Tick the acknowledgement checkbox → Close button enables.
5. The old URL immediately returns 404. Only the new URL works.

6Notifications settings

WhatsApp notifications are owner-only and opt-in. The Settings page has one toggle + three template textareas.

Provider chip tells you the current state:

• ● Twilio WhatsApp (live) — credentials configured, real messages go out.
• ● Noop sender — credentials missing, every "send" is a silent no-op. Safe default.

Three templates, each supports variables:

• order_created — sent when a new order lands.
• out_for_delivery — sent when the dispatcher clicks "Notify customers" after route generation.
• delivered_with_links — sent automatically when an order transitions pending → delivered. Includes tracking + rating links.

Variables available: {customer}, {order_id}, {driver_name}, {track_url}, {rate_url}. Leave a template blank to use the built-in default.

7Reading the audit log

Every mutation in Tariq — every order created, every status change, every token rotation, every login attempt — is written to the audit log. This is your forensic trail.

Common actions to look for:

• auth.login.failed — failed password attempt. Many of these = brute force.
• order.create / order.update / order.delete — CRUD on orders.
• order.status_change — pending → delivered / failed transitions.
• order.reconcile — cash handover from driver to dispatcher.
• driver.token.rotated — security event; investigate if you didn't do it.
• notify.sent / notify.failed — WhatsApp send attempts; phone redacted to last 4 digits.

Red banner at top of the audit page = rate alarm. Shows when auth.login.failed > 10 per hour. Click into the filter to investigate.

Export CSV button: date range → downloads tenant-scoped audit rows. Open in Excel, share with compliance, archive off-server.

8Reading reports

Same /report page the dispatcher uses, but viewed through a platform-owner lens.

What to scan for, in order:

1. Success rate. Below 80% for multiple days running → something is wrong. Usually bad addresses (check failure reasons) or a specific driver underperforming.
2. Failure reason chips. "Wrong address" concentrated in one area → consider adding a customer-facing track link so they can fix it themselves. "Customer not home" high → reconsider dispatch time window.
3. Cash collected vs cash pending. "Pending" is delivered-but-not-yet-reconciled. If this number is large at end of day, reconciliations aren't happening.
4. Date range. Compare last Monday vs this Monday. Growth or drop should match your intuition; big divergences mean data quality issues (orders missed, drivers marking wrong).

9Provisioning WhatsApp (Twilio)

First-time setup. One-time cost in your time, then it just runs.

1. Sign up at twilio.com → free trial gives you enough credit to test.
2. Find WhatsApp Sandbox under Messaging → Try it out → Send a WhatsApp message. Each recipient (every customer) joins the sandbox by sending a join phrase to a Twilio number. This is a sandbox limitation — once you upgrade to a real WhatsApp Business sender, customers don't need to join.
3. Copy your credentials from the Twilio console:
   • Account SID
   • Auth Token
   • WhatsApp sandbox number (e.g. +14155238886)
4. Add them as GitHub secrets at github.com/Ahmedabdulla80/tariq → Settings → Secrets and variables → Actions:
   • TARIQ_TWILIO_ACCOUNT_SID
   • TARIQ_TWILIO_AUTH_TOKEN
   • TARIQ_TWILIO_WHATSAPP_FROM (format: +14155238886, no whatsapp: prefix)
5. Add repo variables (same page, Variables tab): TARIQ_NOTIFY_PROVIDER=twilio, TARIQ_NOTIFY_BASE_URL=https://tariq.codeator.ai, TARIQ_NOTIFY_DEFAULT_CC=+964.
6. Redeploy — push any commit to main, or re-run the latest workflow manually. On redeploy, the provider chip on /settings-page turns green.
7. Flip the toggle on Settings. Test by creating one order with your own WhatsApp number in the phone field. You should receive a message within seconds.

10Disaster recovery

What to do when something bad happens.

Server hardware failure / image rollback:

1. On GitHub Actions, find the last known-good run. Re-run it from there — the self-hosted runner will pull the previous image and restart.
2. Database is in the shared familycapital-sql container; it persists across Tariq container restarts. No data loss from an app restart.

Postgres backup & restore:

# Backup (run on server)
docker exec familycapital-sql pg_dump -U tariq tariq > tariq-$(date +%F).sql

# Restore
docker exec -i familycapital-sql psql -U tariq tariq < tariq-2026-04-01.sql

POD images live in a named volume pod-data, mounted at /data/pod/. To back up:

docker run --rm -v tariq_pod-data:/data -v $(pwd):/backup alpine tar czf /backup/pod-$(date +%F).tar.gz -C /data .

Stolen driver phone: rotate that driver's token (section 5). Old URL dies the instant you hit rotate. No other action needed.

Rogue dispatcher / compromised account: demote the user to accountant or delete via SQL, then review their audit log (actor_email filter) for the last 30 days to assess damage.

11Barcode scanning & tracking

Orders can carry barcode identifiers. Drivers scan them with their phone camera; customers can look up orders by barcode on the public portal.

How it works end-to-end:

1. Assign barcode: dispatchers or owners set a barcode on any order via the orders table or POST /orders/{id}/barcode.
2. Driver scans: the driver taps the scan button in their PWA, points the camera at the physical package barcode. The app uses the browser BarcodeDetector API.
3. Match & navigate: the scanned code hits GET /orders/scan/{barcode}, which returns the order. The driver's app scrolls to that stop.
4. Customer lookup: customers visit /customer-portal and enter the barcode string. GET /customer/status-by-barcode/{barcode} returns status without authentication.

12Predictive analytics

The /report page has a Predictions tab that analyzes historical data to surface patterns.

Data returned by GET /report/predictions:

• Failure by area: table of areas ranked by failure rate — total orders, failed count, and percentage. Helps identify neighborhoods that need address verification.
• Demand by day: order count per weekday (Sunday–Saturday), showing which days need more drivers.
• Peak hours: order volume by hour of day. Shows when customers are placing orders most.
• Average orders per day: your baseline for capacity planning.

13Customer self-service portal

The customer portal at /customer-portal lets customers check order status without contacting your team.

Two lookup methods:

• By order ID: GET /customer/status/{order_id} — returns order status, area, delivery time. No authentication needed.
• By barcode: GET /customer/status-by-barcode/{barcode} — same response, useful when you print barcodes on packages.

Full portal with OTP: customers can also enter their phone number, receive an OTP via WhatsApp, and see all their orders — not just one. This uses POST /customer/request-otp and POST /customer/verify-otp.

14Route reordering

Dispatchers can manually reorder stops after the optimizer generates routes, using drag-and-drop on the Routes page.

The POST /routes/reorder endpoint accepts a driver_id and a new ordered list of order_ids. The route view page calls this when a dispatcher drags stops into a new sequence and clicks "Save Order".

Who can reorder: owners and dispatchers only. The change is reflected immediately on the driver's phone — no page refresh needed (the driver's app auto-polls).

15Role matrix reference

What each role can do. ✓ = allowed, ✗ = blocked, 👁 = read-only.