system design for youtube sample

دیاگرام های C4

openapi: 3.0.0
info:
  title: VideoVerse Video API
  version: 1.0.0
paths:
  /videos/{videoId}:
    get:
      summary: Get Video Details
      parameters:
        - name: videoId
          in: path
          required: true
          schema:
           type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
  /videos/{videoId}/comments:
    get:
      summary: Get Comments for a Video
      parameters:
        - name: videoId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of comments
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
    post:
      summary: Add a new comment
      parameters:
        - name: videoId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
      responses:
        '21':
          description: Comment created
# ... (Schema definitions for Video, Comment, etc.)

ADR-001: تضمین قابلیت اطمینان (Reliability)

• وضعیت: پذیرفته شده

• تاریخ: 2024-05-22

• تصمیم‌گیرندگان: معمار ارشد نرم‌افزار، سرپرست تیم فرانت‌اند

• زمینه و مشکل (Context): یک پلتفرم ویدیویی باید همیشه در دسترس باشد. هرگونه قطعی یا خطا در سمت فرانت‌اند (مانند عدم بارگذاری ویدیوها، کار نکردن دکمه‌ها) مستقیماً به تجربه کاربری آسیب زده و باعث از دست رفتن کاربران می‌شود. فرانت‌اند باید در برابر خطاهای شبکه، پاسخ‌های ناموفق API و مشکلات غیرمنتظره مقاوم باشد.

• گزینه‌های بررسی‌شده (Options Considered):

  1. مدیریت خطای ساده: نمایش یک پیام خطای عمومی (مثلاً "An error occurred") در صورت بروز مشکل.

     • مزایا: پیاده‌سازی سریع و آسان.

     • معایب: تجربه کاربری ضعیف، عدم ارائه راهکار به کاربر، عدم تمایز بین خطاهای موقتی و دائمی.

  2. الگوهای پیشرفته مقاومت در برابر خطا (Resiliency Patterns): پیاده‌سازی مکانیزم‌های هوشمند برای مدیریت خطا. این شامل تلاش مجدد خودکار (Retry with Exponential Backoff) برای خطاهای موقتی شبکه، نمایش داده‌های کش‌شده در صورت عدم دسترسی به سرور، و ارائه پیام‌های خطای مشخص و کاربردی است.

     • مزایا: تجربه کاربری بسیار بهتر، حفظ عملکرد برنامه تا حد ممکن حتی در شرایط نامساعد.

     • معایب: پیچیدگی بیشتر در پیاده‌سازی و نیاز به استفاده صحیح از ابزارهایی مانند RxJS.

• تصمیم نهایی (Decision): ما گزینه ۲ (الگوهای پیشرفته مقاومت در برابر خطا) را انتخاب می‌کنیم. یک Angular HTTP Interceptor سراسری برای مدیریت خطاها پیاده‌سازی خواهد شد. این Interceptor با استفاده از اپراتورهای RxJS مانند retry() و catchError():

  • درخواست‌های ناموفق ��ه دلیل مشکلات موقتی شبکه را به صورت خودکار با فاصله زمانی فزاینده تکرار می‌کند.

  • خطاهای سمت کلاینت (4xx) و سرور (5xx) را تشخیص داده و به یک سرویس لاگینگ مرکزی ارسال می‌کند.

  • برای کاربر پیام‌های قابل فهم نمایش می‌دهد (مثلاً "ارتباط با سرور برقرار نشد، لطفاً لحظاتی بعد تلاش کنید.").

  • همچنین از Service Worker برای کش کردن داده‌های کلیدی (مانند اطلاعات پروفایل کاربر) استفاده خواهیم کرد تا در حالت آفلاین نیز بخشی از برنامه قابل استفاده باشد (Progressive Web App - PWA).

• پیامدها و بده‌بستان‌ها (Consequences):

  • مثبت: افزایش چشمگیر پایداری و قابلیت اطمینان برنامه از دید کاربر. کاهش گزارش‌های خطا به دلیل مشکلات موقتی.

  • منفی: افزایش جزئی در پیچیدگی کد، به خصوص در بخش مدیریت state و عملیات آسنکرون. نیاز به آموزش تیم برای استفاده صحیح از الگوهای RxJS.

