Skip to content
YA
All work
BetaSaaSAIWebBackend

Wakeelوكيل

An AI employee that answers a business's customers on WhatsApp, Instagram and Messenger — in their own Arabic dialect.

Status
Phases 0–8 implemented and verified locally; real-number channel run and production deploy pending.
Period
2026
Platforms
Web · WhatsApp · Instagram · Messenger
Repository
Private — available on request
Live
—
Wakeel dashboard in Arabic, deep green and gold

01Overview

A multi-tenant SaaS: a business connects its messaging channels, and an AI employee answers 24/7 in text and voice notes, sends product photos, captures confirmed leads and hands conversations to humans. Teams work from a premium Arabic RTL dashboard.

By the numbers

commits
121
commits
git history
delivery phases
9
delivery phases
docs/BACKLOG.md
Arab countries & dialects
22
Arab countries & dialects
README
verified screens
65
verified screens
docs/screens
  1. 02The problem

    Small and medium businesses in the Arab world sell through chat. Customers write at midnight, in dialect, often by voice note — and the business owner is the only one answering. Leads go cold, questions repeat, and generic chatbots answer in stiff formal Arabic or invent answers.

  2. 03The vision

    An employee that never sleeps, never forgets and never makes things up: it answers only from what the business taught it, in the customer's dialect, and steps aside when a human should take over.

  3. 04The solution

    Webhooks from Meta are verified, stored and acknowledged instantly, then processed by an idempotent worker pipeline. A LangGraph agent routes, retrieves from a per-tenant hybrid search index, calls tools (products, images, lead fields, hand-off) and replies — as text, or as a voice note in the customer's dialect.

05Key features

  1. 01

    Grounded answers with citations

    Hybrid search (pgvector + Arabic full-text, fused with RRF) over uploaded PDFs, Word, Excel, web pages, FAQs and products. Every reply shows its sources in the inbox; unanswered questions become one-click FAQ entries.

  2. 02

    Leads confirmed in code, not by the model

    The employee reads the customer's name and phone back in their dialect; the confirmation is classified in code, so a lead exists only after the customer said yes to those exact details. Kanban, table, CSV export and email/web-push alerts follow.

  3. 03

    Voice notes both ways

    Incoming voice notes are transcribed and answered; replies can be voice notes in the agent's dialect and chosen voice, encoded as Ogg/Opus — the format WhatsApp expects — without ffmpeg.

  4. 04

    Any business, any Arab country

    Workspace type (store, clinic, restaurant, real estate…) and country set the persona, currency, time zone and dialect across all 22 Arab countries.

  5. 05

    Live inbox with take-over

    Realtime inbox over SSE; a human can take any conversation over and hand it back. A built-in customer simulator lets a business test its employee before going live.

  6. 06

    Plans, usage and billing

    Usage metered per tenant and month (tokens, speech seconds, TTS characters), plans, billing screens and an internal admin console.

06Screens

07System architecture

  1. L1Channels
    • WhatsApp Cloud API
    • Instagram
    • Messenger
    • Web simulator
  2. L2Web
    • Next.js App Router
    • next-intl (ar / en)
    • SSE inbox
    • RTL design system
  3. L3API
    • FastAPI
    • JWT + rotating refresh
    • RBAC
    • Signed webhooks
  4. L4Worker
    • ARQ on Redis
    • Per-conversation lock
    • LangGraph agent
    • Retries → dead-letter
  5. L5Data
    • PostgreSQL 16
    • pgvector
    • Row-level security
    • MinIO / S3
  6. L6Providers
    • LLM
    • Speech-to-text
    • Text-to-speech
    • Embeddings
A pnpm + uv monorepo. The web app proxies /api to FastAPI on the same origin (httpOnly cookies, no CORS). Webhooks land in a replayable table; an ARQ worker runs the pipeline and the agent graph against provider interfaces for LLM, STT, TTS and embeddings.Diagram — derived from the source code

08Engineering decisions

  1. Tenant isolation in the database, not only in code

    PostgreSQL row-level security is forced on tenant tables, with isolation tests. Webhooks reach their tenant through a SECURITY DEFINER function that returns only ids, so RLS never has to be bypassed.

  2. Idempotent by construction

    Raw payloads are stored before processing; provider message ids are unique per channel so duplicate deliveries are no-ops; a Redis lock per conversation prevents double replies; failures retry with backoff and then dead-letter.

  3. Provider interfaces with honest fallbacks

    Without an API key the employee politely hands every conversation to the team; a deterministic 'scripted' provider exists for demos and CI and is refused in production.

09Technical challenges

  1. Stopping the model from inventing leads

    A language model can 'hear' a confirmation that never happened. The lead flow keeps a draft on the conversation; the customer's next message is classified in code as yes / no / unclear, and only a yes creates the lead — the draft id becomes the lead id, so a retried job can never create a second one.

  2. Arabic retrieval

    Vector search alone misses exact product names and prices; keyword search alone misses dialect phrasing. Combining pgvector with Arabic full-text search through reciprocal rank fusion gave precise, citable passages.

10Lessons learned

Let the model write; let code decide anything that has consequences.
A webhook pipeline is only as reliable as its replay story.

My contribution

Product definition, architecture, backend, agent design, the Arabic-first dashboard and the phase-by-phase delivery documented in the repository (121 commits).

Technology

  • Python
  • FastAPI
  • SQLAlchemy
  • PostgreSQL
  • pgvector
  • Redis
  • ARQ
  • LangGraph
  • OpenAI
  • Next.js
  • TypeScript
  • Tailwind CSS
  • next-intl
  • Docker
  • GitHub Actions
  • RAG

How this was verified

Source, architecture and backlog reviewed. Screens are the project's own captures of the running app, saved per delivery phase in docs/screens.

Related projects

Next project

NUR