{
  "title": "معماری هسته اصلی",
  "slug": "team/platform/core/Architecture",
  "url": "/docs/team/platform/core/Architecture",
  "frontmatter": {
    "layout": "doc",
    "title": "معماری هسته اصلی",
    "description": "معماری، ساختار ماژول‌ها، روابط و قوانین فنی سرویس Core به عنوان کنترل‌کننده پلتفرم",
    "version": "1.0.0",
    "status": "PUBLIC",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-11",
    "updated_at": "2026-06-13",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "معماری هسته اصلی",
      "content": "**Core Architecture**\n\n> **خلاصه:** این سند ساختار معماری، وظایف ماژول‌ها، وابستگی‌ها و قوانین فنی سرویس Core رو توضیح می‌ده.\n\n---"
    },
    {
      "level": 2,
      "heading": "ارجاعات مرتبط",
      "content": "**Related Documents**\n\n- [بلوپرینت هسته اصلی](./blueprint)\n- [تصمیم معماری ۱: انتخاب Go](./ADR/ADR-Core-001)\n- [تصمیم معماری ۲: Core به عنوان Platform Control Plane](./ADR/ADR-Core-002)\n\n---"
    },
    {
      "level": 2,
      "heading": "فهرست محتوا",
      "content": "**Table of Contents**\n\n1. [هدف](#هدف)\n2. [جایگاه در معماری](#جایگاه-در-معماری)\n3. [ساختار پیشنهادی](#ساختار-پیشنهادی)\n4. [معرفی ماژول‌ها](#معرفی-ماژول‌ها)\n5. [قابلیت مشاهده‌پذیری](#قابلیت-مشاهده‌پذیری)\n6. [ذخیره‌سازی و ارتباطات](#ذخیره‌سازی-و-ارتباطات)\n7. [قوانین وابستگی‌ها](#قوانین-وابستگی‌ها)\n8. [قوانین معماری و معیار موفقیت](#قوانین-معماری-و-معیار-موفقیت)\n\n---"
    },
    {
      "level": 2,
      "heading": "هدف",
      "content": "**Objective**\n\nسرویس Core یه سرویس زیرساختی هستش که سلامت کل اکوسیستم سرویس‌ها، ثبت وقایع و اعتبارسنجی فنی رویدادها رو مدیریت می‌کنه. یادت باشه که Core هیچ وقت تصمیم‌گیرنده کسب‌وکار (بیزنس) نیست.\n\n---"
    },
    {
      "level": 2,
      "heading": "جایگاه در معماری",
      "content": "**Position in Architecture**\n\n```text\nFrontend\n    │\n    ▼\nAPI Gateway\n    │\n    ▼\nBusiness Services\n    │\n    ▼\nNATS\n    │\n    ▼\nCore\n```\n\n> [!IMPORTANT]\n> سرویس Core اصلاً در مسیر مستقیم درخواست‌های کاربرا قرار نداره و هیچ درخواست HTTP از سمت کاربرا مستقیماً به سمت Core فرستاده نمی‌شه.\n\n---"
    },
    {
      "level": 2,
      "heading": "ساختار پیشنهادی",
      "content": "**Proposed Structure**\n\nساختار دایرکتوری‌های پروژه Core به شکل زیر پیشنهاد می‌شه:\n\n```text\ncore/\n├── cmd/\n│   └── main.go\n├── internal/\n│   ├── audit/\n│   ├── registry/\n│   ├── validation/\n│   ├── health/\n│   ├── lifecycle/\n│   ├── eventrouter/\n│   ├── storage/\n│   ├── telemetry/\n│   └── shared/\n├── configs/\n├── migrations/\n├── go.mod\n└── Dockerfile\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "معرفی ماژول‌ها",
      "content": "**Modules Overview**"
    },
    {
      "level": 3,
      "heading": "ماژول Audit",
      "content": "**Audit Module**\n\nوظایف و اهداف این ماژول عبارتند از:\n\n- ثبت غیرقابل تغییر رویدادهای سیستم\n- نگهداری تاریخچه کامل پلتفرم\n- رهگیری رخدادها (Tracking / Traceability)\n- بررسی و بازبینی رویدادها (Event Review)\n- تحلیل وقایع و رفتار سیستم (Analysis)\n- انطباق با قوانین و استانداردهای پلتفرم (Compliance)\n\n**خروجی:**\n\n- جدول `audit_logs` در دیتابیس."
    },
    {
      "level": 3,
      "heading": "ماژول Validation",
      "content": "**Validation Module**\n\nوظایف این ماژول شامل موارد زیر می‌شه:\n\n- اعتبارسنجی Envelope رویدادها مطابق فایل [envelope.proto](file:///C:/Users/ASUS/Documents/GitHub/nons/nons-api/contracts/envelope.proto)\n- اعتبارسنجی فراداده‌های فنی (Metadata)\n\nفیلدهای فنی اجباری که باید اعتبارسنجی بشن (تعریف‌شده در `envelope.proto`):\n\n- `id`\n- `subject`\n- `version`\n- `timestamp`\n- `source`\n- `trace_id`\n\n> [!TIP]\n> سرویس Core از بایندینگ‌های Go که از روی فایل‌های Proto تولید شدن واسه اعتبارسنجی استفاده می‌کنه و نیازی نیست این ساختارها رو به صورت دستی تعریف کنیم.\n\n> [!CAUTION]\n> اعتبارسنجی ساختار داده‌های دامنه‌ای و تجاری (Business Payload Validation) در سطح سرویس Core اکیداً ممنوع هستش."
    },
    {
      "level": 3,
      "heading": "ماژول Registry",
      "content": "**Registry Module**\n\nوظایف اصلی:\n\n- ثبت سرویس‌ها\n- ثبت نسخه (Version) سرویس‌ها\n- ثبت آخرین Heartbeat دریافتی از اون‌ها\n\nنمونه سرویس‌هایی که توی این رجیستری ثبت می‌شن:\n\n- `auth-service`\n- `marketplace-service`\n- `wallet-service`\n- `payment-service`"
    },
    {
      "level": 3,
      "heading": "ماژول Health",
      "content": "**Health Module**\n\nوظایف این ماژول به شرح زیر هستش:\n\n- تعیین وضعیت سلامت سرویس‌ها بر اساس دریافت Heartbeat در بازه زمانی مجاز\n- تشخیص از دسترس خارج شدن (Down) سرویس‌ها\n\nوضعیت‌های سلامت معتبر (Valid States):\n\n- **UP**: دریافت موفق Heartbeat در بازه زمانی مجاز.\n- **DEGRADED**: مشاهده تاخیر غیرعادی در ارسال Heartbeat.\n- **DOWN**: عدم دریافت Heartbeat پس از گذشت مهلت معین."
    },
    {
      "level": 4,
      "heading": "پایش وضعیت و نقاط توسعه",
      "content": "**Health Monitoring & Extension Point**\n\n- **نگهداری وضعیت سلامت:** Core صرفاً وضعیت سلامت سرویس‌ها رو نگهداری می‌کنه.\n- **محدوده MVP:** سرویس Core در نسخه MVP هیچ‌گونه مسئولیت عملیاتی مثل ارسال هشدار (Alerting) یا اتوماسیون جریان‌های کاری (Workflow Automation) در زمان تغییر وضعیت‌ها نداره.\n- **رویدادهای آتی:** رویداد `platform.service.status_changed` به عنوان یه نقطه توسعه (Extension Point) برای انتشار وضعیت‌های جدید رزرو شده تا در فازهای بعدی بدون تغییر در هسته اصلی، توسط سیستم‌های بیرونی مصرف بشه."
    },
    {
      "level": 3,
      "heading": "ماژول Platform Governance",
      "content": "**Platform Governance**\n\nوظیفه این ماژول کنترل و اطمینان از انطباق فنی سرویس‌ها با استانداردهای کلان پلتفرم هست.\n\nقراردادهای فنی هدف جهت اعمال حاکمیت:\n\n- **Event Contract**: فرمت و ساختار پیام‌ها در رویدادها (تعریف‌شده در `envelope.proto`).\n- **Logging Contract**: انطباق با قالب لاگ‌های سیستم (تعریف‌شده در `packages/logging`).\n- **Metadata Contract**: انطباق اطلاعات هدر و فراداده‌های پلتفرم (تعریف‌شده در Proto)."
    },
    {
      "level": 3,
      "heading": "ماژول Event Router",
      "content": "**Event Router Module**\n\nوظایف اصلی:\n\n- دریافت رویدادها از NATS\n- ارسال به بخش Audit\n- ارسال به بخش Validator\n\n> [!IMPORTANT]\n> این ماژول نقش Orchestrator یا هماهنگ‌کننده رو نداره و صرفاً هدایت‌کننده فنی پیام‌هاست.\n\n---"
    },
    {
      "level": 2,
      "heading": "قابلیت مشاهده‌پذیری",
      "content": "**Observability**\n\nسرویس Core باید اطلاعات زیر رو جهت مانیتورینگ منتشر کنه:"
    },
    {
      "level": 3,
      "heading": "متریک‌ها",
      "content": "**Metrics**\n\n| متریک                       | توضیح                         |\n| :-------------------------- | :---------------------------- |\n| `received_events_total`     | تعداد کل رویدادهای دریافت‌شده |\n| `validated_events_total`    | تعداد رویدادهای معتبر         |\n| `invalid_events_total`      | تعداد رویدادهای نامعتبر       |\n| `audit_writes_total`        | تعداد دفعات ثبت در بخش Audit  |\n| `registered_services_total` | تعداد کل سرویس‌های ثبت‌شده    |\n| `service_health_status`     | وضعیت سلامت لحظه‌ای سرویس‌ها  |"
    },
    {
      "level": 3,
      "heading": "ردیابی",
      "content": "**Tracing**\n\nردیابی توزیع‌شده (Distributed Tracing) باید برای این موارد فعال باشه:\n\n- Event Processing\n- Validation\n- Audit Persistence"
    },
    {
      "level": 3,
      "heading": "لاگ‌نویسی",
      "content": "**Logging**\n\n- تمام لاگ‌ها باید به صورت Structured JSON Logs باشن.\n\n---"
    },
    {
      "level": 2,
      "heading": "ذخیره‌سازی و ارتباطات",
      "content": "**Storage & Communications**\n\nسرویس Core برای ذخیره‌سازی داده‌ها از **PostgreSQL** استفاده می‌کنه.\n\nجداول اصلی دیتابیس:\n\n- `services`: اطلاعات و متادیتای سرویس‌ها.\n- `heartbeats`: تاریخچه ضربان‌های سلامت.\n- `audit_logs`: لاگ‌های غیرقابل تغییر سیستم.\n\nنحوه تعامل با بقیه بخش‌ها:\n\n- Core ↔ NATS\n- Core ↔ PostgreSQL\n- Core ↔ OpenTelemetry\n- Core ↔ Prometheus\n\n---"
    },
    {
      "level": 2,
      "heading": "قوانین وابستگی‌ها",
      "content": "**Dependency Rules**\n\nسرویس Core به عنوان Platform Control Plane قوانین سخت‌گیرانه‌ای برای وابستگی‌ها داره:\n\n- **وابستگی‌های مجاز:**\n  - NATS (ارتباطات پیام‌رسان)\n  - PostgreSQL (ذخیره داده‌ها)\n  - OpenTelemetry (ردیابی توزیع‌شده)\n  - Prometheus (جمع‌آوری متریک‌ها)\n\n- **وابستگی‌های ممنوع:**\n  - `nons-api/packages/*` (همه پکیج‌های TypeScript - چون Core با Go نوشته می‌شه نباید به اکوسیستم JS/TS وابسته باشه)\n  - `nons-api/services/*` (کدهای اختصاصی هر کدوم از سرویس‌های تجاری)\n  - هرگونه دایرکتوری مربوط به `domain/` یا `business/` خارج از پکیج‌های پایه و فنی\n\n- **تغییرات پس از ADR-Platform-001:**\n  - Core مجازه از Bindingهای Go تولیدشده از Proto (`nons-api/contracts/`) استفاده کنه. این کدها در CI تولید می‌شن و وابستگی به پکیج‌های TS ندارن.\n\n---"
    },
    {
      "level": 2,
      "heading": "قوانین معماری و معیار موفقیت",
      "content": "**Architectural Rules & Success Criteria**"
    },
    {
      "level": 3,
      "heading": "قوانین معماری",
      "content": "**Architectural Rules**\n\n1. Core هیچ Event اختصاصی دامنه‌ای (مثل سفارش یا پرداخت) تعریف نمی‌کنه.\n2. Core هیچ گردش کاری (Workflow) یا فرآیندی رو اجرا نمی‌کنه.\n3. Core هیچ ماشین حالتی (State Machine) رو نگه نمی‌داره.\n4. Core هیچ تصمیم کسب‌وکاری یا منطقی مربوط به محصول رو اعمال نمی‌کنه.\n5. اضافه شدن سرویس جدید نباید نیازمند تغییر در کدهای Core باشه.\n6. اضافه شدن رویداد جدید نباید تغییری در Core ایجاد کنه.\n7. تغییر فناوری یا زبان سرویس‌های دیگر نباید تأثیری روی Core بذاره."
    },
    {
      "level": 3,
      "heading": "معیار موفقیت",
      "content": "**Success Criteria**\n\nاگه توی آینده هر کدوم از اتفاقات زیر بیفته و سرویس Core بدون هیچ تغییری و بدون مشکل به کار خودش ادامه بده، یعنی معماری اون موفقیت‌آمیز بوده:\n\n- حذف شدن یا تغییر منطق `order-service`\n- بازنویسی کامل `wallet-service`\n- تغییر زبان یا فریمورک `payment-service`\n\n> **اصل نهایی:**  \n> Core مالک زیرساخته، نه مالک دامنه کسب‌وکار!"
    }
  ]
}