MasirYar — پلتفرم هوشمند رشد شخصی

یک اکوسیستم میکروسرویس Production-Ready، طراحی شده برای مقیاس‌پذیری، هوشمندی و یک تجربه توسعه بی‌نظیر.

اصول معماری • پشته فناوری • راه‌اندازی • عملیات و DevOps • تست

---

Note

هدف این مخزن: ارائه یک Blueprint کامل و عملی برای ساخت سیستم‌های توزیع‌شده مدرن. این پروژه نه تنها یک محصول کارا، بلکه یک "فول کورس" مهندسی نرم‌افزار است که از طراحی اولیه تا استقرار، مانیتورینگ و عملیات روزمره (Day-2 Operations) را پوشش می‌دهد.

---

🏛️ اصول معماری

این پلتفرم بر پایه مجموعه‌ای از اصول مهندسی برای دستیابی به حداکثر مقیاس‌پذیری، پایداری و قابلیت نگهداری بنا شده است.

• معماری میکروسرویس: جداسازی کامل دامنه‌های کسب‌وکار (Identity, Coaching, Notifications) برای توسعه موازی، استقرار مستقل و مقیاس‌پذیری تفکیک شده هر سرویس.
• طراحی دامنه محور (DDD): کپسوله کردن منطق پیچیده کسب‌وکار در مدل‌های غنی دامنه (Rich Domain Models) و استفاده از زبان مشترک (Ubiquitous Language) در سراسر سیستم.
• معماری تمیز (Clean Architecture): جداسازی لایه‌ها و رعایت قانون وابستگی به سمت مرکز، که منجر به کدی تست‌پذیر، مستقل از فریم‌ورک و قابل نگهداری می‌شود.
• ارتباطات رویداد-محور (Event-Driven): استفاده از RabbitMQ و الگوی Outbox برای ارتباطات غیرهمزمان، که پایداری سیستم در برابر خطای موقت سرویس‌ها را تضمین می‌کند (Resilience).
• زیرساخت به عنوان کد (IaC): تعریف کل اکوسیستم در Docker Compose برای راه‌اندازی ۱۰۰٪ تکرارپذیر و آمادگی کامل برای انتقال به مانیفست‌های Kubernetes.
• مشاهده‌پذیری (Observability): پشته Loki & Grafana برای جمع‌آوری و تحلیل متمرکز لاگ‌ها، که برای درک رفتار سیستم‌های توزیع‌شده حیاتی است.

---

💻 پشته فناوری (Tech Stack)

حوزه	فناوری / ابزار	نقش استراتژیک
هسته سرویس‌ها	.NET 9, ASP.NET Core	ارائه عملکرد بالا و اکوسیستم بالغ برای میکروسرویس‌های قوی.
رابط کاربری	Next.js 14, React, TypeScript	ساخت واسط‌های کاربری سریع (SSR) با تجربه توسعه مدرن (DX).
پایداری داده	PostgreSQL 16 (pgvector, JSONB)	پایگاه داده رابطه‌ای و بُرداری یکپارچه برای داده‌های تراکنشی و جستجوی معنایی.
ارتباطات غیرهمزمان	RabbitMQ	پیاده‌سازی الگوی Publish/Subscribe برای ارتباطات پایدار و غیرهمزمان.
پردازش پس‌زمینه	Hangfire	اجرای کارهای زمان‌بر (مانند تحلیل AI) و زمان‌بندی شده.
ارکستراسیون	Docker Compose (محلی), Kubernetes (پروداکشن)	مدیریت چرخه حیات کانتینرها در محیط‌های مختلف.
نقطه ورود API	YARP	یک Reverse Proxy سبک و پرقدرت برای مدیریت متمرکز ترافیک و امنیت.
مشاهده‌پذیری	Loki, Grafana	پشته استاندارد صنعتی برای جمع‌آوری و بصری‌سازی لاگ‌ها.
عملیات (Ops)	Python, Shell Scripting	خودکارسازی وظایف DevOps مانند بکاپ‌گیری، بازیابی و مدیریت سیستم.

---

🚀 راه اندازی با یک دستور (Single-Command Setup)

کل پلتفرم با یک اسکریپت راه‌انداز هوشمند و بدون نیاز به نصب هیچ ابزاری به جز Docker Desktop راه‌اندازی می‌شود.

Important

این اسکریپت به صورت تعاملی شما را برای ایجاد فایل پیکربندی (.env) راهنمایی کرده و تمام سرویس‌ها را به صورت خودکار راه‌اندازی می‌کند.

