> **ملاحظة:** لم يعد يتم دعم دفاتر عمل Excel (`.xlsx`). قم بتصدير البيانات أو حفظها بصيغة CSV قبل استيرادها إلى Quantickle.

#### JSON

`File → Import Data` يقبل أيضًا صادرات JSON التي ينتجها Quantickle أو مجموعات عناصر Cytoscape الخام. عندما يحتوي الملف على `elements` تحتوي على إدخالات `data` متداخلة، يتم تسويتها إلى الهيكل الداخلي لـ Quantickle.

#### رسم بياني Quantickle (`.qut`)

ملفات `.qut` هي مستندات JSON تحتوي على كائنات العقد والحواف المسطحة. يبدو رسم بياني صغير كما يلي:
``````json
{
  "metadata": { "name": "My graph" },
  "nodes": [
    { "id": "srv-1", "label": "Gateway", "type": "server", "size": 40 }
  ],
  "edges": [
    { "id": "srv-1_cli-1", "source": "srv-1", "target": "cli-1", "label": "allows" }
  ]
}

الحقل الاختياري `info` لا يزال يدعم Markdown ويتم الاحتفاظ به بجانب أي خصائص مخصصة.

<a id="layouts"></a>
## التخطيطات

يقوم Quantickle بتجميع التخطيطات في مجموعات عملية حتى تتمكن من اختيار التخطيط المناسب للمهمة:

- **القوة الموجهة** (force, cose, fcose) — جيد لاكتشاف البنية الاستكشافية وعندما تريد التجميع الطبيعي.
- **التسلسل الهرمي والتدفق** (breadthfirst, dagre) — أفضل لأشجار التبعيات، رسوم الاستدعاء، أو التدفقات السببية.
- **الشبكة والدائرة** — تخطيطات سريعة وحتمية للوحات المعلومات والرسوم البيانية الصغيرة والتصدير.
- **قائم على الزمن** (timeline, timeline-scatter, temporal-attraction) — استخدم عندما يكون الترتيب الزمني أو الحداثة هي القصة.
- **المكاني/المطلق** (absolute, depth-aware) — استخدم للتخطيطات الشبيهة بالخريطة أو الرسم التخطيطي ذات الإحداثيات المعروفة.
- **المجموعة/الشعاعي** (radial-recency) — استخدم عندما تريد التجميع حسب النوع أو حلقات الحداثة.

### خيارات التخطيط```javascript
// js/layouts.js
const layoutOptions = {
  'force': {
    name: 'force',
    animate: true,
    randomize: false,
    infinite: false
  },
  'grid': {
    name: 'grid',
    rows: undefined,
    cols: undefined
  }
  // ... more layouts
}

عندما يتم توفير `className`، يتلقى شريط الجدول الزمني تلك الفئة وتتم إزالة تنسيق اللون والارتفاع الافتراضيين حتى تتمكن من استهدافه عبر CSS.

### تخطيط الأحدثية الشعاعي

استخدم `radial-recency` لرسم أحدث العناصر الأقرب إلى المركز والأقدم على الحلقات الخارجية. يربط التخطيط الزاوية بسمة ثانوية (نوع/مجموعة/مجموعة) بحيث تبقى العقد ذات الصلة محاذاة حول الدائرة. يمكنك ضبط الحلقات ببعض الخيارات:```javascript
cy.layout({
  name: 'radial-recency',
  ringThickness: 140, // radial spacing between time rings
  minSeparation: 80,  // minimum distance between neighbors along a ring
  angleJitter: 0.15,  // optional jitter (radians) to break perfect symmetry
  angleStrategy: 'grouped' // or 'alphabetical' for deterministic ordering
}).run();

### تخطيط الجذب الزمني

العُقَد ذات درجات التشابه الرقمية (`similarity`، `similarityScore`، أو `similarity_score`) تتركز حول المتوسط، بينما التصنيفات القاطعة أو المجتمعية تُنشئ ممرات متساوية التباعد على طول المحور الصادي.```javascript
cy.layout({
  name: 'temporal-attraction',
  timeMode: 'gaussian',          // or 'bucket'
  timeSigma: 60 * 60 * 1000,     // Gaussian falloff window (in ms)
  bucketSize: 24 * 60 * 60 * 1000, // bucket size when using bucket mode
  repulsionStrength: 12          // minimal node repulsion
}).run();

