{
  "title": "ساختار مخزن",
  "slug": "team/platform/standards/repository-structure",
  "url": "/docs/team/platform/standards/repository-structure",
  "frontmatter": {
    "layout": "doc",
    "title": "ساختار مخزن",
    "description": "ساختار استاندارد نونز (nons-api) — Monorepo بک‌اند، قراردادها، و سرویس‌ها",
    "version": "1.0.0",
    "status": "PRIVATE",
    "author": "xoxxel",
    "owner": "xoxxel",
    "created_at": "2026-06-07",
    "updated_at": "2026-06-13",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "ساختار مخزن",
      "content": "**Repository Structure**\n\nنسخه 1.0 | الزامی برای همه سرویس‌ها\n\n---"
    },
    {
      "level": 2,
      "heading": "ساختار استاندارد هر سرویس",
      "content": "هر سرویس درون `services/{service-name}/` باید از این ساختار پیروی کند:\n\n```\nservices/{service-name}/\n│\n├── src/                      # تمام کدهای منبع\n│   └── {feature}/            # یک پوشه به ازای هر ویژگی/ماژول\n│\n├── tests/\n│   ├── unit/                 # منطق خالص، بدون I/O\n│   └── integration/          # دیتابیس واقعی، NATS واقعی\n│\n├── docs/\n│   ├── README.md             # اجباری — راه‌اندازی، متغیرها، API\n│   ├── openapi.yaml          # **خودکار (Generated)** — توسط ابزار سرویس تولید می‌شود (مطابق [OpenAPI Guidelines](../api/openapi-guidelines)) — ویرایش مستقیم ممنوع\n│   ├── events.md             # رویدادهای منتشر شده و مصرف شده\n│   ├── database.md           # طرح دیتابیس، نکات مهاجرت\n│   └── adr/                  # سوابق تصمیمات معماری\n│       └── 001-why-mongodb.md\n│\n├── demo/\n│   ├── index.html            # صفحه اصلی دمو\n│   └── assets/               # منابع استاتیک (CSS, JS, assets)\n│\n├── blueprint/                # فقط قبل از توسعه — پس از تکمیل حذف یا بایگانی می‌شود\n│   ├── blueprint.md          # هدف، مسئولیت‌ها، API اولیه\n│   ├── requirements.md       # نیازمندی‌های دقیق\n│   └── scenarios.md          # سناریوهای اصلی و خطا\n│\n├── CHANGELOG.md              # اجباری — ثبت همه تغییرات\n├── Dockerfile                # اجباری — بیلد کانتینر\n├── .env.example              # همه متغیرهای محیط با placeholder\n├── .env.test                 # مقادیر امن برای محیط تست\n├── .dockerignore             # جلوگیری از ورود فایل‌های اضافه به تصویر\n├── .gitignore\n└── package.json / go.mod / pyproject.toml\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "توضیح پوشه‌ها",
      "content": ""
    },
    {
      "level": 3,
      "heading": "`src/` — کد منبع",
      "content": "- تمام کدهای اصلی سرویس اینجا قرار می‌گیرد\n- هر ماژول یا ویژگی یک پوشه مجزا دارد\n- هیچ فایل تستی در `src/` قرار نمی‌گیرد"
    },
    {
      "level": 3,
      "heading": "`tests/` — تست‌ها",
      "content": "- **واحد (unit):** منطق خالص کسب‌وکار، بدون وابستگی به I/O\n- **یکپارچه (integration):** دیتابیس واقعی، NATS واقعی، بدون mock\n- نام فایل تست: `{module}.test.{ext}` یا `{module}.spec.{ext}`"
    },
    {
      "level": 3,
      "heading": "`docs/` — مستندات سرویس",
      "content": "- هر سرویس مستندات خود را داخل پوشه `docs/` خود نگهداری می‌کند\n- شامل: README، API اسنادات (OpenAPI)، رویدادها، طرح دیتابیس، ADRها\n- هیچ مستند سرویسی خارج از دایرکتوری سرویس زندگی نمی‌کند\n- **مستندات پلتفرم و معماری عمومی:** درون `dotdive/docs/` (پروژه جداگانه)\n- **رجیستری محلی کلاینت:** درون `.nons/services/` در پروژه فرانت‌اند (تولیدشده توسط `nons service add`)\n- **مصنوعات تولیدشده (Types, API Client, Hooks):** درون `.nons/generated/` در پروژه فرانت‌اند (تولیدشده توسط `nons generate`)"
    },
    {
      "level": 3,
      "heading": "`demo/` — پیش‌نمایش",
      "content": "- یک پیش‌نمایش HTML/CSS از عملکرد سرویس\n- فقط HTML و CSS ساده — بدون فریم‌ورک، بدون Build Step\n- باید مستقیماً در مرورگر باز شود"
    },
    {
      "level": 3,
      "heading": "`blueprint/` — طرح اولیه",
      "content": "- فقط قبل از شروع توسعه وجود دارد\n- پس از اتمام توسعه، محتوای آن به `docs/` منتقل یا بایگانی می‌شود\n\n---"
    },
    {
      "level": 2,
      "heading": "قوانین کلی",
      "content": "| قانون | توضیح |\n|---|---|\n| تفکیک مسئولیت | هر پوشه یک مسئولیت دارد — `src` برای کد، `tests` برای تست، `docs` برای مستندات |\n| عدم نفوذ | هیچ فایل مستنداتی در `src/`، هیچ فایل کدی در `docs/` |\n| خودکفایی | هر سرویس مستقل است — وابستگی به سرویس دیگر فقط از طریق API یا NATS |\n| CHANGELOG اجباری | هر تغییری باید در CHANGELOG ثبت شود |\n| README اجباری | هر سرویس باید `docs/README.md` داشته باشد (طبق الگوی مشخص) |\n| عدم تکرار | محتوای تکراری بین سرویس‌ها در پکیج‌های مشترک (`packages/`) قرار می‌گیرد |\n\n---"
    },
    {
      "level": 2,
      "heading": "ساختار Monorepo (ریشه اصلی پروژه)",
      "content": "```\nnons-api/                      ← ریشه اصلی پروژه (ROOT)\n│\n├── services/                  # همه سرویس‌ها\n│   ├── auth/\n│   │   ├── src/\n│   │   ├── tests/\n│   │   ├── docs/\n│   │   └── ...\n│   ├── order/\n│   ├── payment/\n│   └── ...\n│\n├── contracts/                 # **لایه قراردادهای پلتفرم (Proto — Source of Truth)**\n│   ├── envelope.proto\n│   ├── registry.proto\n│   ├── errors.proto\n│   └── permissions.proto\n│\n├── packages/                  # پکیج‌های اشتراکی (Bindingها و قراردادها)\n│   ├── contracts/             # Binding TS از Proto — Error Codes, Permissions (تولیدشده)\n│   ├── events/                # Binding TS از Proto — Event Envelope (تولیدشده)\n│   └── logging/               # قرارداد ثبت وقایع (interfaces — خارج از Proto)\n│\n├── core/                      # Go Core (از Bindingهای Go تولیدشده از Proto استفاده می‌کند)\n│\n├── infra/                     # زیرساخت توسعه محلی (کوبرنتیز)\n│   └── k8s/                   # مانیفست‌های K8s\n│\n├── nx.json                    # NX config\n├── package.json\n├── pnpm-workspace.yaml\n└── tsconfig.base.json\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "مرجع سریع: چه چیزی کجا می‌رود",
      "content": "**درون `nons-api/`:**\n\n| محتوا | مکان |\n|---|---|---|\n| قراردادهای پلتفرم (Proto SoT) | `contracts/` |\n| Bindingهای TS — Error Codes, Permissions | `packages/contracts/` (تولیدشده) |\n| Bindingهای TS — Event Envelope | `packages/events/` (تولیدشده) |\n| Catalog رویدادها (YAML/JSON) | `catalog/events/` |\n| قرارداد لاگینگ | `packages/logging/` |\n| مصنوعات فرانت‌اند (Types, API Client, Hooks) | `project/.nons/generated/` (تولیدشده توسط `nons generate`) |\n| انتزاعات دامنه | `core/` |\n| کد منبع سرویس | `services/{name}/src/` |\n| تست‌های سرویس | `services/{name}/tests/` |\n| مستندات سرویس | `services/{name}/docs/` |\n| دموی سرویس | `services/{name}/demo/` |\n| طرح اولیه سرویس | `services/{name}/blueprint/` |\n| تغییرات سرویس | `services/{name}/CHANGELOG.md` |\n\n| مانیفست‌های K8s | `infra/k8s/` |\n| اسرار | **هیچ‌کجا در git** — از secret manager استفاده کنید |"
    }
  ]
}