# 1. Clone the repository
git clone https://github.com/Opselon/MasirYar.git
cd MasirYar

# 2. Run the launcher
#    (On the first run, it will guide you through the setup wizard)
./run.sh up

برای کاربران ویندوز، از run.ps1 در PowerShell استفاده کنید.

اکوسیستم در دسترس پس از راه‌اندازی:

سرویس	آدرس محلی	توضیحات
Frontend Application	http://localhost:3000	رابط کاربری اصلی پلتفرم.
API Gateway	http://localhost:8000	نقطه ورود واحد برای تمام درخواست‌های API.
Grafana Dashboard	http://localhost:3001	داشبورد متمرکز لاگ‌ها (user: admin, pass: admin).
RabbitMQ Management	http://localhost:15672	داشبورد مدیریت RabbitMQ (user: guest, pass: guest).
Identity Service API	http://localhost:5001/swagger	مستندات API سرویس هویت.

Tip

برای مشاهده لیست کامل دستورات مدیریتی (مانند down, logs, prune), اسکریپت را بدون پارامتر اجرا کنید: ./run.sh

---

⚙️ عملیات و DevOps (Operations & DevOps)

پلتفرم MasirYar با ذهنیت عملیات روز دوم (Day-2 Operations) طراحی شده است.

• بکاپ و بازیابی خودکار:

  • یک سرویس بکاپ اختصاصی (ops/backup) با استفاده از Python و docker-compose-backup.yml پیاده‌سازی شده است.
  • این سرویس به صورت زمان‌بندی شده (Cron Job) از دیتابیس PostgreSQL بکاپ کامل (Logical Dump) گرفته و آن را ذخیره می‌کند.
  • اسکریپت‌های restore.sh برای بازیابی سریع از آخرین بکاپ در مواقع بحرانی فراهم شده است.

• آمادگی برای Kubernetes:

  • تمام سرویس‌ها برای اجرا در یک محیط ارکستراسیون شده مانند Kubernetes آماده شده‌اند.
  • مانیفست‌های اولیه K8s (شامل Deployments, Services, Ingress) در نقشه راه پروژه قرار دارند و ساختار فعلی، مهاجرت به K8s را تسهیل می‌کند.

• پایپ‌لاین CI/CD:

  • یک پایپ‌لاین کامل در .github/workflows پیاده‌سازی شده که به صورت خودکار:
    1. کد را Build می‌کند.
    2. تمام تست‌ها (Unit, Integration, E2E) را اجرا می‌کند.
    3. ایمیج‌های داکر را ساخته و به یک Container Registry پوش می‌کند.

---

📁 ساختار پروژه

/
├── .github/              # پایپ‌لاین‌های CI/CD با GitHub Actions
├── docker/               # فایل‌های Docker Compose اصلی و پیکربندی زیرساخت
├── docs/                 # مستندات معماری و طراحی
├── ops/                  # ابزارها و سرویس‌های عملیاتی (مانند بکاپ)
├── protos/               # قراردادهای gRPC برای ارتباطات داخلی
├── src/                  # سورس کد تمام میکروسرویس‌ها و برنامه‌ها
│   ├── ApiGateway/
│   ├── CoachingService/
│   ├── IdentityService/
│   ├── NotificationService/
│   └── frontend-web/
└── kubernetes/           # (نقشه راه) مانیفست‌های استقرار در Kubernetes

---

✅ استراتژی تست (Quality Assurance)

کیفیت کد از طریق یک هرم تست خودکار که در پایپ‌لاین CI ادغام شده است، تضمین می‌شود.

• تست‌های واحد (Unit Tests): تست منطق خالص کسب‌وکار در لایه‌های Core و Application با دیتابیس در حافظه.
• تست‌های یکپارچه‌سازی (Integration Tests): تست جریان کامل یک میکروسرویس و ارتباطات بین سرویس‌ها (از طریق RabbitMQ) با استفاده از Testcontainers. این رویکرد حداکثر اطمینان را با حفظ ایزوله‌سازی فراهم می‌کند.
• تست‌های End-to-End (E2E): تست جریان‌های کاربری کامل از طریق UI با استفاده از Playwright.

Warning

هیچ Pull Request ای بدون گذراندن موفقیت‌آمیز تمام تست‌های CI، ادغام (Merge) نخواهد شد.

---

🤝 مشارکت (Contributing)

مشارکت شما باعث افتخار ماست. لطفاً قبل از شروع کار، فایل CONTRIBUTING.md را مطالعه کرده و فرآیند ما برای ارسال Issues و Pull Requests را دنبال کنید.

---

Engineered for Scale, Performance, and Insight.