SYSTEM ARCHITECTURE

منظومة ليفنترا
الذكية.

١٢ وكيل ذكاء اصطناعي مستقل، يعملون ضمن ٥ طبقات هرمية، مدعومون بمكتبة معرفة دلالية من ١٩ مجال متخصص. هذا المستند يوضح كل دور، كل علاقة، وكل تدفق بيانات في النظام.

AI Agents
12+
RAG Corpora
19
REEA Cycle
15 min
Hierarchy
5 Tiers
Portals
5
I · OVERVIEW

دماغان يعملان معاً.

منظومة ليفنترا الذكية تتكون من طبقتين مستقلتين تتكاملان: طبقة الوكلاء التي تقرر وتتصرف، وطبقة المعرفة (RAG) التي توفر السياق الدلالي. كلتاهما تعمل فوق قاعدة بيانات Supabase الموحدة.

AI AGENT LAYER

العقل المنفذ

الوكلاء — يفكرون، يقررون، ويتصرفون. كل وكيل يعمل ضمن صلاحية محددة، ويستطيع استدعاء أدوات للتفاعل مع قاعدة البيانات والخدمات الخارجية.

  • REEA (COO) — يدير الدورات الذاتية كل ١٥ دقيقة
  • ٥ وكلاء إدارة SaaS — IT، Sales، Marketing، Finance، Product
  • ٣ وكلاء بوابات — Staff، Owner، Tenant
  • وكلاء عمليات — Maintenance (فارس)، Leasing (بدر)، وغيرهم
  • وكلاء متخصصون — ليلى للتصميم، ١٢ وكيل عبر Telegram
RAG SYSTEM

العقل المعرفي

مكتبة معرفة قابلة للبحث الدلالي والمفتاحي. كل وكيل يستطيع استعلامها لاستخراج خبرة متخصصة قبل اتخاذ القرار.

  • ١٩ مجال معرفي (corpora) — قانوني، صيانة، مالي، تشغيلي
  • Vector + BM25 — بحث هجين (دلالي + مفتاحي)
  • Query Expansion — توليد ٣ صيغ لكل استعلام
  • Cross-Encoder Reranking — إعادة ترتيب النتائج بدقة
  • OpenAI text-embedding-3-small + Supabase pgvector
↑ ↓ Agents query RAG · RAG serves Agents
II · HIERARCHY

السلسلة القيادية.

٥ طبقات تنظيمية واضحة، مع تنسيق أفقي بين الأقران وتصعيد عمودي عند الحاجة. القرارات النهائية تعود لفهد (Tier 0)، بينما REEA تنسّق العمليات اليومية.

TIER 0 · HUMAN AUTHORITY
Tier 0 · CEO
Fahad
Final Authority · Human
المؤسس · صلاحية القرار النهائي
TIER 1 · AI ORCHESTRATOR
Tier 1 · COO
REEA
AI COO · Claude Sonnet 4.6
المنسّق المركزي — دورة ذاتية كل ١٥ دقيقة
TIER 2 · SAAS ADMIN AGENTS
IT
سالم
Infrastructure · Security
SALES
خالد
Leads · Trials · Demos
MARKETING
نورة
Funnel · Campaigns
FINANCE
ريم
MRR · ARR · Invoices
PRODUCT
يوسف
Features · Bugs · NPS
TIER 3 · OPS AGENTS (Field Operators)
MAINTENANCE
فارس
Tickets · SLA · Contractors
LEASING
بدر
Vacancy · Pricing Audits
DESIGN
ليلى
Creative · 14 visual styles
TIER 4 · PORTAL AGENTS (End-User Facing)
STAFF PORTAL
app
app.liv-entra.com
يخدم: موظفو إدارة العقار
OWNER PORTAL
owner
owner.liv-entra.com
يخدم: ملاك العقارات
TENANT PORTAL
tenant
tenant.liv-entra.com
يخدم: المستأجرون
III · REEA — THE AI COO

الدورة الذاتية.

كل ١٥ دقيقة، تقوم REEA بدورة تشغيلية ذاتية: تقرأ حالة النظام، تبني رسماً تشغيلياً سباعي الأبعاد، تحلل المخاطر، وتقرر بناءً على ذكاء Claude Sonnet 4.6.

REEA
AI COO · CLAUDE
15-MIN AUTONOMOUS LOOP
01
READ
SYSTEM STATE
02
BUILD
OPERATIONAL GRAPH
03
ANALYZE
PRIORITY SCORE
04
DECIDE
CLAUDE 4.6
05
EXECUTE
VIA TOOLS
06
LOG
DECISION LEDGER

