DarkRoute

إنهم يراقبون. ونحن نراقبهم بالمقابل.

جدول المحتويات

• ما هذا
• تخطيط المستودع
• البنية المعمارية
• واجهة برمجة التطبيقات العامة
• سير العمل أثناء التشغيل
• المتطلبات الأساسية
• التثبيت
• متغيرات البيئة
• أوامر التطوير
• أوامر الاختبار
• نموذج الأمان والخصوصية
• مصادر التصميم وقاعدة الرموز
• قيود المنصات
• المساهمة
• سياسة الأمان
• الترخيص

ما هذا

تطبيق ويب تقدمي (PWA) لمكافحة المراقبة، موجّه أولاً لنظام أندرويد، يخبر السائق بمكان قارئات لوحات السيارات الآلية قبل أن يمر بها.

يوفّر تنبيهات قرب فورية بالاعتماد على أرشيف كاميرات يعمل دون اتصال، وسجل تعرّض محلي، وطابور على الجهاز لتقارير كاميرات موقّعة ومتسلسلة بالتجزئة، وسياق سجلات عامة موثّق بالمصادر عن الوكالات التي تشغّل الكاميرات من حولك.

التطبيق المنشور لا يحتوي على نقطة نهاية لرفع التقارير. تبقى التقارير في IndexedDB حالياً. توجد بوابة إرسال كشيفرة مشغّل وليست مساراً منشوراً؛ وهذا التمييز مقصود في كل هذا الملف.

وهو لا يفعل شيئاً سادساً عن قصد: فهو لا يستعلم من نظام أي مورّد، وقيم لوحات السيارات لا تغادر الجهاز أبداً.

تخطيط المستودع

darkroute/
├── apps/
│   ├── pwa/                    React 19 + TypeScript + Vite PWA
│   ├── desktop/                developer console at api.darkroute.ai; its functions/ proxy /v1 and /api/v1 to the apex
│   └── android/                buildable Android Trusted Web Activity shell
├── packages/
│   ├── core/                   pure geometry and alert engine; no DOM or I/O
│   └── api-client/             empty placeholder; the live contract is GET /api/v1/openapi.json
├── functions/
│   ├── cameras/                same-origin camera tiles from the CAMERA_TILES R2 binding
│   └── api/
│       ├── v1/                 the public API: reads, /submit (opens a PR), /photo, openapi.json, _middleware
│       └── admin/              Cloudflare Access tester allowlist (private dev host only)
├── scripts/                    camera pipeline, deploy, asset and policy checks
├── docs/                       implementation, operations and public documentation
├── the design-gap ledger              unresolved design decisions and stand-ins
└── installer.sh

مكدّس LoRa هو مكدّس Meshtastic نفسه، دون تعديل: هذا المشروع لا يبني أي برنامج ثابت (firmware) ويقترن بعقدة جاهزة. يبقى packages/api-client عنصراً نائباً؛ وتطبيق PWA الإنتاجي لا يستخدمه.

البنية المعمارية

المنتج المنشور هو تطبيق PWA ثابت مع Cloudflare Pages Functions: مسار بلاطات الكاميرات، وواجهة برمجة التطبيقات العامة تحت /api/v1/ (انظر واجهة برمجة التطبيقات العامة)، ومساران إداريان محميان بـ Access على مضيف التطوير الخاص. لا يحتوي على عملية FastAPI، ولا قاعدة بيانات Postgres، ولا واجهة برمجة تطبيقات للحضور، ولا نقطة نهاية تقارير منشورة؛ ومسار الكتابة الوحيد، POST /api/v1/submit، يفتح طلب سحب عام بدلاً من الكتابة إلى أي شيء.

flowchart LR
    OSM["OpenStreetMap"] --> PIPE["scheduled Node camera pipeline"]
    PIPE --> R2[("R2 camera archive")]
    R2 --> CAM["/cameras/* Pages Function"]

    subgraph device["Browser or Android TWA"]
        GPS["geolocation + other adapters"] --> CORE["packages/core alert engine"]
        CORE --> UI["DRIVE / map / reports"]
        UI <--> IDB[("IndexedDB + service-worker cache")]
    end

    CAM --> IDB
    MAP["project tile host (PMTiles)"] --> UI

تُطلب بلاطات الكاميرات من /cameras/* على نفس الأصل، وتُقدَّم من ارتباط CAMERA_TILES في R2، وتُخزَّن مؤقتاً للاستخدام دون اتصال. أما أرشيفات الخرائط الأساسية والسرعة فهي طلبات نطاق عبر أصول مختلفة إلى مضيف البلاطات العام الذي يشغّله المشروع. darkroute.ai هو التطبيق العام. أما الدوال الإدارية فتقع خارج هذا التوزيع بالكامل.

أدوات التنسيق وبوابة الإرسال هي شيفرة مشغّل، مُبقاة خارج هذا التوزيع. وليست أي منهما خادم تشغيل منشوراً، ولا يعتمد أي شيء في هذا المستودع على أي منهما: فالتطبيق يُبنى ويعمل ويُختبر ويُدقَّق بدونها.

تقع الحسابات الجغرافية المكانية في packages/core؛ وتستهلك الشاشات المخازن والمحوّلات. ويبقى مطابقة اللوحات، وسجل الرحلات، وسلسلة أدلة التقارير على الجهاز.

واجهة برمجة التطبيقات العامة

الأرشيف متاح للقراءة من أي شخص، دون مفتاح، على https://darkroute.ai/api/v1/، ويُقدَّم أيضاً على https://api.darkroute.ai/v1/ و https://api.darkroute.ai/api/v1/ عبر وكيل لوحة تحكم المطوّر. العقد القابل للقراءة آلياً هو GET /api/v1/openapi.json؛ والنص الوصفي في docs/public/API.md §1.3؛ ولوحة التحكم لتجربته هي api.darkroute.ai.

المسار	ما يجيب عنه
GET /api/v1/cameras	الكاميرات في bbox (≤ 1.5° لكل ضلع، ≤ 24 بلاطة، ≤ 1000 صف)، مع مرشّح اختياري owner
GET /api/v1/stats	حجم الأرشيف، والجيل، والبناء، والطوابع الزمنية للمصدر الأعلى
GET /api/v1/abuse	الحالات الموثّقة وتاريخ التوليد؛ مع fips اختياري للمقاطعة
GET /api/v1/news	عناوين ALPR المجمّعة تلقائياً، وروابط المصادر، وحالة التجميع
GET /api/v1/atlas	وكالات وموردو EFF Atlas حسب المقاطعة، مع تواريخ الاسترجاع/التحقق؛ مع fips اختياري
GET /api/v1/monitoring	جرد معدات مراقبة الطرق؛ مع kind و bbox اختياريين
GET /api/v1/monitoring/image?id=...	صورة ناشر متاحة لكاميرا المرور المحددة
GET /api/v1/place	بحث عن مكان في الولايات المتحدة/بورتوريكو، عبر وكيل حتى لا يرى محدد المواقع عنوان السائق أبداً
GET /api/v1/route	مسار قيادة يتجنّب حتى 60 نقطة؛ لا يُخزَّن مؤقتاً أبداً
GET /api/v1/doc/{name}	مستند منشور من المرآة العامة، بصيغة Markdown
POST /api/v1/submit	تصحيح، يتحوّل إلى طلب سحب [unreviewed]، ولا يُكتب أي شيء في الأرشيف
PUT /api/v1/photo	صورة يشير إليها إرسال، مفتاحها بايتاتها؛ ويقدّمها GET /api/v1/photo/{key} مرة أخرى