معماری¶

مخزن یک monorepo است: SPA React 19 + Vite + TypeScript و API Express که فیدهای عمومی را تجمیع می‌کند. SPA مستقیماً با NVD/OSV صحبت نمی‌کند؛ همهٔ ترافیک خروجی از سرور است تا کلید، کش و محدودیت نرخ متمرکز بماند.

این فصل پوشه‌ها را به مسئولیت‌ها نگاشت می‌کند و یکپارچه‌سازها را به OpenAPI زمان اجرا ارجاع می‌دهد.

توپولوژی سطح بالا¶

flowchart LR
  classDef ui fill:#e9edf5,stroke:#00baba,color:#253343
  classDef api fill:#f3fcfc,stroke:#008c8c,color:#253343
  classDef ext fill:#fff7ed,stroke:#eda232,color:#253343

  Browser[SPA مرورگر]:::ui --> API[Express /api]:::api
  API --> NVD[NVD]:::ext
  API --> OSV[OSV]:::ext
  API --> GH[GitHub]:::ext
  API --> CISA[CISA KEV]:::ext
  API --> RSS[RSS]:::ext

شرح نمودار¶

مرورگر پشته، locale و toggle منابع را در localStorage نگه می‌دارد و POST /api/scan یا POST /api/watch می‌زند. لایهٔ API بدنهٔ JSON را اعتبارسنجی، scanStack را فراخوانی و آسیب‌پذیری‌های ادغام‌شده برمی‌گرداند.

مسیر درخواست (اسکن کامل)¶

server/routes/scan.ts دریافت POST /scan.
server/handlers/scanHandlers.ts با stackValidation.ts پارس می‌کند.
scanStack منابع فعال و RSS سفارشی را حل می‌کند.
fetch موازی هر ابزار؛ ادغام و مرتب‌سازی.
در translate: true، enrichVulnsWithTranslations.
JSON ScanResponse به کلاینت برمی‌گردد؛ persistLastScan در src/lib/scanCache.ts مقدار cve-radar:last-scan را با کلید پشته می‌نویسد.

لایهٔ پایگاه‌داده (PostgreSQL اختیاری)¶

وقتی DATABASE_URL تنظیم است، فرادادهٔ اسکن در PostgreSQL از طریق server/db/scanHistory.ts و پشته‌های tenant از server/db/tenants.ts پایدار می‌ماند. migrationهای SQL در server/db/migrations/*.sql هستند و در راه‌اندازی pool به‌صورت خودکار اجرا می‌شوند.

تعاریف schema type-safe برای migration تدریجی ORM در server/db/schema.ts (Drizzle ORM) قرار دارند. server/db/drizzle.ts تابع getDb() را با pool مشترک pg در اختیار می‌گذارد. persistence مربوط به tenant و scan-history (server/db/tenants.ts، server/db/scanHistory.ts) از query builderهای Drizzle استفاده می‌کند؛ migrationهای SQL در server/db/migrations/*.sql همچنان در راه‌اندازی pool اجرا می‌شوند.

سرویس‌های اعلان¶

هشدارهای watch سمت سرور از server/services/notifications/NotificationService.ts استفاده می‌کنند. آداپترهای کانال (Slack، Discord، Telegram، SMTP، webhook عمومی) متغیرهای env مستند در پیکربندی را می‌خوانند. server/services/alerts.ts برای سازگاری با ALERT_WEBHOOK_URL به این سرویس واگذار می‌کند.

لایهٔ قرارداد مشترک¶

انواع و ترتیب severity در shared/ (shared/api/vulnerability.ts، shared/constants/severityOrder.ts) قرار دارند. هر دو src/ و server/ از @shared/* import می‌کنند؛ server/types.ts برای سازگاری عقب‌رو re-export می‌کند. npm run build:server پوشهٔ shared/ را در dist-server/ کامپایل می‌کند.

لایهٔ API¶

ماژول	نقش
`server/index.ts`	mount روترها
`server/routes/health.ts`	`GET /health`
`server/routes/meta.ts`	capabilities، sources، openapi
`server/routes/scan.ts`	scan، watch، validate
`server/routes/v1.ts`	همان handlerها با پیشوند v1
`server/handlers/scanHandlers.ts`	منطق مشترک
`server/openapi/spec.json`	قرارداد OpenAPI 3.1

مسیرهای legacy زیر /api/* باقی‌اند؛ یکپارچه‌سازی جدید /api/v1/* را ترجیح دهد.

نقشهٔ فرانت‌اند¶

ناحیه	مسیر
پوسته	`src/components/layout/AppShell.tsx`, `SubNav.tsx`, `SetupWizard.tsx`
تب‌ها	`src/components/tabs/*`
کش اسکن	`src/lib/scanCache.ts`
کلاینت API	`src/api/scan.ts`, `watch.ts`, `scanPayload.ts`
i18n	`src/i18n/messages/*.ts`
قلاب‌ها	`useVulnScan`, `useWatch`, `useVulnTranslations`, `useFontScale`
Middleware	`server/middleware/rateLimit.ts`, `scanTimeout.ts`

سرویس‌های بک‌اند¶

ارائه‌دهنده	ماژول
NVD	`server/services/nvd.ts`
OSV	`server/services/osv.ts`
GitHub	`server/services/github.ts`
CISA KEV	`server/services/cisa.ts`
RSS	`server/services/rss.ts`
ترجمه	`server/services/translate.ts`

کش و محدودیت‌ها¶

کش در حافظه (server/lib/cache.ts) برای XML RSS و رشته‌های ترجمه. تأخیر NVD از server/lib/rateLimit.ts (هماهنگ‌سازی upstream). محدودیت نرخ درخواست برای scan/watch در server/middleware/rateLimit.ts اعمال می‌شود (سطل‌های جداگانه؛ validate معاف). نتایج اسکن سمت کلاینت از طریق scanCache.ts در localStorage باقی می‌ماند. GET /api/capabilities با اعتبارسنجی (۵۰ ابزار، ۲۰ فید سفارشی) هم‌خوان است.

بعدی: هشدارها