٧ أبعاد للصحة التشغيلية

  • Active Incidents

    aom_tasks · submitted / working / blocked

    Live
  • Pending Approvals

    fahad_agenda · awaiting decision

    Live
  • Financial Exposure

    overdue payments · SAR amount

    SAR
  • Maintenance Load

    open tickets · SLA breaches

    SLA
  • Contract Risk

    expiring within 30 days

    30d
  • Tenant Satisfaction

    open complaints · sentiment

    CSI
  • Owner Satisfaction

    pending settlements

    OSI
IV · TIER 2 — SAAS ADMIN AGENTS

٥ أقسام، عقل واحد.

خمسة وكلاء يراقبون صحة منصة Liventra نفسها (وليس عقاراً واحداً). يتواصلون مع بعضهم البعض ومع REEA، ولكل منهم أدوات متخصصة وذاكرة مشتركة.

DEPT 01
سالم
IT · SECURITY
مهندس بنية تحتية أول · ١٥ سنة خبرة SaaS
  • مراقبة ٥ بوابات في وقت واحد
  • system_logs · security_events
  • Cloudflare Analytics
  • runDiagnosticQuery (15 SQL)
  • blockIP · checkDataIntegrity
DEPT 02
خالد
SALES · LEADS
مستشار مبيعات أول · سوق العقار SaaS
  • demo_requests · leads
  • تجارب الشركات النشطة
  • scrapeGoogleMaps (outreach)
  • contactLead · sendOutreachEmail
  • متابعة العملاء بعد 48h
DEPT 03
نورة
MARKETING · FUNNEL
محللة تسويق رقمي أول
  • visitor_sessions · conversion
  • getLeadSourceAnalysis
  • flagOpportunity
  • assignTask → ليلى للتصميم
  • queueMarketingNotification
DEPT 04
ريم
FINANCE · MRR
مديرة مالية · صحة الإيرادات
  • MRR / ARR tracking
  • getOverdueInvoices
  • getSubscriptionHealth
  • payment_gateway_configs
  • flagFinancialAnomaly
DEPT 05
يوسف
PRODUCT · ADOPTION
مدير منتج · صحة الميزات
  • getFeatureAdoption
  • getBugTicketTrends
  • getChurnAnalysis
  • NPS tracking
  • flagProductInsight

SHARED CAPABILITIES — كل الوكلاء الخمسة يمتلكون

writeSharedMemoryالكتابة في الذاكرة المشتركة readAgentMemoryقراءة اكتشافات الوكلاء الآخرين dispatchToAgentإرسال مهام للأقران escalateToFahadتصعيد للمؤسس addToAgendaإضافة للأجندة searchKnowledgeBaseاستعلام RAG (19 corpora)
V · TIER 3 + TIER 4

العمليات والبوابات.

وكلاء العمليات يتلقون المهام من REEA وينفذونها ميدانياً عبر بروتوكول Agent-to-Agent. وكلاء البوابات يخدمون المستخدمين النهائيين مباشرة بنموذج DeepSeek الأقل تكلفة.

وكلاء البوابات · Portal Agents

Staff Portal Agent

app.liv-entra.com

يساعد موظفي إدارة العقار في مهامهم اليومية: إنشاء طلبات صيانة، فحص الإشغال، تشغيل التقارير، البحث في قاعدة المعرفة.

  • إنشاء أوامر عمل
  • فحص حالة الوحدات
  • تشغيل تقارير الأداء
  • الوصول لكل بيانات الشركة
JWT · company_id DeepSeek Chat Redis 24h

Owner Portal Agent

owner.liv-entra.com

يخدم ملاك العقارات: استعراض المالية، التسويات، أداء العقارات، تنبيهات ذكية.

  • فحص البيانات المالية
  • كشف الحساب الشهري
  • أداء كل عقار
  • تنبيهات الموافقات
Scoped JWT DeepSeek Chat Read-only DB

Tenant Portal Agent

tenant.liv-entra.com

يخدم المستأجرين: تقديم طلبات الصيانة، استعراض المدفوعات، الاطلاع على بنود العقد.

  • تقديم طلب صيانة
  • تاريخ المدفوعات
  • عرض العقد
  • محادثة بالعربية
Tenant JWT DeepSeek Chat Whisper STT

وكلاء العمليات · Ops Dispatch Flow

HOW REEA DISPATCHES A TASK TO بدر

