🇸🇩 سودانا — بوابة المطورين

🟢 حالة النظام اللحظية

🧪 Live Execution Trace — Real Example

Actual execution path for: "عندي ألم في الصدر"

POST /s26/api/visitor_ask.php
Content-Type: application/json

{
  "question": "عندي ألم في الصدر"
}

Gateway::handle()
  → revenueGate(plan_key=free)    ✅
  → IE(554 rules) → conf=0.72     (no direct answer)
  → detectService: medical         ✅
  → PDE: REAL + mandatory          ⛔
  → HARD GATE triggered
  → tryStartFlow(medical_tele_v1)  ✅
  → StepController.start()
  → flow_session created (DB)
  → createMedicalCase() pending

INSERT → flow_sessions
  session_id: abc123...
  flow_id: medical_telemedicine_v1
  status: active
  current_step: intake_symptoms

(after triage)
INSERT → medical_records
  user_id, symptoms, triage_level
  specialization, session_id

{
  "success": true,
  "source": "flow",
  "blocked_ai": true,
  "medical_context": true,
  "flow": {
    "session_id": "abc123...",
    "step": "intake_symptoms",
    "progress": {
      "current": 1,
      "total": 7,
      "pct": 14
    }
  }
}

📊 إحصائيات اليوم

🗄️ حالة الجداول

⚡ مستكشف API التفاعلي

🏥 تدفق الطب عن بعد — server-driven

🔄 مسار Hard Gate (طبي)

🤖 AI Brain

{"question":"..."} → {"success":true,"answer":"...","source":"ie|cache|flow|gemini","actions":[]}

🏥 Flow / Telemedicine

{"flow_id":"medical_telemedicine_v1"} → {"session_id":"...","step":"intake_symptoms","progress":{"current":1,"total":7,"pct":14}}

{"session_id":"...","input":{"severity":7,"duration":"يوم"}} → {"step":"triage","triage_level":"urgent"}

📅 Booking

{"provider_id":1,"booking_date":"2026-05-01","booking_time":"10:00","consultation_type":"video","flow_session_id":"..."}

{"action":"cancel|start|complete|list","booking_id":1}

💳 Subscription

{"plan_key":"plus","payment_method":"bank_transfer","receipt_base64":"..."}

🗂️ BDE

👨‍⚕️ Provider

🏗️ System Architecture Diagram

Full request lifecycle — from user input to database write.

🏥 Telemedicine Flow Diagram

📊 Data + Provider Economy Diagrams

🔄 Flow State Diagram

🛡️ Governance Model

How Sudanna ensures determinism, safety, and institutional trust.

// Governance enforcement (Gateway.php)
if ($decision['type'] === 'REAL' && medical) {
    // HARD GATE — no bypass possible
    $flow = StepController::start('medical_telemedicine_v1');
    if (!$flow) return $medical_safe_deterministic_response;
    // ↑ Even on failure: no AI, no diagnosis
}

📋 Engine Files (12)

Database — 56 جدول في 9 طبقات

Layer 1: neighborhoods, partners, subscription_plans (no FK)
Layer 2: users (core entity)
Layer 3: sessions, user_subscriptions, payments, family_members
Layer 4: lessons, pharmacies, marketplace_items, pulse_posts, inquiries
Layer 5: bookings, provider_services, booking_ratings, provider_earnings
Layer 6: tele_sessions, consultation_messages, prescriptions, medical_records
Layer 7: flow_sessions, flow_step_logs
Layer 8: ai_cache, ai_requests, context_memory, kpi_daily
Layer 9: rate_limits, audit_logs, support_tickets, staff_members, ...

💳 خطط الاشتراك

⚙️ Gateway Enforcement

// Gateway.php — getPlanLimit()
// reads from subscription_plans table → admin changes = immediate effect

$limit = getPlanLimit($plan, 'ai_requests_day');
// free=20 | plus=60 | pro=200 (from DB — not hardcoded)

if (!check_rate_limit('ask_u_'.$uid, $limit, 86400))
    return 'block'; // → upgrade prompt shown to user

📊 سجلات الطلبات

JavaScript — AI Brain

const res = await fetch('https://sudanna.ai/s26/api/visitor_ask.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ question: 'عندي حرارة مستمرة' })
});
const d = await res.json();
// d.source = 'ie' | 'cache' | 'flow' | 'gemini' | 'medical_safe'
if (d.flow) handleFlowStep(d.flow);  // telemedicine
else        showAnswer(d.answer);

JavaScript — Telemedicine Flow

// Start flow
const start = await fetch('https://sudanna.ai/s26/api/flow/start.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ flow_id: 'medical_telemedicine_v1', context: {} })
});
const { session_id, step, prompt, progress } = await start.json();
// progress = { current: 1, total: 7, pct: 14, label: 'الخطوة 1 من 7' }

// Advance
const next = await fetch('https://sudanna.ai/s26/api/flow/next.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    session_id,
    input: { severity: 7, duration: 'يوم واحد', temperature: true }
  })
});
const { triage_level, providers } = await next.json();
// triage_level = 'urgent' | 'emergency' | 'normal'

JavaScript — Booking (with flow session)

// Booking requires valid flow session (anti-bypass)
const book = await fetch('https://sudanna.ai/s26/api/booking/create.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    provider_id:      42,
    booking_date:     '2026-05-10',
    booking_time:     '10:00',
    consultation_type:'video',
    flow_session_id:  session_id   // required — blocks direct API bypass
  })
});
const b = await book.json();
// b.meeting_link = 'https://sudanna.ai/s26/meet/...'

⚡ Sudanna Agent — AI Execution Platform

Build intelligent automation using Sudan's domain AI. Deploy agents for medical, legal, and business workflows.

GET /s26/dashboard/api.php
Authorization: Session Cookie

// Response
{
  "keys": [{
    "key_prefix": "sdk_abc...",
    "label": "Production Key",
    "calls_today": 12,
    "status": "active"
  }]
}

POST /s26/api/engine/chat.php
Authorization: Bearer sdk_YOUR_KEY
Content-Type: application/json

{"message": "محتاج محامي"}

// Response
{
  "success": true,
  "service": "legal",
  "flow": {
    "session_id": "abc123",
    "step": "legal_issue"
  }
}

POST /s26/api/engine/agents.php
Authorization: Bearer sdk_YOUR_KEY

{
  "action": "create",
  "name": "Legal Assistant",
  "prompt": "أنت محامٍ خبير...",
  "service": "legal"
}

// Response: {"success":true,"agent_id":5}

POST /s26/api/engine/run.php
Authorization: Bearer sdk_YOUR_KEY

{
  "agent_id": 5,
  "input": "أحتاج مساعدة في عقد"
}

// Response
{
  "success": true,
  "output": "...",
  "run_id": 23,
  "latency_ms": 1240
}

📊 Plans & Limits

🚀 أول API call في 5 دقائق

من الصفر إلى أول response — 3 خطوات فقط

❌ Error Codes