FirstTouch SLA

Multi-tenant lead distribution & business-hours SLA engine — with AI RAG, Telegram alerts, and n8n automation.

Changelog · Features · Architecture · Quick start · API · Docs

Hero · Lenovo Legion screen-only · light Filament UI · Nova Realty showcase data

---

What it is

FirstTouch SLA helps sales teams answer inbound leads in minutes, not hours.

Leads arrive from Meta, TikTok, Google, Snapchat, website forms, and Zapier/Make. The system verifies signatures fail-closed, assigns agents safely, starts a timezone-aware SLA clock, escalates through buffers, can answer with confidence-gated RAG, and notifies humans via Telegram / n8n.

Built as an enterprise-shaped portfolio system: strict multi-tenancy, SOLID adapters, Horizon queues, Pest + PHPStan Level 8.

---

Why teams buy this shape of product

Buyer pain	FirstTouch answer
Ads spend wasted when leads go cold	SLA clock + breach / warning / reassign buffers
Channel chaos (Meta, TikTok, Google…)	Signed webhooks + sandbox before go-live
AI that hallucinates on prospects	pgvector RAG with confidence gate → human fallback
Ops noise in email	Telegram alerts + claim / in-progress / contacted callbacks
Custom CRM / Slack / WhatsApp glue	n8n notification driver
Usage risk on AI	Credit ledger + plan gating

---

Feature gallery

Each shot is a full Legion screen-only mock of one marketable capability (16:9).

1. SLA analytics dashboard

Owner view: compliance rate, queue depth, breaches, and source mix — so managers see first-touch health at a glance.

2. Leads inbox & claim workflow

Multi-channel inbox with source pills, claim / in-progress / contacted actions, and SLA status (pending · active · met · breached).

3. AI Knowledge Base (RAG + pgvector)

Tenant knowledge bases power confidence-gated answers. Below threshold → human-only path; credits gate inferences.

4. Telegram ops alerts

Instant lead + breach notifications with quick-reply callbacks so reps claim without opening the console first.

5. n8n automation bridge

Workflow-friendly notification driver for CRM, Slack, WhatsApp, or any custom ops chain.

6. Multi-channel webhook sandbox

Simulate Meta / TikTok / Google / Snap / website payloads locally. Production adapters stay HMAC / API-key fail-closed.

7. Billing & AI credits

Growth plan, credit balance, top-up packages, and AI routing that falls back to human-only at zero credits.

8. Team RBAC

Owner vs sales roles: sales cannot touch billing or tenant settings. Skills + online status for fair routing.

9. Developer API

Sanctum tokens, inbound webhook contracts, and analytics endpoints for partners and internal tools.

More assets: docs/marketing/

---

Architecture

graph TD
  subgraph Inbound
    M[Meta / TikTok / Google / Snap]
    W[Website API key]
    Z[Zapier / Make]
  end

  Inbound --> T[Throttle + Webhook Controller]
  T --> H[HMAC / secret fail-closed]
  H --> Q[[Horizon ingestion job]]
  Q --> P[Lead pipeline]
  P --> DB[(PostgreSQL + pgvector)]
  P --> SLA[SLA + working hours]
  SLA --> BUF[Escalation buffers]
  BUF --> TG[Telegram]
  BUF --> N8N[n8n workflows]
  DB --> AI[RAG + credits gate]
  DB --> UI[Filament Admin / Sales]

Loading

More detail: docs/ARCHITECTURE.md

---

Tech stack

Layer	Choice
Backend	PHP 8.5+, Laravel 13
Admin UI	Filament v5, Livewire
Data	PostgreSQL 18 + pgvector
Queues	Redis + Laravel Horizon
Realtime hooks	Reverb / Echo-ready
Quality	Pest, PHPStan Level 8, Pint, GitHub Actions

---

Quick start

git clone https://github.com/yousefbzaqout/firsttouch-sla.git
cd firsttouch-sla

cp .env.example .env
composer install          # or Sail composer image if PHP is not local
./vendor/bin/sail up -d
./vendor/bin/sail artisan key:generate
./vendor/bin/sail artisan migrate --seed

Open http://localhost/admin and register a tenant.

Optional locals: Mailpit http://localhost:8025 · n8n http://localhost:5678 · Horizon http://localhost/horizon

Keep PAYMENT_DRIVER=mock and leave AI/Stripe/webhook secrets empty until you intentionally wire them.

Showcase demo tenant (local seed used for marketing shots)

Field	Value
Company	Nova Realty Group
Owner	demo@novarealty.demo
Password	DemoSecure123!

Local-only. Do not reuse on shared environments.

---

API & webhooks

Area	Examples
Auth	POST /api/v1/auth/register, forgot/reset password
Inbound	POST /api/v1/webhooks/{meta|tiktok|google|snapchat|universal|website}/{tenant_id}
Telegram	POST /api/v1/webhooks/telegram/{tenant_id}
Payments	POST /api/v1/payments/webhook/{driver}
Developer API	Sanctum: leads list/show, SLA analytics, token issue/revoke

---

Quality

./vendor/bin/sail pint
./vendor/bin/sail test --parallel
./vendor/bin/sail exec laravel.test ./vendor/bin/phpstan analyse --memory-limit=1G

CI runs the same gates on every push/PR to main.

---

Author

Yousef Bzaqout — portfolio system focused on tenancy, SLA reliability, and integration security.

Review path for hiring: docs/ARCHITECTURE.md → app/Pipelines → app/Services/Sla → tests/Feature.

License

MIT