S/۰۱ · خدمات
معماری سیستم
تصمیم‌هایی که بقیه‌ی چیزها را تعیین می‌کنند.
پیش از نوشتن هر خط کد، مشخص می‌کنیم سیستم چه چیزی را باید نگه دارد، اجزایش چطور با هم حرف می‌زنند و کجا ممکن است بشکند — و دلیل هر تصمیم را مکتوب می‌کنیم تا تیم بعدی به جای معما، یک نقشه تحویل بگیرد.
- تحویلی
- مستندات معماری، مدل داده، ADR
- مناسب برای
- ساخت از صفر، بازنویسی، مشکلات مقیاس
- طراحی‌شده برای
- ده سال، نه یک نسخه
- ۰۱
قرار است چیز بزرگی بسازید و می‌خواهید از همان بار اول درست باشد.
- ۰۲
تغییر دادن سیستم فعلی کند است و کسی دلیلش را نمی‌داند.
- ۰۳
دو تیم مدام کار همدیگر را خراب می‌کنند.
- ۰۴
رشد در راه است و نمی‌دانید اول کجا کم می‌آورد.
- D/۰۱
مدل دامنه و داده
کسب‌وکار را به موجودیت‌ها، روابطشان و قواعدی که همیشه باید برقرار بمانند تبدیل می‌کنیم. این سخت‌ترین بخش سیستم برای تغییر در آینده است، پس اول روی کاغذ درستش می‌کنیم و همین مدل مرجعی می‌ماند که هر صفحه و هر API بر اساسش ساخته می‌شود.
شامل
- مدل موجودیت–رابطه، با همه‌ی فیلدها و معنای هر کدام
- قواعدی که همیشه باید برقرار باشند، به زبان ساده
- چرخه‌ی عمر رکوردهای اصلی: وضعیت‌ها و این‌که چه کسی می‌تواند تغییرشان دهد
- نکات نگهداری و حریم خصوصی برای هر جدول
docs/data-model.dbml - D/۰۲
مرز سرویس‌ها
تصمیم می‌گیریم سیستم از چه اجزایی ساخته شود، هر جزء مالک چه چیزی باشد و اجزا چطور با هم حرف بزنند: فراخوانی API جایی که همین حالا پاسخ لازم است، رویداد جایی که می‌تواند صبر کند. مرزهای روشن به تیم‌ها اجازه می‌دهد موازی کار کنند بی‌آن‌که کار همدیگر را خراب کنند.
شامل
- نقشه‌ی زمینه: همه‌ی سرویس‌ها و داده‌ای که هر کدام مالکش است
- قرارداد API میان سرویس‌ها، با OpenAPI یا gRPC
- رویدادها و صف‌ها، با این‌که چه کسی منتشر می‌کند و چه کسی گوش می‌دهد
- آنچه هرگز نباید مستقیم به اشتراک گذاشته شود، و چرا
docs/architecture/containers.mmd - D/۰۳
ثبت تصمیم‌ها
هر انتخاب مهم به شکل یک سند تصمیم معماری نوشته می‌شود: مسئله، گزینه‌هایی که بررسی کردیم، هزینه‌ی هر کدام و این‌که چرا همین را انتخاب کردیم. وقتی سه سال بعد کسی بپرسد «چرا این‌طوری است؟»، جوابش در مخزن کد است.
شامل
- یک سند برای هر تصمیم، شماره‌دار و تاریخ‌دار
- گزینه‌ها با بده‌بستان‌های صادقانه، نه فقط گزینه‌ی برنده
- پیامدها: چه چیزی را آسان و چه چیزی را سخت می‌کند
- وضعیت به‌روز، وقتی تصمیمی بازنگری می‌شود
docs/adr/0007-bookings-in-postgres.md ADR-0007 · نگهداری رزروها در PostgreSQL
پذیرفته‌شده · ۲۲ اسفند
زمینه
- رزروها به سازگاری کامل نیاز دارند: هیچ نوبتی نباید دو بار فروخته شود.
- بار پیش‌بینی‌شده: ۴۰ نوشتن در ثانیه در اوج.
گزینه‌ها
- PostgreSQL با قفل سطری: ساده و آزموده.
- ذخیره‌ساز رویدادمحور: انعطاف‌پذیر، اما با هزینه‌ی نگهداری بیشتر.
تصمیم
- PostgreSQL، با ایندکس یکتا روی (clinic_id, slot_at).
پیامدها
- + یک پایگاه داده برای پشتیبان‌گیری و فکر کردن.
- − گزارش‌ها از نسخه‌ی تکراری خوانده می‌شوند، چند ثانیه عقب‌تر.
- D/۰۴
نمودارهایی که درست می‌مانند
سیستم را در سطح‌هایی رسم می‌کنیم که آدم‌ها واقعاً لازم دارند: دنیایی که در آن زندگی می‌کند، کانتینرهایی که از آن‌ها ساخته شده و کامپوننت‌های درون بخش‌های مهم. نمودارها به شکل متن در مخزن کد هستند، پس در همان تغییری که کد عوض می‌شود بازبینی و به‌روز می‌شوند.
شامل
- نماهای زمینه، کانتینر و کامپوننت به سبک C4
- نمودار به شکل کد، نسخه‌بندی‌شده همراه مخزن
- نمودار توالی برای جریان‌های مهم
- یک مرور یک‌صفحه‌ای برای هر کسی که تازه به سیستم می‌رسد
repository - docs/
- overview.mdاز اینجا شروع کنید
- architecture/
- context.mmdC4 · زمینه
- containers.mmdC4 · کانتینرها
- booking-flow.mmdتوالی
- adr/
- 0001-record-decisions.mdپذیرفته‌شده
- 0007-bookings-in-postgres.mdپذیرفته‌شده
- data-model.dbmlمدل داده
- runbook.mdعملیات
- D/۰۵
بررسی ریسک و مقیاس
پیش از آن‌که محیط واقعی پیدایش کند، دنبال جایی می‌گردیم که طراحی در آن می‌شکند: نقطه‌های شکست تکی، گلوگاه‌های زیر بار، داده‌ای که بی‌حد رشد می‌کند، رخنه‌های امنیتی. هر ریسک یک شدت و یک راه حل می‌گیرد تا تصمیم بگیرید چه چیزی را همین حالا درست کنید و چه چیزی را زیر نظر بگیرید.
شامل
- حالت‌های شکست و این‌که هر کدام تا کجا اثر می‌گذارد
- برآورد بار و این‌که اولین گلوگاه کجا خواهد بود
- بررسی امنیتی جریان داده و دسترسی‌ها
- فهرست شاخص‌هایی که زودتر از همه هشدار می‌دهند
docs/risk-register.md - یک پایگاه داده‌ی تنها، نقطه‌ی شکست تکی استبالا
- جست‌وجوی نوبت با اضافه شدن کلینیک‌ها کند می‌شودمتوسط
- صف اعلان‌ها صف پیام‌های ناموفق نداردمتوسط
- وب‌هوک‌های پرداخت را می‌توان با خیال راحت تکرار کردانجام‌شده
- داده‌ی شخصی در ذخیره و در پشتیبان رمزنگاری شده استانجام‌شده
- D/۰۶
نقشه‌ی راه قابل ساخت
طراحی به مرحله‌هایی تقسیم می‌شود، به ترتیبی که ساختنش منطقی است. هر مرحله چیزی تحویل می‌دهد که از اول تا آخر کار می‌کند، پس پیشرفت را زود می‌بینید و می‌توانید بی‌آن‌که کاری دور ریخته شود مسیر را عوض کنید.
شامل
- مرحله‌ها، هر کدام با یک نتیجه‌ی کارا
- وابستگی‌ها، و آنچه می‌شود موازی ساخت
- بازه‌ی زمان و هزینه، با عدم قطعیتی که صادقانه نشان داده می‌شود
- آنچه بعداً ساخته شود، و آنچه اصلاً ساخته نشود
docs/roadmap.md هفته‌ی ۱ تا ۳
هسته‌ی رزرو
→ رزرو، لغو و جابه‌جایی نوبت
هفته‌ی ۴ تا ۶
پرداخت
→ پرداخت آنلاین و بازگشت وجه
هفته‌ی ۷ و ۸
اعلان‌ها
→ یادآوری با پیامک و ایمیل
هفته‌ی ۹ تا ۱۱
داشبورد کلینیک
→ برنامه‌ها و گزارش‌ها
- ۰۱
شنیدن
کاربران، محدودیت‌ها، بودجه و سیستم قدیمی‌ای که کسی جرئت دست زدن به آن را ندارد. آن‌قدر می‌پرسیم تا مسئله روشن شود.
- ۰۲
مدل‌سازی
اول دامنه و داده را مدل می‌کنیم؛ بیشتر خطاهای معماری از همین‌جا شروع می‌شوند.
- ۰۳
تصمیم
گزینه‌ها با بده‌بستان‌های صادقانه، مکتوب به شکل سندهای تصمیم که می‌توانید به چالش بکشید.
- ۰۴
تحویل
مستندات، نمودارها و نقشه‌ی راهی که تیم شما — یا ما — بتواند بر اساسش بسازد.
یک پروژه‌ی معماری معمولاً بسته به اندازه‌ی سیستم چهار تا شش هفته طول می‌کشد. شما در تمام مسیر همراه هستید: هیچ چیز پشت درهای بسته طراحی نمی‌شود و هر تصمیمی را پیش از گرفته شدن، با استدلالش دیده‌اید.
- هفته‌ی ۱
جلسه‌های کاری با تیم شما: کاربران، هدف‌ها، محدودیت‌ها و سیستم‌هایی که الان وجود دارند.
- هفته‌ی ۲
پیش‌نویس مدل دامنه و داده، بازبینی‌شده با کسانی که کسب‌وکار را بهتر از همه می‌شناسند.
- هفته‌ی ۳ و ۴
مرز سرویس‌ها، یکپارچه‌سازی‌ها و تصمیم‌های کلیدی، هر کدام مکتوب در یک سند تصمیم.
- هفته‌ی ۵
بررسی ریسک و مقیاس، و بعد نقشه‌ی راه، تقسیم‌شده به مرحله‌ها.
- هفته‌ی ۶
تحویل: همه‌چیز را با تیمتان مرور می‌کنیم و به سؤال‌های سخت جواب می‌دهیم.
سند معماری
یک سند که سیستم را توضیح می‌دهد: اجزا، داده و استدلال پشت هر کدام.
سندهای تصمیم
هر انتخاب و بده‌بستان‌هایش، در مخزن کد شما و به زبان ساده.
نمودار به شکل کد
نمودارهایی که تیمتان کنار کد ویرایش می‌کند، پس هیچ‌وقت کهنه نمی‌شوند.
مدل داده
مدل کامل، با معنای هر فیلد، قواعد و چرخه‌ی عمرش.
نقشه‌ی راه
مرحله‌ها و برآوردهایی که تیم شما، یا هر تیمی، می‌تواند بر اساسش بسازد.
یک بازبینی پس از شروع ساخت
بررسی این‌که طراحی در عمل چطور جواب می‌دهد و چه چیزی باید تنظیم شود.
- C4 model
- ADRs
- Event storming
- PostgreSQL
- OpenAPI
- gRPC
- NATS / Kafka
- Threat modelling
اگر برنامه‌نویس داریم، باز هم به این نیاز داریم؟
معمولاً حتی بیشتر. برنامه‌نویس خوب در هر جهتی که نشانش بدهید سریع پیش می‌رود؛ معماری مطمئن می‌شود آن جهت درست است.
می‌توانید سیستم فعلی ما را بررسی کنید؟
بله. آنچه واقعاً وجود دارد را نقشه‌برداری و مستند می‌کنیم و مسیری پیشنهاد می‌دهیم که با بازنویسی شروع نمی‌شود.
چقدر طول می‌کشد؟
برای بیشتر سیستم‌ها چهار تا شش هفته. بررسی متمرکز یک سیستم موجود می‌تواند دو هفته طول بکشد.
از ما چه چیزی لازم دارید؟
چند ساعت در هفته از وقت کسانی که کسب‌وکار و سیستم‌های فعلی را می‌شناسند، و دسترسی به هر آنچه امروز وجود دارد.
ساختش را هم انجام می‌دهید؟
اگر بخواهید، بله. معماری در هر صورت روی پای خودش می‌ایستد — هدف از مکتوب کردنش همین است.
بگویید چه چیزی می‌سازید.
هر پروژه با یک جلسه‌ی مشاوره شروع می‌شود: شما ایده و هر آنچه می‌دانید را می‌آورید، ما آن را به طرحی تبدیل می‌کنیم که بشود رویش ساخت.
رزرو مشاوره