<a id="api"></a>
## API

### HTTP API

يقوم خادم Express (`server.js`) بتقديم الواجهة الأمامية الثابتة ويعرض عدة نقاط نهاية JSON تستخدمها واجهة المستخدم. جميع المسارات مسبوقة بـ `/api`:

| الطريقة والمسار | الوصف |
| --- | --- |
| `GET /api/domain-files` | يسرد تعريفات نطاقات JSON الموجودة في `assets/domains/`. |
| `GET /api/examples` | يعرض بيانات وصفية حول رسوم بيانية `.qut` نموذجية مرفقة. |
| `GET /api/serpapi` | يقوم بوكالة طلبات بحث Google إلى SerpApi؛ يتطلب `SERPAPI_API_KEY` في سلسلة الاستعلام أو البيئة. |
| `GET /api/openai/models` | يقوم بوكالة طلبات قائمة نماذج OpenAI إلى `api.openai.com`؛ يتطلب رأس `Authorization: Bearer ...`. |
| `GET /api/proxy?url=…` | يمرر طلبات HTTP/HTTPS إلى مضيفين مسموح بهم مع رؤوس شبيهة بالمتصفح. |
| `POST /api/neo4j/graph` | يحفظ رسماً بيانياً في Neo4j. يقبل جسم JSON المسطح لرسم Quantickle البياني الموضح أعلاه. |
| `POST /api/neo4j/node-graphs` | يجد الرسوم البيانية المحفوظة التي تحتوي على عقد تطابق مصفوفة `labels` المقدمة. |
| `GET /api/neo4j/graphs` | يسرد الرسوم البيانية المخزنة في Neo4j مع بيانات وصفية موجزة. |
| `GET /api/neo4j/graph/:name` | يجلب رسمًا بيانيًا محفوظًا، مع إرجاع `metadata` و `nodes` و `edges`. |
| `DELETE /api/neo4j/graph/:name` | يزيل رسمًا بيانيًا مخزنا من Neo4j. |

تقبل جميع نقاط نهاية Neo4j بيانات الاعتماد عبر الرؤوس `X-Neo4j-Url` و `X-Neo4j-Username` و `X-Neo4j-Password` (أو المتغيرات البيئية `NEO4J_URL` و `NEO4J_USER` و `NEO4J_PASSWORD` على الخادم). عند توفيره، يتم حفظ كائن `metadata` إلى جانب الرسم البياني ويتم إضافة طابع زمني `savedAt` تلقائيًا.

<a id="api-keys"></a>
### API Keys

تتطلب بعض الميزات مفاتيح API. يتم تخزينها في التخزين المحلي للمتصفح عبر لوحة التكاملات.

- **SerpAPI** — مطلوب لخط أنابيب RAG في البحث على الويب. أضف مفتاحك في حوار التكاملات وسيتم استخدامه من قبل خط أنابيب RAG من جانب العميل.
- **VirusTotal** — يُستخدم لإثراء عقد النطاق/IP/الملف/URL وسحب الرسوم البيانية للعلاقات.
- **CIRCL-LU** — بيانات اعتماد مصادقة اختيارية إذا كان خلاصة MISP الخاصة بك تتطلبها.

للاستخدام عبر سطر الأوامر، يمكنك بدلاً من ذلك تعيين `SERPAPI_API_KEY` في البيئة.

<a id="backend-proxy"></a>
### Backend Proxy