• اقدامات بعدی (Follow-up Actions):

  • پیاده‌سازی GlobalErrorHandlingInterceptor.

  • پیکربندی NgRx Effects برای مدیریت صحیح اکشن‌های خطا.

  • افزودن قابلیت‌های PWA با استفاده از @angular/pwa.

  • نوشتن مستندات برای الگوهای مدیریت خطا در تیم.

ADR-002: پیاده‌سازی بومی‌سازی (Localization)

• وضعیت: پذیرفته شده

• تاریخ: 2024-05-22

• تصمیم‌گیرندگان: معمار ارشد نرم‌افزار، سرپرست تیم فرانت‌اند

• زمینه و مشکل (Context): برای دستیابی به مخاطب جهانی، پلتفرم VideoVerse باید از چندین زبان و فرهنگ مختلف پشتیبانی کند. این نیازمندی (i18n) شامل ترجمه تمام متون رابط کاربری و همچنین بومی‌سازی فرمت‌های تاریخ، زمان و اعداد (L10n) است.

• گزینه‌های بررسی‌شده (Options Considered):

  1. استفاده از i18n داخلی Angular: این ابزار قدرتمند و یکپارچه با فریمورک است. در زمان build، برای هر زبان یک نسخه جداگانه از اپلیکیشن تولید می‌کند.

     • مزایا: عملکرد بسیار بالا در زمان اجرا (چون ترجمه‌ها از قبل کامپایل شده‌اند)، یکپارچگی کامل با فریمورک.

     • معایب: تغییر زبان در زمان اجرا نیازمند بارگذاری مجدد کامل برنامه است که تجربه کاربری ایده‌آلی نیست. مدیریت فایل‌های ترجمه (مانند XLIFF) می‌تواند کمی پیچیده باشد.

  2. استفاده از کتابخانه @ngx-translate: یک کتابخانه محبوب شخص ثالث که امکان تغییر زبان را در زمان اجرا (run-time) بدون نیاز به رفرش صفحه فراهم می‌کند.

     • مزایا: تجربه کاربری عالی برای تغییر زبان، مدیریت آسان فایل‌های ترجمه (معمولاً JSON)، پشتیبانی گسترده جامعه.

     • معایب: بارگذاری و پردازش ترجمه‌ها در زمان اجرا ممکن است تأثیر جزئی و قابل چشم‌پوشی بر عملک��د اولیه داشته باشد.

• تصمیم نهایی (Decision): ما گزینه ۲ (کتابخانه @ngx-translate) را انتخاب می‌کنیم. تجربه کاربری مدرن ایجاب می‌کند که کاربر بتواند زبان را به صورت آنی تغییر دهد. این کتابخانه این قابلیت را به بهترین شکل فراهم می‌کند. ما یک TranslationService خواهیم ساخت که @ngx-translate را کپسوله کرده و منطق بارگذاری فایل‌های زبان بر اساس زبان انتخابی کاربر یا زبان مرورگر را مدیریت می‌کند.

• پیامدها و بده‌بستان‌ها (Consequences):

  • مثبت: ارائه تجربه کاربری برتر در زمینه چندزبانگی. فرآیند افزودن زبان جدید ساده‌تر خواهد بود.

  • منفی: افزودن یک وابستگی شخص ثالث به پروژه. باید اطمینان حاصل کنیم که بارگذاری فایل‌های JSON زبان به صورت بهینه (lazy-loaded) انجام می‌شود تا بر زمان بارگذاری اولیه تأثیر منفی نگذارد.

• اقدامات بعدی (Follow-up Actions):

  • نصب و پیکربندی کتا��خانه @ngx-translate/core و @ngx-translate/http-loader.

  • ایجاد ساختار پوشه برای فایل‌های ترجمه JSON (مثلاً assets/i18n/en.json, assets/i18n/fa.json).

  • پیاده‌سازی TranslationService و ادغام آن در AppComponent.

  • جایگزینی متون ثابت در کامپوننت‌ها با pipe translate.