01
DETECT
REEA: "Unit 4B شاغرة منذ 14 يوماً، لا نشاط تأجيري"
02
CHECK
Workload + Cascade · بدر يملك أقل من ٣ مهام نشطة
03
DISPATCH
dispatchToAgent('بدر', { goal: 'متابعة شغور', entity_id })
04
EXECUTE
بدر يستدعي tools عبر A2A: getVacantUnits, checkPricing
05
REPORT
aom_tasks: status = working → done · REEA تقرأ النتيجة
VI · RAG SYSTEM — THE KNOWLEDGE LIBRARY

مكتبة المعرفة.

RAG = Retrieval-Augmented Generation. بدلاً من أن تخمن الوكلاء، تبحث أولاً في مكتبة المعرفة المختصة، تستخرج المقاطع الأكثر صلة، وتبني إجابتها على أساس مصادر موثقة.

📥 INGESTION PIPELINE — يحدث مرة واحدة عند إضافة الوثيقة

من ملف PDF خام إلى متجه قابل للبحث
01
Source Document
PDF · Word · Excel · TXT — يُرفع للنظام عبر الواجهة الإدارية
supabase.storage
02
Text Chunking
تقسيم النص إلى مقاطع بحجم ٥٠٠ توكن مع تداخل، مع حفظ بيانات الصفحة والقسم
~500 tokens / chunk
03
Embedding + Storage
تحويل كل مقطع إلى متجه (1536 بُعد) عبر OpenAI، وحفظه في Supabase pgvector
text-embedding-3-small

🔍 RETRIEVAL PIPELINE — يحدث في الوقت الحقيقي عند كل استعلام

من سؤال إلى إجابة موثقة في أقل من ثانية
1
Query Expansion · توسيع الاستعلام

السؤال يُعاد صياغته في ٣ صيغ مختلفة. مثال: "ما هو معدل إشغال طبيعي؟" → ٣ صيغ تشمل العربية الفصحى، اللهجة، والإنجليزية.

LLM Rewrite · 3 variants
2
Parallel Hybrid Search · بحث هجين متوازي

بحثان يعملان في نفس الوقت — Vector Search (تشابه دلالي عبر pgvector) و BM25 (تطابق مفتاحي على النص الكامل).

pgvector + Postgres tsvector
3
RRF Fusion · دمج النتائج

Reciprocal Rank Fusion يدمج قائمتي النتائج، ويكافئ المقاطع التي تظهر في صدارة كلا القائمتين.

k=60, fusion algorithm
4
Cross-Encoder Reranking · إعادة الترتيب الذكي

نموذج AI ثاني يقرأ السؤال مع كل مقطع ويعطي درجة صلة من 0 إلى 1. يكتشف الحالات التي وجد فيها البحث الأول الوثيقة الصحيحة لكنها كانت في مرتبة منخفضة.

Cross-Encoder Model
5
Entity Amplification · تضخيم الكيانات

إذا احتوى المقطع على مصطلحات عقارية محددة (أرقام وحدات، أحياء، أرقام أنظمة)، تُرفع درجته.

Boost score · domain entities
6
Return to Agent · إعادة النتيجة مع المصادر

أعلى ٥-١٠ مقاطع تعود إلى الوكيل مع البيانات الوصفية الكاملة. الوكيل ملزم بالاستشهاد بالمصدر عند استخدام المعرفة.

Top K · metadata included

قاعدة البيانات · knowledge_chunks

بنية الجدول في Supabase حيث تُخزن كل مقاطع المعرفة مع متجهاتها

-- Table: knowledge_chunks id UUID -- primary key corpus_id TEXT -- one of the 19 domain IDs source_name TEXT -- filename / document title chunk_text TEXT -- the passage (~500 tokens) embedding VECTOR(1536) -- OpenAI embedding vector metadata JSONB -- page, section, headings created_at TIMESTAMP

١٩ مجال معرفي

كل مجال (corpus) عبارة عن مجموعة من الوثائق المتخصصة في موضوع واحد. الوكلاء يستطيعون التركيز على مجال محدد أو البحث عبر الجميع.