يعرض الخادم وكيلاً يتجاوز CORS يقوم بتمرير طلبات HTTP(S) إلى المضيفين المدرجين في القائمة المسموح بها للوكيل. استخدم `/api/proxy` مع معلمة URL:```
curl "http://localhost:3000/api/proxy?url=https%3A%2F%2Fopentip.kaspersky.com%2F"

إذا كنت تفضل متغيرات البيئة، قم بتعيين `PROXY_ALLOWLIST="otx.alienvault.com,feeds.example.org"` قبل تشغيل الخادم.

عندما يقوم البروكسي بإعادة توجيه طلب، فإنه الآن يرسل مجموعة رؤوس تشبه المتصفح (بما في ذلك قيم `User-Agent` و `Accept` و `Accept-Language` و `Sec-Fetch-*` الخاصة بمتصفح Chrome الحديثة) بحيث تستجيب المواقع التي تحجب المحتوى خلف مرشحات مكافحة البوت بنفس الطريقة التي تستجيب بها لتحميل صفحة عادي. يمكن تجاوز أي من هذه الرؤوس عن طريق توفير تجاوزات `x-proxy-<header>` من طلب العميل عند الحاجة.

<a id="storage"></a>
## التخزين

يحتفظ Quantickle بحالة الرسم البياني في المتصفح أثناء العمل، ثم يحفظها عند التصدير أو المزامنة.

- **تخزين المتصفح** — يتم تخزين الإعدادات ومفاتيح API محليًا في المتصفح.
- **ملفات المشروع (`.qut`)** — تُحفظ في مجلد مساحة العمل الخاصة بك للحصول على لقطات كاملة الدقة للرسم البياني. انظر [GRAPH_FILE_MANAGEMENT_README.md](https://github.com/rsac-labs/quantickle/blob/HEAD/GRAPH_FILE_MANAGEMENT_README.md) لمزيد من المعلومات حول قواعد مساحة العمل ودورة حياة الملفات.
- **Neo4j** — استمرارية اختيارية على جانب الخادم للتعاون والبحث، مهيأة عبر تكامل Neo4j.

<a id="project-structure"></a>
## هيكل المشروع```
quantickle/
├── assets/                               # Static assets
│   ├── backgrounds/                      # Background graphics
│   ├── icons/                            # Mostly empty now; icons are colocated with node types
│   ├── domains/                          # Node type definitions
│   ├── help/                             # Help pages
│   ├── examples/                         # Example graphs
│   └── css/                              # Stylesheets referenced by index.html
├── config/                               # Proxy allowlist
├── data_retrieval/                       # SerpAPI/web search helpers used by the RAG pipeline
├── graphs/                               # Workspace folder for bundled and test .qut graphs
├── js/                                   # Front-end source modules
│   ├── main.js                           # Application bootstrap
│   ├── ai-input-manager.js               # Currently unused
│   ├── api.js                            # HTTP client for server endpoints
│   ├── graph.js                          # Graph rendering and management
│   ├── graph-manager.js                  # High-level graph state orchestration
│   ├── graph-reference-resolver.js       # Normalization of graph references
│   ├── layouts.js                        # Layout registration and options
│   ├── 3d-globe-layout.js                # 3D Layout
│   ├── absolute-layout.js                # Absolute coordinate layout
│   ├── custom-layouts.js                 # Other custom layouts
│   ├── aggressive-performance-fix.js     # Aggressive Performance Fix for Large Graph Panning 
│   ├── non-invasive-performance-fix.js   # Non-Invasive Performance Fix for Large Graphs
│   ├── lod-system.js                     # Level of Detail (LOD) System
│   ├── auto-refresh.js                   # Auto-refresh functionality when new data arrives
│   ├── config.js                         # Default settings
│   ├── domain-loader.js                  # Loading and managing domain-specific node type configurations
│   ├── edge-editor.js                    # Editing edge styles
│   ├── extensions.js                     # Loading and registration of Cytoscape extensions 
│   ├── integrations.js                   # Configuration and connection to external services
│   ├── rag-pipeline.js                   # Handles AI-assisted data ingestion
│   ├── secure-storage.js                 # Encrypts sensitive values in sessionStorage
│   ├── source-editor.js                  # Editor for the JSON graph source
│   ├── tables.js                         # Data table updates, filtering, and display
│   ├── ui.js                             # User interface interactions and notifications
│   ├── validation.js                     # Validation of all data inputs
│   ├── workspace-manager.js              # Workspace file functionality
│   ├── utils.js                          # Shared browser utilities
│   ├── integrations/                     # Integration-specific helpers (MISP/CIRCL-LU, etc.)
│   └── features/                         # Feature modules (node editor, callouts, timeline, ...)
├── tests/                                # Automated regression tests covering UI flows, imports, and APIs
├── utils/                                # Node helpers (Neo4j client, readability shim, CLI scripts)
├── public/                   
│   ├── index.html                        # Static front-end
│   └── favicon.ico                       # Main app icon
├── package.json                          # Node dependencies and scripts
└── server.js                             # Express server exposing the HTTP API