ADR-003: تضمین قابلیت ارتقا (Upgradability)

• وضعیت: پذیرفته شده

• تاریخ: 2024-05-22

• تصمیم‌گیرندگان: معمار ارشد نرم‌افزار، سرپرست تیم فرانت‌اند

• زمینه و مشکل (Context): VideoVerse یک پروژه بلندمدت است. اکوسیستم فرانت‌اند به سرعت در حال تحول است و فریمورک Angular نیز به طور منظم نسخه‌های جدید با بهبودهای عملکردی، امنیتی و ویژگی‌های جدید منتشر می‌کند. معماری ما باید به گونه‌ای باشد که به‌روزرسانی به نسخه‌های جدید Angular و سایر کتابخانه‌ها با حداقل هزینه و ریسک ممکن انجام شود.

• گزینه‌های بررسی‌شده (Options Considered):

  1. ساختار پروژه استاندارد Angular CLI: استفاده از ساختار پیش‌فرض که توسط Angular CLI ایجاد می‌شود.

     • مزایا: سادگی و شروع سریع. ابزار ng update به خوبی کار می‌کند.

     • معایب: در مقیاس بسیار بزرگ، مدیریت وابستگی‌ها بین ماژول‌های مختلف و اعمال قوانین معماری می‌تواند چالش‌برانگیز شود و فرآیند ارتقا را پیچیده کند.

  2. استفاده از یک Monorepo با ابزارهای پیشرفته (مانند Nx): قرار دادن تمام کدهای فرانت‌اند (و حتی بک‌اند) در یک مخزن واحد (monorepo) و مدیریت آن با ابزاری مانند Nx.

     • مزایا: Nx ابزارهای قدرتمندی برای تعریف مرز بین ماژول‌ها، تحلیل گراف وابستگی‌ها، اجرای تست‌ها و buildها به صورت هوشمند (فقط برای کدهای تغییریافته) و مدیریت یکپارچه به‌روزرسانی‌ها ارائه می‌دهد. این ساختار، مقیاس‌پذیری و ارتقاپذیری را به شدت بهبود می‌بخشد.

     • معایب: نیاز به یادگیری ابزار Nx و پیکربندی اولیه پیچیده‌تر.

• تصمیم نهایی (Decision): ما گزینه ۲ (Monorepo با Nx) را انتخاب می‌کنیم. با توجه به مقیاس و طول عمر پروژه، سرمایه‌گذاری اولیه برای یادگیری و راه‌اندازی Nx، در بلندمدت با ساده‌سازی فرآیندهای توسعه، تست و به‌روزرسانی، بازدهی بسیار بالایی خواهد داشت. با استفاده از Nx، می‌توانیم ماژول‌های اصلی (مانند watch-page, upload, shared-ui) را به عنوان کتابخانه‌های داخلی تعریف کرده و وابستگی‌های بین آن‌ها را به دقت کنترل کنیم. این کار فرآیند ng update را بسیار قابل پیش‌بینی و ایمن‌تر می‌کند.

• پیامدها و بده‌بستان‌ها (Consequences):

  • مثبت: معماری بسیار تمیز و مقیاس‌پذیر. فرآیندهای ارتقا و نگهداری در آینده بسیار ساده‌تر خواهند بود. بهبود سرعت CI/CD به دلیل buildها و تست‌های هوشمند.

  • منفی: افزایش پیچیدگی اولیه پروژه و نیاز به آشنایی تیم با مفاهیم Monorepo و ابزار Nx.

• اقدامات بعدی (Follow-up Actions):

  • ایجاد پروژه با استفاده از create-nx-workspace.

  • مهاجرت ساختار اولیه به کتابخانه‌های قابل انتشار (publishable libraries) درون monorepo.

  • تنظیم قوانین لینت برای کنترل وابستگی‌ها بین کتابخانه‌ها (e.g., feature libraries should not depend on each other).

  • آموزش تیم برای کار با دستورات Nx CLI.

