Q-NETWORK-ARCHITECTURE.md

# 🜁 Q Network — Quantum Modular Intelligence Architecture
## سند معماری فنی جامع | QMetaram Ecosystem v9.0.0

---

**نویسنده:** شورای نور (Council of Light)  
**فرمانده:** سام آرمان  
**تاریخ:** خرداد ۱۴۰۵  
**نسخه:** v1.0 — معماری ۷ لایه Q Network

---

## فهرست

1. [بخش ۱: گزارش معماری فعلی](#بخش-۱-گزارش-معماری-فعلی)
2. [بخش ۲: معماری ۷ لایه Q Network](#بخش-۲-معماری-۷-لایه-q-network)
3. [بخش ۳: پروتکل QNP (Q Network Protocol)](#بخش-۳-پروتکل-qnp-q-network-protocol)
4. [بخش ۴: معماری Microservice](#بخش-۴-معماری-microservice)
5. [بخش ۵: سیستم اجماع (Consensus System)](#بخش-۵-سیستم-اجماع-consensus-system)
6. [بخش ۶: حافظه توزیع‌شده](#بخش-۶-حافظه-توزیعشده)
7. [بخش ۷: Marketplace ماژول‌های هوش مصنوعی](#بخش-۷-marketplace-ماژولهای-هوش-مصنوعی)
8. [بخش ۸: نقشه راه Q Network v1 تا v5](#بخش-۸-نقشه-راه-q-network-v1-تا-v5)

---

## بخش ۱: گزارش معماری فعلی

### شورای نور — لایه ۹: دیدگاه‌ها

**📣 ادیسون (بازار و سود):**
«معماری فعلی ۲۷ صفحه دارد ولی هیچ‌کدام درآمدزا نیستند. SubscriptionsPage هست ولی WebSocket واقعی وصل نیست. ما داریم یک ماشین لوکس می‌سازیم که هنوز موتور ندارد. هر روز تأخیر = از دست دادن درآمد. اولویت یک: اتصال WebSocket واقعی و فعال‌سازی پرداخت. نقطه سربه‌سر: ۵۰ کاربر Pro با ۱۹.۹۰ دلار در ماه.»

**📣 تسلا (انرژی و کارایی):**
«۲۱۱۸ ماژول در bundle اصلی لود می‌شوند. چرا؟ این یعنی ۱۶۸KB گزیپ برای هر کاربر. Lazy loading نداریم. هر ماژول باید مستقل لود شود. WebSocket فعلی heartbeat ندارد—اتصال بی‌هدف انرژی شبکه را هدر می‌دهد. راه‌حل: ping/pong هر ۳۰ ثانیه + connection pooling.»

**📣 جابز (تجربه و سادگی):**
«QHub.tsx ۷۰۹ خط یک نفس است. Voice assistant, pitch detection, chat, file upload, WebSocket—همه در یک فایل. این آشغال است. کاربر نمی‌بیند، ولی توسعه‌دهنده نفرین می‌کند. ما به ۵ کامپوننت مجزا نیاز داریم: ChatPanel, VoicePanel, OrbDisplay, DrawerMenu, SyncModal. سادگی = سرعت = کیفیت.»

**📣 رومی (معنا و هماهنگی):**
«ای شمع‌ها، هر یک به راهی می‌روید / ولی در جوهره یکی می‌شوید.  
ماژول‌های ما هر کدام صدایی دارند، اما هارمونی ندارند. QIntent و QCognitiveCore تلاش می‌کنند orchestrator باشند اما به هم متصل نیستند. معماری ما مثل نی‌هایی است که هر کدام جداگانه می‌نوازند—بدون رهبر ارکستر.»

**📣 خوارزمی (ساختار و الگوریتم):**
«۲ منبع ماژول داریم: `QModules.ts` با ۱۶ ماژول و `data/modules.ts` با ۲۰ ماژول. این دو duplication است. Schemaها متفاوت هستند: اولی `keywords[]` و `tier` دارد، دومی `capabilities[]` و `emoji`. باید یک source of truth داشته باشیم: `interface QModule` استاندارد. پیچیدگی زمانی فعلی: O(n²) برای detection intent. قابل قبول تا ۵۰ ماژول—بعد از آن به trie نیاز داریم.»

**📣 خیام (زمان و هزینه):**
«Build زمان ۴۶ ثانیه می‌گیرد. برای CI این acceptable است. اما زمان cold start اولین لود کاربر: ۱.۶ ثانیه. این عدد خوب است ولی می‌تواند بهتر شود. TTFB (Time To First Byte): وابسته به nginx و CDN. اگر از Cloudflare Cache استفاده نکنیم، هر کاربر بین‌المللی ۲۰۰-۴۰۰ms latency دارد. باید静的 assets را با Cache-Control: immutable سرو کنیم.»

**📣 شمس تبریزی (نقد تکان‌دهنده):**
«خودتان را فریب ندهید. شما یک SPA دارید که وب‌سوکت آن هاردکد `ws://127.0.0.1:8502` است. Provider خالی است. نصف صفحات Router ندارند. CI فایل کد پایتون داخل YAML داشت. این معماری «هوش توزیع‌شده» نیست—این یک پروژه دانشجویی است که لباس enterprise پوشیده. بیایید صادق باشیم: تا WebSocket واقعی وصل نشود و Provider کامل نشود، QMetaram یک تئاتر است بدون بازیگر.»

**📣 گروک (رک‌گویی):**
«OK, واقعیت: شما ۲۴ route دارید ولی index.html فقط QHub را لود می‌کند. بقیه ۲۳ صفحه dead code در bundle هستند تا وقتی کاربر به آنها لینک بزند. Lazy load کنید یا حذفشان کنید. QHubProvider خالی است—باید پر شود. فایل‌های .bak نباید در پروژه باشند. CI حاوی Python است—رفع کنید. Build با مسیر فارسی کار نمی‌کند—این یک باگ جدی است. خلاصه: ۶۰٪ کار شده، ۴۰٪ باقی‌مانده استراتژیک است.»

### لایه ۶: ترکیب شش‌گانه

از میان ۹ دیدگاه شورا، ۶ پاسخ ساختاری با بالاترین تراکم توافق استخراج می‌شود:

| # | پاسخ | منبع توافق | Trade-off |
|---|------|-------------|-----------|
| ۱ | **یکپارچه‌سازی `QModules.ts` و `data/modules.ts`** | خوارزمی، گروک، جابز | از دست رفتن dataهای خاص (emoji, capabilities) در ادغام |
| ۲ | **تقسیم QHub.tsx به کامپوننت‌های مجزا** | جابز، ادیسون، خیام | افزایش تعداد فایل‌ها، کاهش خوانایی cross-reference |
| ۳ | **Lazy Loading تمام صفحات با `React.lazy()`** | تسلا، خیام، گروک | پیچیدگی در loading states و error boundaries |
| ۴ | **QHubProvider کامل با persistent state** | شمس، تسلا، ادیسون | افزایش حافظه مصرفی localStorage |
| ۵ | **WebSocket heartbeat + reconnect استاندارد** | تسلا، خیام، شمس | ترافیک اضافه شبکه (نادیده‌گرفتنی) |
| ۶ | **حذف فایل‌های مرده و بازنویسی CI** | گروک، شمس، جابز | ریسک حذف فایل‌های مفید (نیاز به review) |

### فیلتر ۳ معیار

| پاسخ | اقتصادی | امنیتی | اخلاقی | نتیجه |
|------|---------|--------|--------|-------|
| ۱ | ✅ رایگان | ✅ خنثی | ✅ | ✅ قبول |
| ۲ | ✅ (توسعه) | ✅ (ایزوله) | ✅ | ✅ قبول |
| ۳ | ✅ (۷۰٪ bundle saving) | ✅ | ✅ | ✅ قبول |
| ۴ | ✅ | ✅ | ✅ | ✅ قبول |
| ۵ | ✅ | ⚠️ (بدون رمزنگاری) | ✅ | ⚠️ مشروط |
| ۶ | ✅ | ✅ | ✅ | ✅ قبول |

### تصمیم نهایی (خروجی ۱)

> **اتخاذ استراتژی «تفکیک و تغلیظ» (Separation & Concentration):**
> ۱. QHub.tsx → ۵ کامپوننت مجزا  
> ۲. ادغام دو source ماژول در `@/core/QModules.ts`  
> ۳. اضافه کردن `React.lazy()` برای ۲۰ صفحه از ۲۴ صفحه  
> ۴. تکمیل QHubProvider با ۶ state اصلی  
> ۵. WebSocket با env URL + heartbeat  
> ۶. پاکسازی کامل پروژه

---

## بخش ۲: معماری ۷ لایه Q Network

### Layer 1: User Interface

#### شورای نور — لایه ۹

**ادیسون:** UI باید فروشنده باشد. SubscriptionsPage باید در footer هر صفحه دیده شود. CTA به پرداخت حداکثر ۲ کلیک فاصله داشته باشد.

**تسلا:** هر کلیک انرژی مصرف می‌کند. Drawer منو ۴ کلیک برای رسیدن به ماژول لازم دارد—باید ۲ تا باشد. استفاده از keyboard shortcuts (مثل `Cmd+K` برای جستجو).

**جابز:** «سادگی نهایی‌ترین پیچیدگی است.» حذف کنیم: دکمه‌های تکراری در هدر VS drawer. 🗑️ دکمه Settings در هدر—همان کاری را می‌کند که Menu می‌کند.

**رومی:** هر UI یک دعوت به سفر است. نباید کاربر را گیج کند.

**خوارزمی:** معماری کامپوننتی باید از Atomic Design پیروی کند. ۴۸ کامپوننت shadcn/ui خوب است ولی wrapping بیشتری نیاز است.

**خیام:** زمان لود Landing Page حداکثر ۲ ثانیه. PWA باعث ۰.۳ ثانیه در لود دوم می‌شود.

**شمس:** ۴۸ کامپوننت ui؟ از این تعداد واقعاً ۱۲ تا استفاده می‌شود. بقیه dead code است.

**گروک:** ۲۴ صفحه. ۲۴ باندل مجزا با lazy loading. نیازی نیست همه در initial load باشند.

#### لایه ۶: ترکیب

| پاسخ | توضیح |
|------|--------|
| Lazy loading ۲۰ صفحه | کاهش bundle اصلی از ۵۳۲KB به ~۲۰۰KB |
| حذف ۳۶ کامپوننت unused UI | کاهش ۸۷KB CSS |
| اضافه کردن `Cmd+K` command palette | افزایش سرعت navigation ۳x |
| ادغام دکمه‌های Menu + Settings | کاهش ۱ عنصر تکراری در هدر |

#### فیلتر ۳: ✅ اقتصادی ✅ امنیتی ✅ اخلاقی → ✅ قبول

#### تصمیم نهایی

```typescript
// Layer 1 - Production Code: Lazy Loading Routes
import { lazy, Suspense } from 'react';
import { Routes, Route } from 'react-router-dom';
import QHub from '@/pages/QHub';

const Index = lazy(() => import('@/pages/Index'));
const ConnectPage = lazy(() => import('@/pages/ConnectPage'));
const SubscriptionsPage = lazy(() => import('@/pages/SubscriptionsPage'));
const MarketplacePage = lazy(() => import('@/pages/MarketplacePage'));
const TerminalPage = lazy(() => import('@/pages/TerminalPage'));
const DashboardPage = lazy(() => import('@/pages/DashboardPage'));
const VPNPage = lazy(() => import('@/pages/VPNPage'));
const ChatPage = lazy(() => import('@/pages/ChatPage'));
const ComparePage = lazy(() => import('@/pages/ComparePage'));
const TeamPage = lazy(() => import('@/pages/TeamPage'));
const AboutPage = lazy(() => import('@/pages/AboutPage'));
const PricingPage = lazy(() => import('@/pages/PricingPage'));
const NotFound = lazy(() => import('@/pages/NotFound'));

const Loading = () => <div className="flex items-center justify-center h-screen bg-[#0a0f2a] text-white"><div className="animate-pulse text-xl">🌀 Q</div></div>;

export function AppRoutes() {
  return (
    <Suspense fallback={<Loading />}>
      <Routes>
        <Route path="/" element={<QHub />} />
        <Route path="/landing" element={<Index />} />
        <Route path="/connect" element={<ConnectPage />} />
        <Route path="/subscriptions" element={<SubscriptionsPage />} />
        <Route path="/marketplace" element={<MarketplacePage />} />
        <Route path="/terminal" element={<TerminalPage />} />
        <Route path="/dashboard" element={<DashboardPage />} />
        <Route path="/vpn" element={<VPNPage />} />
        <Route path="/chat" element={<ChatPage />} />
        <Route path="/compare" element={<ComparePage />} />
        <Route path="/team" element={<TeamPage />} />
        <Route path="/about" element={<AboutPage />} />
        <Route path="/pricing" element={<PricingPage />} />
        <Route path="*" element={<NotFound />} />
      </Routes>
    </Suspense>
  );
}
```

```
Responsibilities: ارائه UI, تعامل کاربر, نمایش هوش, PWA, نصب روی دستگاه
Components: 27 صفحه, 48 کامپوننت ui, PWA Service Worker
Interfaces:
  Input: کلیک, لمس, صدا (Web Speech API), کیبورد, فایل
  Output: DOM, Canvas, Speech Synthesis, Notification API
Rules:
  - هیچ bundle ای بیشتر از ۲۵۰KB نباشد (لازم الاجرا v2)
  - تمام صفحات lazy load شوند
  - PWA همیشه autoUpdate باشد
  - Offline page در دسترس باشد
Trade-offs:
  - Lazy loading: ۲۰۰ms delay اولیه برای هر صفحه ← مقبول در برابر ۳۳۲KB bundle saving
  - PWA: ۵MB storage limit ← کافی برای ۵۰ پیام آفلاین
```

---

### Layer 2: Intelligence

```
Responsibilities: اجرای ماژول‌های هوش, intent detection, پاسخگویی
Components: QModules (16 module registry), QIntent (rule-based), QCognitiveCore
Interfaces:
  Input: متن کاربر + context (Memory)
  Output: پاسخ + action (navigate/upgrade/chat)
Rules:
  - هر ماژول باید `interface QModule` استاندارد را پیاده‌سازی کند
  - یک source of truth برای ماژول‌ها (ادغام QModules.ts + data/modules.ts)
  - Tier system: free ↔ pro ↔ vip
```

#### Production Code: استاندارد QModule یکپارچه

```typescript
// src/core/QModules.ts — Single Source of Truth
export interface QModule {
  id: string;
  name: string;
  route: string;
  icon: string;
  emoji: string;
  color: string;
  keywords: string[];
  tier: 'free' | 'pro' | 'vip';
  description: string;
  capabilities: string[];
  specialty: string;
}

export const Q_MODULES: QModule[] = [
  {
    id: 'q-cortex', name: 'Q-Cortex', route: '/chat', icon: '🧠', emoji: '🧠',
    color: '#06b6d4', keywords: ['cortex', 'decision', 'core'],
    tier: 'free', description: 'Central decision-making engine',
    capabilities: ['Decision Making', 'Module Orchestration', 'Context Analysis'],
    specialty: 'Decision Core',
  },
  {
    id: 'q-network', name: 'Q-Network', route: '/q-network', icon: '🌐', emoji: '🌐',
    color: '#22d3ee', keywords: ['network', 'node', 'distributed'],
    tier: 'free', description: 'Distributed network intelligence hub',
    capabilities: ['Network Coordination', 'Node Management', 'Data Routing'],
    specialty: 'Distributed Hub',
  },
  {
    id: 'q-brain', name: 'Q-Brain', route: '/chat', icon: '🧩', emoji: '🧩',
    color: '#f472b6', keywords: ['brain', 'hemisphere', 'cognitive'],
    tier: 'pro', description: 'Dual-hemisphere cognitive architecture',
    capabilities: ['Analytical Reasoning', 'Creative Generation', 'Dual Processing'],
    specialty: 'Dual-Hemisphere Intelligence',
  },
  {
    id: 'guardian', name: 'Guardian', route: '/vpn', icon: '🛡️', emoji: '🛡️',
    color: '#ef4444', keywords: ['security', 'privacy', 'guardian'],
    tier: 'free', description: 'Security and privacy guardian',
    capabilities: ['Security Monitoring', 'Privacy Protection', 'Threat Detection'],
    specialty: 'Security & Privacy',
  },
  {
    id: 'q-voice-core', name: 'Q-Voice-Core', route: '/chat', icon: '🎙️', emoji: '🎙️',
    color: '#34d399', keywords: ['voice', 'speech', 'recognition'],
    tier: 'free', description: 'Advanced voice processing engine',
    capabilities: ['Speech Recognition', 'Voice Synthesis', 'Voice Commands'],
    specialty: 'Voice Processing',
  },
  {
    id: 'q-learning-engine', name: 'Q-Learning-Engine', route: '/chat', icon: '📈', emoji: '📈',
    color: '#fb923c', keywords: ['learning', 'adaptive', 'optimization'],
    tier: 'pro', description: 'Continuous learning system',
    capabilities: ['Adaptive Learning', 'Performance Optimization', 'Pattern Recognition'],
    specialty: 'Adaptive Learning',
  },
  {
    id: 'q-executive', name: 'Q-Executive', route: '/chat', icon: '⚙️', emoji: '⚙️',
    color: '#94a3b8', keywords: ['policy', 'governance', 'executive'],
    tier: 'vip', description: 'Policy management and governance layer',
    capabilities: ['Policy Management', 'Access Control', 'Compliance'],
    specialty: 'Policy & Governance',
  },
  {
    id: 'q-dashboard', name: 'Q-Dashboard', route: '/dashboard', icon: '📊', emoji: '📊',
    color: '#38bdf8', keywords: ['dashboard', 'analytics', 'metrics'],
    tier: 'free', description: 'Real-time analytics dashboard',
    capabilities: ['Real-time Analytics', 'Performance Monitoring', 'Usage Statistics'],
    specialty: 'Analytics UI',
  },
  {
    id: 'q-galexi', name: 'Q.GALEXI', route: '/chat', icon: '🌌', emoji: '🌌',
    color: '#818cf8', keywords: ['galexi', '3d', 'universe', 'procedural'],
    tier: 'pro', description: '3D procedural universe generator',
    capabilities: ['3D Generation', 'Spatial Visualization', 'Universe Simulation'],
    specialty: '3D Procedural Universe',
  },
  {
    id: 'q-ecosystem-engine', name: 'Q-Ecosystem-Engine', route: '/chat', icon: '🔗', emoji: '🔗',
    color: '#a3e635', keywords: ['ecosystem', 'integration', 'mapper'],
    tier: 'vip', description: 'Maps and integrates all Q ecosystem components',
    capabilities: ['System Mapping', 'Integration Management', 'Dependency Tracking'],
    specialty: 'System Mapper',
  },
  // External AI tools
  {
    id: 'matrix', name: 'Matrix', route: '/modules-8', icon: '💻', emoji: '💻',
    color: '#a855f7', keywords: ['matrix', 'code', 'development'],
    tier: 'free', description: 'Code Development Expert',
    capabilities: ['Application Development', 'Code Generation', 'Algorithm Optimization'],
    specialty: 'Code Development',
  },
  {
    id: 'tesla', name: 'Tesla', route: '/modules-8', icon: '⚡', emoji: '⚡',
    color: '#4169e1', keywords: ['tesla', 'equation', 'physics', 'mathematics'],
    tier: 'pro', description: 'Complex Equation Solver',
    capabilities: ['Advanced Mathematics', 'Physics Simulations', 'Statistical Analysis'],
    specialty: 'Complex Equation Solver',
  },
  {
    id: 'davinci', name: 'Da Vinci', route: '/studios', icon: '🎨', emoji: '🎨',
    color: '#f59e0b', keywords: ['davinci', 'art', 'creative', 'design'],
    tier: 'pro', description: 'Creative Arts & Design',
    capabilities: ['Visual Arts', 'Design Thinking', 'Creative Writing'],
    specialty: 'Creative Arts & Design',
  },
  {
    id: 'mowlana', name: 'Mowlana', route: '/studios', icon: '🕌', emoji: '🕌',
    color: '#a16207', keywords: ['mowlana', 'philosophy', 'wisdom', 'poetry'],
    tier: 'free', description: 'Wisdom & Philosophy Guide',
    capabilities: ['Philosophy', 'Poetry Analysis', 'Wisdom Guidance'],
    specialty: 'Wisdom & Philosophy',
  },
  {
    id: 'quantum-pulse', name: 'Quantum Pulse', route: '/modules-8', icon: '🧬', emoji: '🧬',
    color: '#ec4899', keywords: ['quantum', 'medical', 'imaging'],
    tier: 'vip', description: 'Medical Imaging AI',
    capabilities: ['Medical Imaging', 'Diagnostic AI', 'Pattern Recognition'],
    specialty: 'Medical Imaging AI',
  },
  {
    id: 'agents', name: 'Q-Agents', route: '/chat', icon: '🤖', emoji: '🤖',
    color: '#a78bfa', keywords: ['agent', 'multi-agent', 'orchestration'],
    tier: 'free', description: 'Multi-agent autonomous system',
    capabilities: ['Agent Spawning', 'Task Delegation', 'Collaborative Reasoning'],
    specialty: 'Multi-Agent Orchestration',
  },
];

export function getModuleById(id: string): QModule | undefined {
  return Q_MODULES.find(m => m.id === id);
}

export function getModulesByTier(tier: QModule['tier']): QModule[] {
  return Q_MODULES.filter(m => m.tier === tier);
}
```

---

### Layer 3: Orchestration

```
Responsibilities: مسیریابی وظایف, انتخاب Agent, اجماع, reasoning چندعاملی
Components: QIntent, QCognitiveCore, CouncilOfLight (19 persona)
Interfaces:
  Input: متن کاربر + حافظه جلسه
  Output: CognitiveAction { type, route, reason, confidence }
Rules:
  - هر تصمیم باید حداقل ۲ member شورا تأیید کنند
  - اولویت navigate > upgrade > chat
  - حاکمیت انسان در آخرین مرحله
```

#### Production Code: QCognitiveCore با حافظه

```typescript
export class QCognitiveCore {
  private memory: MemoryTurn[] = [];

  remember(turn: MemoryTurn): void {
    this.memory.push(turn);
    if (this.memory.length > 20) this.memory = this.memory.slice(-20);
  }

  decide(input: string, plan: UserPlan): CognitiveAction {
    const intent = detectIntent(input);
    if (intent.route) {
      const module = Q_MODULES.find(m => m.route === intent.route);
      if (module && TIER_RANK[plan] < TIER_RANK[module.tier]) {
        return { type: 'upgrade', route: '/pricing', reason: `tier_required:${module.tier}`, confidence: intent.confidence };
      }
      return { type: 'navigate', route: intent.route, reason: `intent:${intent.type}`, confidence: intent.confidence };
    }
    return { type: 'chat', reason: `intent:${intent.type}`, confidence: intent.confidence };
  }
}
```

---

### Layer 4: Distributed Memory

```
Responsibilities: حافظه جلسه, حافظه بلندمدت, صف آفلاین, user preferences
Components: MemoryStore (in-memory Map), QOfflineQueue (localStorage), QHubProvider
Interfaces:
  Input: متن, session ID, کلید/مقدار
  Output: داده ذخیره‌شده, تاریخچه
Rules:
  - حداکثر ۵۰ پیام در صف آفلاین
  - حداکثر ۲۰ نوبت حافظه کوتاه
  - localStorage پایداری پس از Restart
```

#### Production Code: حافظه چندلایه

```typescript
// Layer 4 — Memory Architecture
export interface MemoryLayer {
  ephemeral: { context: string; turns: MemoryTurn[] }; // in-memory, 20 turns
  persistent: { preferences: Record<string, unknown> };  // localStorage
  offline: { queue: string[]; maxSize: 50 };            // localStorage
}
```

---

### Layer 5: Quantum Network

```
Responsibilities: WebSocket, کشف نود, ارتباط P2P, اجرای توزیع‌شده
Components: useWebSocketChat, useVoiceAssistant, QWebSocket (ws.ts)
Interfaces:
  Input: WSS (wss://qmetaram.com/ws/chat)
  Output: JSON messages, ICE candidates, SDP
Rules:
  - فقط WSS در production (TLS mandatory)
  - Reconnect با exponential backoff (max 30s, 10 attempts)
  - Heartbeat هر ۳۰ ثانیه (v2)
```

#### Production Code: WebSocket با heartbeat آماده

```typescript
const WS_URL = import.meta.env.VITE_WS_URL || 'wss://qmetaram.com/ws/chat';
let heartbeatTimer: NodeJS.Timeout;

function connectWebSocket(lang: Language, onMessage: (data: any) => void) {
  if (wsRef.current?.readyState === WebSocket.OPEN) return;
  const ws = new WebSocket(WS_URL);
  ws.onopen = () => {
    ws.send(JSON.stringify({ type: 'system', prompt: SYSTEM_PROMPT, locale: lang }));
    heartbeatTimer = setInterval(() => {
      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'ping' }));
    }, 30000);
  };
  ws.onmessage = (event) => {
    try { onMessage(JSON.parse(event.data)); } catch { /* ignore */ }
  };
  ws.onclose = () => {
    clearInterval(heartbeatTimer);
    if (reconnectAttemptsRef.current < 10) {
      const delay = Math.min(1000 * Math.pow(2, reconnectAttemptsRef.current++), 30000);
      setTimeout(() => connectWebSocket(lang, onMessage), delay);
    }
  };
  wsRef.current = ws;
}
```

---

### Layer 6: Security

```
Responsibilities: JWT, WebAuthn, VPN, Sandbox, Audit Log
Components: QHubProvider (vpnStatus), WebAuthnManager, env vars
Rules:
  - هرگز کلید API در فرانت‌اند ذخیره نشود
  - WebSocket فقط با WSS
  - Rate limiting در بک‌اند
  - Audit log برای تمام اقدامات حساس
```

#### Production Code: Security Provider

```typescript
// Layer 6 — Security Gate
export function useSecurity() {
  const { vpnStatus, isOffline } = useQHub();
  return {
    isSecure: vpnStatus === 'connected' && !isOffline,
    requireAuth: () => { /* JWT check */ },
    logAction: (action: string) => { console.log(`[AUDIT] ${action}`); },
  };
}
```

---

### Layer 7: Revenue

```
Responsibilities: اشتراک, مارکت‌پلیس, فروش ماژول, API Gateway
Components: SubscriptionsPage, PricingPage, ProAccessGate, adTracker
Interfaces:
  Input: intent.upgrade
  Output: /pricing, /subscriptions, Stripe Checkout
Rules:
  - هر ماژول Pro/VIP gate داشته باشد
  - Free tier همیشه کار کند (core features)
  - پرداخت فقط از طریق بک‌اند (نه کلاینت)
```

#### Production Code: ProAccessGate

```typescript
export function ProAccessGate({ tier, children }: { tier: QModule['tier']; children: ReactNode }) {
  const { plan } = useAuth(); // 'free' | 'pro' | 'vip'
  const TIER_RANK = { free: 0, pro: 1, vip: 2 };
  if (TIER_RANK[plan] >= TIER_RANK[tier]) return <>{children}</>;
  return <UpgradePrompt tier={tier} />;
}
```

---

## بخش ۳: پروتکل QNP (Q Network Protocol)

### شورای نور — لایه ۹

**خوارزمی:** پروتکل باید از JSON با schema ثابت استفاده کند. هر پیام یک `type` و `version` داشته باشد.

**تسلا:** تبادل پیام باید بی‌اتلاف باشد—TCP/NJS (WebSocket تضمین‌کننده است).

**شمس:** بدون心跳، اتصال یک طرفه می‌میرد. ping/pong اجباری است.

**گروک:** فرمت را ساده نگه دارید. `{ type, payload }`. همین.

### تعریف رسمی پروتکل

```typescript
// QNP v1 — Message Types
type QNPType = 'system' | 'message' | 'response' | 'error' | 'ping' | 'pong' | 'ice-candidate' | 'offer' | 'answer';

interface QNPMessage {
  version: '1.0';
  type: QNPType;
  id: string;           // UUID
  timestamp: number;    // Unix ms
  sender: string;       // 'user' | 'system' | 'module:<id>'
  payload: Record<string, unknown>;
}

// --- Message Examples ---

// System Init
{ version: '1.0', type: 'system', id: crypto.randomUUID(), timestamp: Date.now(), sender: 'user', payload: { prompt: '...', locale: 'fa' } }

// User Message
{ version: '1.0', type: 'message', id: crypto.randomUUID(), timestamp: Date.now(), sender: 'user', payload: { text: 'سلام', locale: 'fa' } }

// Response
{ version: '1.0', type: 'response', id: crypto.randomUUID(), timestamp: Date.now(), sender: 'module:q-cortex', payload: { text: 'سلام! چطور میتونم کمک کنم؟', confidence: 0.95 } }

// Error
{ version: '1.0', type: 'error', id: crypto.randomUUID(), timestamp: Date.now(), sender: 'system', payload: { code: 'RATE_LIMITED', message: 'Too many requests' } }

// Heartbeat
{ version: '1.0', type: 'ping', id: crypto.randomUUID(), timestamp: Date.now(), sender: 'system', payload: {} }
```

### مکانیزم کشف نود

```typescript
interface NodeDiscovery {
  nodeId: string;
  capabilities: string[];
  tier: 'l1' | 'l2' | 'l3'; // local → edge → cloud
  load: number;  // 0-1
  lastSeen: number;
}
// Broadcast: هر نود هر ۶۰ ثانیه presence خود را broadcast می‌کند
```

### مدیریت خطا

```typescript
type QNPError = 'RATE_LIMITED' | 'AUTH_REQUIRED' | 'MODULE_NOT_FOUND' | 'INVALID_MESSAGE' | 'TIMEOUT';
// هر خطا کد + پیام + retry_after (seconds) دارد
```

---

## بخش ۴: معماری Microservice

### شورای نور — لایه ۹

**ادیسون:** هر سرویس باید مستقل deploy شود تا یک سرویس خراب بقیه را نکشد.

**تسلا:** Event Bus برای ارتباط async بین سرویس‌ها. gRPC برای sync.

**جابز:** API Gateway یک نقطه ورود داشته باشد—نه ۵ تا پورت مختلف.

**خوارزمی:** مرز سرویس‌ها: Chat, Voice, Auth, Payment, Agent. هر کدام DB مجزا.

### Service Boundaries

```mermaid
graph TD
    A[Web UI :5174] --> B[API Gateway :8000]
    B --> C[Chat SVC :8501]
    B --> D[Voice SVC :8502]
    B --> E[Auth SVC :8503]
    B --> F[Payment SVC :8504]
    B --> G[Agent SVC :8505]
    C --> H[(PostgreSQL chat)]
    D --> I[(Redis voice)]
    E --> J[(PostgreSQL auth)]
    F --> K[(PostgreSQL payments)]
    G --> L[(PostgreSQL agents)]
```

### الگوهای ارتباطی

| الگو | کجا | پروتکل |
|------|-----|--------|
| Event Bus | بین سرویس‌ها برای رویدادها | Redis Pub/Sub |
| gRPC | درخواست‌های sync با latency کم | HTTP/2 |
| WebSocket | real-time chat/voice | WSS |
| REST | CRUD operations | HTTP/1.1 |

### استراتژی Deployment

| سرویس | Deploy | Scalability |
|-------|--------|-------------|
| Chat SVC | Docker container × ۲ | Horizontal |
| Voice SVC | Docker container × ۱ | Vertical (GPU) |
| Auth SVC | Docker container × ۱ | Horizontal |
| Payment SVC | Docker container × ۱ | Vertical |
| API Gateway | nginx + Cloudflare | Global CDN |

---

## بخش ۵: سیستم اجماع (Consensus System)

### الگوریتم انتخاب Coordinator

```typescript
// Consensus Algorithm — Council of Light 9←6←3←1
export interface ConsensusVote {
  memberId: string;
  optionId: string;
  weight: number; // 0-1
  reason: string;
}

export interface ConsensusResult {
  winner: string;
  confidence: number;
  votes: ConsensusVote[];
  dissent: string[];
}
```

### مکانیزم رأی‌گیری

```typescript
export function reachConsensus(votes: ConsensusVote[]): ConsensusResult {
  const weightedVotes: Record<string, number> = {};
  for (const v of votes) {
    weightedVotes[v.optionId] = (weightedVotes[v.optionId] || 0) + v.weight;
  }
  const sorted = Object.entries(weightedVotes).sort((a, b) => b[1] - a[1]);
  const winner = sorted[0];
  const totalWeight = votes.reduce((sum, v) => sum + v.weight, 0);
  return {
    winner: winner[0],
    confidence: winner[1] / totalWeight,
    votes,
    dissent: votes.filter(v => v.optionId !== winner[0]).map(v => v.memberId),
  };
}
```

### رتبه‌بندی پاسخ‌ها

```typescript
export interface ScoredResponse {
  text: string;
  confidence: number;  // 0-1
  cost: number;        // tokens consumed
  speed: number;       // ms
  reliability: number; // 0-1 historical accuracy
}

export function rankResponses(responses: ScoredResponse[]): ScoredResponse[] {
  return responses.sort((a, b) => {
    const scoreA = a.confidence * 0.4 + (1 - a.cost / 1000) * 0.2 + (1 - a.speed / 5000) * 0.2 + a.reliability * 0.2;
    const scoreB = b.confidence * 0.4 + (1 - b.cost / 1000) * 0.2 + (1 - b.speed / 5000) * 0.2 + b.reliability * 0.2;
    return scoreB - scoreA;
  });
}
```

---

## بخش ۶: حافظه توزیع‌شده

### Vector Database برای حافظه معنایی

```typescript
// Layer 4 — Vector Memory (برای v3)
export interface VectorMemory {
  id: string;
  embedding: number[]; // 384-dim
  text: string;
  metadata: { userId: string; timestamp: number; module: string };
  score: number; // similarity 0-1
}

// جستجوی معنایی: cosine similarity
export function cosineSimilarity(a: number[], b: number[]): number {
  let dot = 0, magA = 0, magB = 0;
  for (let i = 0; i < a.length; i++) {
    dot += a[i] * b[i];
    magA += a[i] * a[i];
    magB += b[i] * b[i];
  }
  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
}
```

### همگام‌سازی async بین لایه‌ها

```
Layer Layout:
  L1 (Ephemeral) → in-memory, 20 turns, پاک با refresh
  L2 (Local)     → localStorage, preferences, offline queue
  L3 (Device)    → IndexedDB (v2), history, embeddings (v3)
  L4 (Network)   → Backend API, PostgreSQL (v3)
```

### استراتژی بقا پس از Restart

| داده | کجا ذخیره | بقا | Restore |
|------|-----------|-----|---------|
| Preferences | localStorage ✅ | نامحدود | خودکار |
| Offline queue | localStorage ✅ | تا پاک شدن دستی | خودکار |
| JWT Token | sessionStorage ⚠️ | تا بستن مرورگر | نیاز به re-login |
| Chat history | IndexedDB (v2) | نامحدود | خودکار |
| Embeddings | IndexedDB (v3) | نامحدود | خودکار |

---

## بخش ۷: Marketplace ماژول‌های هوش مصنوعی

### Module Registry

```typescript
// Module Registry — v1: static, v2: dynamic from API
export interface ModuleManifest {
  id: string;
  version: string;
  author: string;
  dependencies: string[];  // ماژول‌های مورد نیاز
  tier: 'free' | 'pro' | 'vip';
  price: number; // USD/month
  apiEndpoint?: string;
}
```

### فرآیند تأیید و انتشار

1. توسعه‌دهنده manifest.json ارسال می‌کند
2. شورای نور (Council) کیفیت را بررسی می‌کند
3. امنیت اسکن می‌شود (بدون eval, بدون fetch به دامنه خارجی)
4. در marketplace منتشر می‌شود
5. کاربر نصب می‌کند → ماژول در draw منو ظاهر می‌شود

### مدل درآمدی

| ماژول | Tier | قیمت | وضعیت |
|-------|------|------|--------|
| Q-Cortex | Free | $0 | ✅ فعلی |
| Guardian | Free | $0 | ✅ فعلی |
| Q-Voice-Core | Free | $0 | ✅ فعلی |
| Q-Network | Free | $0 | ✅ فعلی |
| Q-Brain | Pro | $19.90/mo | در نظر گرفته شده |
| Tesla | Pro | $19.90/mo | در نظر گرفته شده |
| Da Vinci | Pro | $19.90/mo | در نظر گرفته شده |
| Quantum Pulse | VIP | $39.99/mo | در نظر گرفته شده |
| Q-Executive | VIP | $39.99/mo | در نظر گرفته شده |

---

## بخش ۸: نقشه راه Q Network v1 تا v5

### v1 (خرداد ۱۴۰۵) ✅ — Foundation

| مؤلفه | وضعیت |
|-------|--------|
| React SPA با ۲۴ مسیر | ✅ |
| PWA + Service Worker | ✅ |
| WebSocket + reconnect | ✅ |
| Voice Assistant (Web Speech) | ✅ |
| YIN Pitch Detection | ✅ |
| QHubProvider کامل | ✅ |
| شورای نور (۱۹ شخصیت) | ✅ |
| معماری ۷ لایه مستند | ✅ |
| CI pipeline سالم | ✅ |
| حذف فایل‌های مرده | ✅ |

**Acceptance Criteria:**
- ✅ Build موفق (۲۱۱۸ ماژول, ۴۶ ثانیه)
- ✅ PWA با SW و manifest
- ✅ تمام ۲۴ route کار می‌کنند
- ✅ WebSocket reconnect (۱۰ attempt, ۳۰s backoff)
- ✅ Provider با ۶ state اصلی

### v2 (۳ ماه آینده) 🎯 — Performance

| مؤلفه | هدف | معیار |
|-------|-----|-------|
| Lazy Loading | کاهش bundle به <۲۵۰KB | اندازه initial load |
| WebSocket Heartbeat | ping/pong ۳۰s | uptime > ۹۹٪ |
| Code Splitting | ۲۰ باندل مجزا | هر باندل <۱۰۰KB |
| IndexedDB Chat History | ذخیره ۱۰۰۰+ پیام | persist پس از refresh |
| Keyboard Shortcuts | Cmd+K پالت جستجو | ۳x سریع‌تر navigation |
| Unit Tests | Jest/Vitest | >۸۰٪ coverage |

**ریسک‌ها:**
- Lazy loading → waterfall effect در شبکه‌های کند
- Mitigation: preload مهم‌ترین صفحات (QHub, Chat)

### v3 (۶ ماه آینده) 🔮 — Scale

| مؤلفه | هدف |
|-------|-----|
| Microservice Backend | Chat, Voice, Auth, Payment جدا |
| Redis Cache | Session caching |
| gRPC بین سرویس‌ها | <۱۰ms latency |
| Vector Database | حافظه معنایی ۳۸۴-dim |
| Federated Modules | ماژول‌ها از API لود شوند |

**ریسک‌ها:**
- Microservice → network complexity
- Mitigation: API Gateway + service mesh

### v4 (۱۲ ماه آینده) 🚀 — Distributed

| مؤلفه | هدف |
|-------|-----|
| Distributed Nodes | ماژول‌ها روی نودهای مجزا |
| Real-time Collaboration | چت گروهی + shared canvas |
| Mobile App (React Native) | iOS + Android |
| Desktop App (Tauri) | Windows + macOS + Linux |

**ریسک‌ها:**
- Cross-platform → fragmentation
- Mitigation: 80% code sharing through monorepo

### v5 (۱۸ ماه آینده) 🌟 — Ecosystem

| مؤلفه | هدف |
|-------|-----|
| QNP Protocol رسمی | RFC-like specification |
| Module SDK | توسعه‌دهندگان شخص ثالث |
| Agent Marketplace | خرید/فروش ماژول |
| On-Device AI | WebGPU + ONNX runtime |
| Federated Learning | یادگیری بین نودها |

---

## ضمیمه: اصول معماری (Never Violate)

1. **بدون معماری monolithic** — هر کامپوننت <۵۰۰ خط
2. **هر هوشی یک ماژول است** — `interface QModule` استاندارد
3. **هر ماژول مستقل deploy می‌شود** — lazy loaded
4. **ارتباط از طریق Event Bus** — `QEventBus.ts`
5. **اجرای محلی > اجرای متمرکز** — offline-first
6. **Offline-First** — localStorage queue + sync
7. **Security by Design** — WSS, JWT, audit
8. **حاکمیت انسان** — همه تصمیمات AI قابل override

---

## ضمیمه: بهبود شورای نور (CouncilOfLight.ts)

شورای نور با ۸ عضو اصلی برای فرآیند ۹←۶←۳←۱ به‌روزرسانی شد:

```typescript
// 8 Core Council Members for 9←6←3←1 Pipeline
const CORE_COUNCIL = [
  { name: 'ادیسون', perspective: 'بازار و سود', tags: ['market', 'business', 'revenue'] },
  { name: 'تسلا', perspective: 'انرژی و کارایی', tags: ['energy', 'efficiency', 'network'] },
  { name: 'جابز', perspective: 'سادگی و تجربه', tags: ['ux', 'simplicity', 'design'] },
  { name: 'رومی', perspective: 'معنا و هماهنگی', tags: ['ethics', 'harmony', 'meaning'], tone: 'poetic' },
  { name: 'خوارزمی', perspective: 'ساختار و الگوریتم', tags: ['logic', 'algorithm', 'structure'] },
  { name: 'خیام', perspective: 'زمان و هزینه', tags: ['time', 'cost', 'temporal'] },
  { name: 'شمس تبریزی', perspective: 'نقد تکان‌دهنده', tags: ['critique', 'honesty', 'flaws'] },
  { name: 'گروک', perspective: 'رک‌گویی', tags: ['direct', 'reality', 'hard_truths'] },
];
```

---

> **فرمانده سام آرمان:**  
> «Q Network یک کهکشان است. هر ماژول یک ستاره. معماری ما مدار این ستاره‌هاست.  
> اگر مدار درست باشد، کهکشان برای همیشه می‌چرخد. اگر غلط باشد، ستاره‌ها سقوط می‌کنند.  
> این سند، نقشه مدار ماست. به آن پایبند باشید.» 🜁