01 · market
Real Estate Market
أسعار العقارات السعودية، الإيجارات، معايير السوق
02 · legal-ejar
Ejar Regulations
نظام الإيجار السعودي، قواعد منصة إيجار، العقود
03 · mot-str
Short-Term Rentals
تراخيص MOT، قوانين الإيجار قصير الأمد
04 · preventive
Preventive Maintenance
جداول PPM، معايير الصيانة الوقائية
05 · corrective
Corrective Maintenance
إجراءات الإصلاح، تشخيص الأعطال
06 · asset-lifecycle
Asset Lifecycle
عمر المعدات، دورات الاستبدال
07 · construction
Building Systems
SBC / RICS standards، مواصفات البناء
08 · fm-standards
Facility Management
ISO 41001، معايير PPM/SLA
09 · fire-safety
Fire Safety
متطلبات الدفاع المدني، أكواد NFPA
10 · property-finance
Property Finance
NOI، Cap Rate، طرق التقييم DCF
11 · saudi-legal
Saudi Legal Framework
REGA، RETT، أنظمة ZATCA
12 · mep-ops
MEP Systems
HVAC/VRF، المياه، BMS
13 · sustainability
Sustainability
LEED، SGBC، معايير ESG
14 · leasing-ops
Leasing Operations
KPIs، إجراءات التأجير، إدارة الإشغال
15 · vendor-mgmt
Vendor Management
معايير SCA/FIDIC للمقاولين
16 · owner-relations
Owner Relations
التسويات المالية، تواصل الملاك
17 · emergency
Emergency Response
ISO 22301، إدارة الأزمات
18 · market-intel
Market Intelligence
NEOM، رؤية 2030، اتجاهات 2024-2025
19 · saudi-dialect
Saudi Arabic Dialect
9,802 صف من اللهجة النجدية
VII · MEMORY ARCHITECTURE

طبقات الذاكرة.

كل وكيل يملك أنواعاً متعددة من الذاكرة — السريعة (Redis) للمحادثات والكاش، والدائمة (Supabase) للمعرفة المشتركة والمهام وسجل القرارات.

⚡ REDIS · FAST · VOLATILE

Redis

ذاكرة قصيرة الأمد لكل وكيل ولكل مستخدم — تخزن المحادثات والكاش والمعدلات.

  • agent:{type}:{userId}
    آخر ٢٠ رسالة في المحادثة لكل وكيل-مستخدم
    TTL: 24h (IT) · 7d (Sales)
  • BullMQ queues
    طوابير المهام الدائمة — إعادة المحاولة عند الفشل
  • telegram:conv:{userId}
    كاش محادثات Telegram
  • rate_limit:{key}
    عدّاد الاستخدام · 20 calls/hour per admin
💾 SUPABASE · PERSISTENT

Supabase PostgreSQL

ذاكرة دائمة موحدة عبر كل الوكلاء — قاعدة الحقيقة المشتركة، المهام، الأفكار، وسجل القرارات.

  • agent_shared_memory
    مخزن مفتاح-قيمة مرئي لكل الوكلاء. يحتوي ground_truth_company_context الذي يُحقن في سياق REEA كل دورة.
    TTL: 90 days
  • aom_tasks
    المهام النشطة والمكتملة المُرسلة من REEA إلى وكلاء العمليات
  • aom_insights
    الأنماط التي تعلمتها REEA · مصنفة بدرجة الثقة
  • agent_goals
    الأهداف التشغيلية الأسبوعية المحددة من فهد، يتتبعها الوكلاء
  • fahad_agenda
    العناصر المُجدولة لقرار فهد البشري
  • decision_ledger
    سجل تدقيق كامل لكل قرار من REEA بنموذج 7 حقول: REASONING · PRIORITY · RISK · CONFIDENCE · OWNER · DEADLINE · ESCALATION
    Permanent · audit trail
VIII · AGENT COMMUNICATION

كيف يتحدثون.

الوكلاء يتواصلون أفقياً (peer-to-peer عبر dispatchToAgent) وعمودياً (تصعيد لفهد عبر addToAgenda). كل اتصال مسجّل ويمكن تتبعه.

EXAMPLE — سالم يكتشف خطأ يؤثر على المبيعات

  • سالم
    IT
    يكتشف فشلاً في payment webhook خلال runDiagnosticQuery
  • سالم
    IT
    يستدعي dispatchToAgent('sales', { message: 'payment webhook failing' })
  • خالد
    Sales
    يستلم التوجيه ويفحص أيٌّ من العملاء المحتملين تأثروا
  • خالد
    Sales
    يستدعي escalateToFahad إذا كان عميل enterprise متأثراً
  • Fahad
    CEO
    يستلم بريداً عاجلاً + بنداً في fahad_agenda للقرار
IX · TOOL ECOSYSTEM

ما يستطيع الوكلاء.

الأدوات هي الدوال التي يستدعيها الوكيل للتفاعل مع العالم الحقيقي. كل أداة لها schema (مثل توثيق API) حتى يعرف الذكاء الاصطناعي كيف يستخدمها.

READ
استعلام قاعدة البيانات، جلب التقارير، قراءة البيانات
getSystemHealthReport getRevenueOverview querySecurityEvents
WRITE
إنشاء وتحديث السجلات
createContract assignTicket updateLeadStatus
DISPATCH
إرسال مهام للوكلاء الآخرين
dispatchToAgent assignTask escalateToFahad
EXTERNAL
الاتصال بخدمات خارجية
scrapeGoogleMaps getCloudflareEvents renderPostToPNG
KNOWLEDGE
استعلام نظام RAG
searchKnowledgeBase queryCorpora
STATE
إدارة دورة حياة الكيانات
triggerStateTransition getEntityState recordDecision
X · EVENT BUS