ADR-004: بهینه‌سازی کاربردپذیری (Usability)

• وضعیت: پذیرفته شده

• تاریخ: 2024-05-22

• تصمیم‌گیرندگان: معمار ارشد نرم‌افزار، سرپرست تیم فرانت‌اند، طراح UI/UX

• زمینه و مشکل (Context): کاربردپذیری به معنای سهولت استفاده از محصول برای دستیابی به اهداف است. این شامل طراحی واکنش‌گرا (Responsive) برای نمایش صحیح در تمام دستگاه‌ها (موبایل، تبلت، دسکتاپ) و دسترس‌پذیری (Accessibility) برای کاربران با توانایی‌های محدود (مانند کاربران نابینا که از صفحه‌خوان استفاده می‌کنند) است.

• گزینه‌های بررسی‌شده (Options Considered):

  1. توسعه کامپوننت‌ها و سیستم طراحی (Design System) از صفر: ساخت تمام کامپوننت‌های UI (دکمه‌ها، فرم‌ها، مدال‌ها و ...) به صورت سفارشی.

     • مزایا: کنترل کامل بر روی ظاهر و رفتار کامپوننت‌ها.

     • معایب: بسیار زمان‌بر و پرهزینه. تضمین دسترس‌پذیری (A11y) و سازگاری بین مرورگرها برای هر کامپوننت بسیار دشوار و نیازمند تخصص عمیق است.

  2. استفاده از یک کتابخانه کامپوننت بالغ (Mature Component Library): استفاده از یک کتابخانه معتبر مانند Angular Material یا ng-bootstrap.

     • مزایا: صرفه‌جویی عظیم در زمان توسعه. این کتابخانه‌ها از قبل برای واکنش‌گرایی، دسترس‌پذیری (مطابق با استانداردهای WCAG) و سازگاری با مرورگرها تست شده‌اند. ارائه یک زبان طراحی یکپارچه.

     • معایب: ممکن است سفارشی‌سازی کامل ظاهر برخی کامپوننت‌ها برای تطابق با برندینگ خاص، کمی چالش‌برانگیز باشد.

• تصمیم نهایی (Decision): ما گزینه ۲ (استفاده از Angular Material) را انتخاب می‌کنیم. این کتابخانه به طور رسمی توسط تیم Angular پشتیبانی می‌شود و بهترین یکپارچگی را با فریمورک دارد. این انتخاب به ما اجازه می‌دهد تا به سرعت یک رابط کاربری زیبا، یکپارچه، واکنش‌گرا و دسترس‌پذیر بسازیم و تمرکز تیم توسعه را به جای ساخت کامپوننت‌های پایه، بر روی منطق اصلی برنامه و ویژگی‌های منحصر به فرد VideoVerse معطوف کنیم. ما از سیستم Theming آن برای سفارشی‌سازی رنگ‌ها و فونت‌ها مطابق با برند پروژه استفاده خواهیم کرد.

• پیامدها و بده‌بستان‌ها (Consequences):

  • مثبت: سرعت توسعه به شدت افزایش می‌یابد. استانداردهای Usability و Accessibility به ط��ر پیش‌فرض رعایت می‌شوند. ظاهر برنامه یکپارچه و حرفه‌ای خواهد بود.

  • منفی: ما تا حدی به طراحی Material Design محدود می‌شویم. اگر در آینده نیاز به یک طراحی کاملاً منحصر به فرد داشته باشیم، ممکن است با چالش مواجه شویم.

• اقدامات بعدی (Follow-up Actions):

  • نصب و پیکربندی @angular/material.

  • ایجاد یک ماژول SharedMaterialModule برای import و export کردن کامپوننت‌های مورد نیاز در سراسر برنامه.

  • ایجاد یک فایل theming.scss سفارشی برای تعریف پالت رنگی و تایپوگرافی پروژه.

  • آموزش تیم در مورد بهترین شیوه‌های استفاده از کامپوننت‌های Angular Material برای حفظ دسترس‌پذیری.

ADR-005: پیاده‌سازی تعامل‌پذیری آنی (Interactivity)

• وضعیت: پذیرفته شده

• تاریخ: 2024-05-22

• تصمیم‌گیرندگان: معمار ارشد نرم‌افزار، سرپرست تیم فرانت‌اند

• زمینه و مشکل (Context): برای ایجاد یک تجربه ک��ربری مدرن و جذاب، برخی ویژگی‌ها مانند نمایش نظرات جدید، نوتیفیکیشن‌ها یا تعداد لایک‌ها باید به صورت آنی (Real-time) و بدون نیاز به رفرش صفحه توسط کاربر، به‌روز شوند.

• گزینه‌های بررسی‌شده (Options Considered):

  1. نظرسنجی دوره‌ای (HTTP Polling): فرانت‌اند به صورت دوره‌ای (مثلاً هر ۵ ثانیه) یک درخواست HTTP به سرور ارسال می‌کند تا بررسی کند آیا داده جدیدی وجود دارد یا خیر.

     • مزایا: پیاده‌سازی ساده با استفاده از HttpClient و setInterval یا اپراتورهای RxJS.

     • معایب: ناکارآمد و غیراقتصادی. تولید تعداد زیادی درخواست غیرضروری که باعث افزایش بار روی سرور و مصرف پهنای باند می‌شود. به‌روزرسانی‌ها با تأخیر همراه هستند.

  2. استفاده از WebSockets: ایجاد یک ارتباط دوطرفه و پایدار بین کلاینت و سرور. سرور می‌تواند به محض وقوع یک رویداد، داده‌ها را به کلاینت push کند.

     • مزایا: بسیار کارآمد و سریع. به‌روزرسانی‌ها به صورت کاملاً آنی انجام می‌شوند. کاهش قابل توجه بار سرور در مقایسه با Polling.

     • معایب: پیاده‌سازی اولیه کمی پیچیده‌تر است و نیازمند پشتیبانی در سمت سرور است. مدیریت وضعیت اتصال (قطع و وصل شدن) نیازمند دقت است.

• تصمیم نهایی (Decision): ما گزینه ۲ (WebSockets) را انتخاب می‌کنیم. برای یک پلتفرم تعاملی مانند VideoVerse، این تنها راه‌حل مقیاس‌پذیر و کارآمد است. ما از یک RealtimeService در Angular استفاده خواهیم کرد که ارتباط WebSocket را مدیریت می‌کند. این سرویس از کتابخانه rxjs/webSocket برای تبدیل جریان داده‌های WebSocket به یک Observable استفاده خواهد کرد. این کار به ما اجازه می‌دهد تا با استفاده از قدرت RxJS، به راحتی داده‌های دریافتی را در کامپوننت‌های مختلف مصرف کرده و state برنامه را در NgRx به‌روز کنیم.

• پیامدها و بده‌بستان‌ها (Consequences):

  • مثبت: تجربه کاربری بسیار پویا و جذاب. معماری کارآمد و مقیاس‌پذیر برای ویژگی‌های real-time.

  • منفی: نیازمند هماهنگی دقیق با تیم بک‌اند برای طراحی پروتکل WebSocket. مدیریت چرخه عمر اتصال WebSocket (connection lifecycle) باید به دقت انجام شود.

• اقدامات بعدی (Follow-up Actions):

  • پیاده‌سازی RealtimeService با استفاده از webSocket از RxJS.

  • تعریف یک قرارداد (contract) مشخص برای پیام‌های WebSocket با تیم بک‌اند.

  • ادغام RealtimeService با NgRx Effects برای به‌روزرسانی state بر اساس پیام‌های دریافتی.

  • پیاده‌سازی منطق تلاش مجدد برای اتصال در صورت قطع شدن WebSocket.

ADR-006: تضمین قابلیت پشتیبانی (Supportability)

• وضعیت: پذیرفته شده

• تاریخ: 2024-05-22