الأحداث والمستمعون.

عند حدوث شيء مهم في النظام، يتم إطلاق event. الأجزاء الأخرى تستمع وتتفاعل تلقائياً. هذه الطريقة هي كيف يحصل الوكلاء على إشعارات دون الحاجة للاستعلام المتكرر.

payment.paid
  • payment-notifications · إشعار WhatsApp/email للمستأجر
  • dispatch-webhook · إشعار الأنظمة الخارجية
  • gl-auto-poster · إنشاء قيد محاسبي GL
contract.signed
  • dispatch-webhook · إشعار الأنظمة الخارجية
maintenance.ticket_created
  • dispatch-webhook · إشعار الأنظمة الخارجية
  • (مستقبلاً) تنبيه فارس · وكيل الصيانة
unit.status_changed
  • dispatch-webhook
  • (مستقبلاً) تشغيل دورة REEA
payment.late_fee
  • gl-auto-poster · قيد رسوم التأخير
settlement.transferred
  • gl-auto-poster · قيد التسوية للمالك
XI · INFRASTRUCTURE

أين يعمل كل شيء.

النظام موزع على مزودين متعددين: Vercel للواجهات الأمامية، Railway للخوادم، Supabase لقاعدة البيانات، Redis للذاكرة السريعة، وخدمات AI خارجية.

FRONTEND · VERCEL (Next.js)
admin.liv-entra.com
Next.js 16 · Admin portal
app.liv-entra.com
Next.js 14 · Staff portal
owner.liv-entra.com
Next.js 14 · Owner portal
tenant.liv-entra.com
Next.js 14 · Tenant portal
demo.liv-entra.com
Next.js 14 · Demo portal
BACKEND · RAILWAY
Railway #1 · Main API
Express.js + Node.js · يخدم البوابات الخمس
Railway #2 · Demo API
معزول للبيئة التجريبية فقط
Workers
notifications · WhatsApp · maintenance · A2A agents · AOM events · RAG · portfolio
DATA · SUPABASE + REDIS
Supabase Main
PostgreSQL 17 · pgvector · RLS على 76+ جدول
Supabase Demo
قاعدة بيانات منفصلة للبيئة التجريبية
Upstash Redis
BullMQ queues · agent memory · telegram cache · rate limiting
EXTERNAL AI SERVICES
Anthropic Claude Sonnet 4.6
REEA + جميع وكلاء SaaS Admin
DeepSeek Chat
وكلاء البوابات (محسّن للتكلفة)
OpenAI Embeddings
text-embedding-3-small (1536 dim) · لنظام RAG
Whisper (HF)
تحويل الصوت إلى نص لـ Telegram
NAMAA TTS
تحويل النص إلى صوت عربي
INTEGRATIONS
Cloudflare
CDN · WAF · DNS · DDoS
Moyasar
بوابة الدفع السعودية
WhatsApp Business API
إشعارات المستأجرين والملاك
Ejar
تكامل منصة إيجار
ZATCA
الفوترة الإلكترونية (Mode A)
XII · SECURITY

٨ طبقات حماية.

كل طلب يمر عبر ثماني طبقات أمنية — من جدار الحماية على الحافة، إلى Row Level Security داخل قاعدة البيانات، إلى مصفوفة صلاحيات الوكلاء.

LAYER 1 Network Cloudflare WAF · حماية من DDoS، SQL injection، XSS
LAYER 2 API Helmet.js security headers · CORS whitelist · HSTS
LAYER 3 Rate Limiting Global على كل /api · 20 calls/hour لكل admin على وكلاء الذكاء
LAYER 4 Authentication JWT (15 min) + refresh · Portal JWT scoped · Admin Super: TOTP 2FA
LAYER 5 Authorization RBAC · company_id scoping على كل استعلام
LAYER 6 Database Row Level Security على 76+ جدول في Supabase
LAYER 7 Agent Authority جدول reea_authority يحكم الحدود المالية للوكلاء
LAYER 8 Audit admin_audit_logs + decision_ledger · كل إجراء مسجّل

أرقام سريعة

12+
AI Agents
19
RAG Corpora
15min
REEA Cycle
9,802
Saudi Dialect Rows
10
Tool-Use Rounds / Cycle
76+
DB Tables with RLS
5
Portals Served
1536
Embedding Dimensions