• تصمیم‌گیرندگان: معمار ارشد نرم‌افزار، سرپرست تیم فرانت‌اند

• زمینه و مشکل (Context): پس از استقرار برنامه در محیط پروداکشن، تیم پشتیبانی و توسعه باید قادر باشند به سرعت خطاها را شناسایی، ردیابی و رفع کنند. اتکا به گزارش‌های کاربران یا تلاش برای بازتولید خطاها به صورت دستی، ناکارآمد و زمان‌بر است. ما به یک سیستم جامع برای لاگ‌گیری، مانیتورینگ و گزارش خطاهای سمت کلاینت نیاز داریم.

• گزینه‌های بررسی‌شده (Options Considered):

  1. لاگ‌گیری دستی با console.log: استفاده از دستورات console.log/error در کد برای دیباگ کردن.

     • مزایا: ساده‌ترین راه ممکن.

     • معایب: کاملاً ناکافی برای محیط پروداکشن. لاگ‌ها فقط در کنسول مرورگر کاربر قابل مشاهده هستند و هیچ راهی برای جمع‌آوری متمرکز آن‌ها وجود ندارد. اطلاعات زمینه‌ای کافی (مانند نسخه مرورگر، سیستم‌عامل) را ارائه نمی‌دهد.

  2. ادغام با یک سرویس مانیتورینگ و گزارش خطای شخص ثالث: استفاده از سرویس‌هایی مانند Sentry, LogRocket یا Datadog. این سرویس‌ها SDKهایی برای فرانت‌اند ارائه می‌دهند که به طور خودکار خطاها را捕获 کرده و با اطلاعات کامل (stack trace, user context, network requests) به یک داشبورد مرکزی ارسال می‌کنند.

     • مزایا: دید کامل و فوری به خطاهای رخ‌داده در پروداکشن. کاهش چشمگیر زمان لازم برای دیباگ کردن. امکان تنظیم هشدار برای خطاهای جدید یا مکرر.

     • معایب: هزینه اشتراک سرویس. افزودن یک اسکریپت شخص ثالث به برنامه که ممکن است تأثیر جزئی بر عملکرد داشته باشد.

• تصمیم نهایی (Decision): ما گزینه ۲ (ادغام با سرویس Sentry) را انتخاب می‌کنیم. برای یک اپلیکیشن در سطح سازمانی، داشتن یک ابزار قدرتمند برای مانیتورینگ خطاها یک ضرورت است نه یک انتخاب. Sentry به طور خاص برای این منظور طراحی شده و یکپارچه‌سازی آن با Angular بسیار ساده است. ما یک ErrorHandler سفارشی در Angular پیاده‌سازی خواهیم کرد که تمام خطاهای مدیریت‌نشده را رهگیری کرده و به Sentry ارسال می‌کند. همچنین می‌توانیم رویدادها و لاگ‌های مهم را به صورت دستی نیز به Sentry بفرستیم تا زمینه بیشتری برای دیباگ فراهم شود.

• پیامدها و بده‌بستان‌ها (Consequences):

  • مثبت: قابلیت دیباگ و پشتیبانی از برنامه در محیط پروداکشن به شدت بهبود می‌یابد. توانایی شناسایی و رفع مشکلات قبل از اینکه تعداد زیادی از کاربران تحت تأثیر قرار گیرند.

  • منفی: هزینه‌بر بودن سرویس (معمولاً بر اساس تعداد رویدادها). نیاز به مدیریت صحیح اطلاعات ارسالی برای جلوگیری از ارسال داده‌های حساس کاربران (PII).

• اقدامات بعدی (Follow-up Actions):

  • ایجاد حساب کاربری Sentry و دریافت کلید DSN.

  • نصب Sentry SDK برای Angular (@sentry/angular-ivy).

  • پیکربندی Sentry در main.ts و ایجاد یک SentryErrorHandler سفارشی.

  • تنظیم Source Maps در فرآیند build تا stack traceها در Sentry خوانا باشند.

  • آموزش تیم برای استفاده از داشبورد Sentry و تحلیل گزارش‌های خطا.