{
  "title": "تصمیمات معماری مصوب",
  "slug": "team/platform/ADR/ADR-Platform-003",
  "url": "/docs/team/platform/ADR/ADR-Platform-003",
  "frontmatter": {
    "layout": "doc",
    "title": "تصمیمات معماری مصوب",
    "description": "ثبت رسمی تصمیمات معماری مصوب شامل Versioning, Domain, Environment, Release, Registry, Secrets",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "Antigravity",
    "owner": "Platform Team",
    "created_at": "2026-06-15",
    "updated_at": "2026-06-15",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "تصمیمات معماری مصوب",
      "content": "**Architectural Decision Record — Approved Architecture Decisions**\n\n> **Status:** APPROVED\n> **Date:** 2026-06-15\n\n---"
    },
    {
      "level": 2,
      "heading": "زمینه (Context)",
      "content": "این سند ۷ تصمیم معماری مصوب را که پیش از این در مستندات پراکنده ثبت شده یا ثبت نشده بودند، به صورت رسمی و متمرکز ثبت می‌کند.\n\n**پیش‌نیاز انجام شده:** قبل از نگارش این سند، تمام مستندات موجود (`versioning-policy.md`, `container-delivery-architecture.md`, `security-policy.md`, `roadmap.md`, ADRهای موجود) بررسی شدند تا از ثبت تکراری (Duplicate) جلوگیری شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. Versioning",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تصمیم",
      "content": "**Semantic Versioning 2.0.0 از هم‌اکنون برای همه سرویس‌ها و پکیج‌ها پذیرفته شده است.**"
    },
    {
      "level": 3,
      "heading": "الگوی نسخه",
      "content": "```\nv{major}.{minor}.{patch}\n```\n\n| مرحله | الگو | مثال |\n|-------|------|-------|\n| توسعه داخلی | `v0.{minor}.{patch}` | `v0.1.0`, `v0.2.0` |\n| انتشار پایدار | `v{major}.{minor}.{patch}` | `v1.0.0`, `v1.2.0` |\n| پیش‌انتشار | `v{version}-{tag}.{n}` | `v1.0.0-alpha.1`, `v1.0.0-rc.1` |"
    },
    {
      "level": 3,
      "heading": "مستندات مرتبط",
      "content": "جزئیات کامل قوانین افزایش نسخه، انتشار و وابستگی نسخه‌ها در سند [`versioning-policy.md`](../standards/versioning-policy.md) ثبت شده است. این ADR آن سند را تأیید و به عنوان مصوب اعلام می‌کند.\n\n| ایتم | ارجاع |\n|------|--------|\n| قوانین MAJOR/MINOR/PATCH | `versioning-policy.md#2-قوانین-افزایش-نسخه` |\n| پیش‌انتشار (alpha, beta, rc) | `versioning-policy.md#3-پیش‌انتشار` |\n| Git Tagging | `versioning-policy.md#5-انتشار` |\n| Docker Image Tagging | `container-delivery-architecture.md#22-image-versioning-policy` |\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. Domain Strategy",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تصمیم",
      "content": "**دامنه‌ها در کد هاردکد نمی‌شوند و به صورت Config-Driven از طریق متغیرهای محیطی تأمین می‌شوند.**"
    },
    {
      "level": 3,
      "heading": "متغیرهای الزامی",
      "content": "| متغیر | توضیح | مثال (Development) | مثال (Production) |\n|--------|-------|-------------------|-------------------|\n| `API_DOMAIN` | دامنه اصلی API | `api.localhost` | `api.nons.app` |\n| `AUTH_DOMAIN` | دامنه احراز هویت | `auth.localhost` | `auth.nons.app` |\n| `WEB_DOMAIN` | دامنه وب/فرانت‌اند | `localhost` | `nons.app` |"
    },
    {
      "level": 3,
      "heading": "قوانین",
      "content": "| قانون | توضیح |\n|-------|-------|\n| هاردکد ممنوع | هیچ دامنه‌ای در کد سرویس نوشته نشود |\n| Config Source | متغیر محیطی یا K8s ConfigMap |\n| پیش‌فرض | اگر متغیر تنظیم نشده باشد، سرویس باید fail fast کند (نه fallback بی‌صدا) |\n| Validation | مقدار دامنه در زمان راه‌اندازی سرویس اعتبارسنجی شود (فرمت URL معتبر) |"
    },
    {
      "level": 3,
      "heading": "مستندات مرتبط",
      "content": "این تصمیم جدید است و در مستندات قبلی ثبت نشده بود. جزئیات پیاده‌سازی به مستندات هر سرویس موکول می‌شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. Environment Model",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تصمیم",
      "content": "**سه محیط زیر در معماری باقی می‌مانند:**\n\n| محیط | وضعیت در فاز فعلی | توضیح |\n|------|------------------|-------|\n| **Development** | ✅ Active | توسعه محلی روی K3d |\n| **Staging** | ✅ Active | استقرار خودکار برای اعتبارسنجی |\n| **Production** | ⏳ Planned | فعلاً پیاده‌سازی نمی‌شود |"
    },
    {
      "level": 3,
      "heading": "فازبندی",
      "content": "```\nPhase 1 (Current): Development + Staging فعال\nPhase 2 (Future):  Production اضافه می‌شود\n```"
    },
    {
      "level": 3,
      "heading": "قوانین محیطی",
      "content": "| قانون | Development | Staging | Production |\n|-------|------------|---------|------------|\n| Cluster | K3d | K3s | K3s |\n| Deploy Trigger | دستی (`k3d image import` + `helm upgrade`) | خودکار (CI پس از merge) | دستی (با تأیید) |\n| Image Source | Local build | ghcr.io (SHA tag) | ghcr.io (Version tag) |\n| Data | Ephemeral | Realistic | Real |\n| Secrets | Dev secrets | Stage secrets | Production secrets |"
    },
    {
      "level": 3,
      "heading": "مستندات مرتبط",
      "content": "جزئیات پیاده‌سازی محیط‌ها در [`setup-guide.md`](../../devops/setup-guide.md) و [`helm-architecture.md`](../../devops/helm-architecture.md) ثبت شده است.\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. Release Strategy",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تصمیم",
      "content": "**مسیر انتشار رسمی (برای فاز فعلی):**\n\n```text\nDeveloper\n  ↓\nStaging (استقرار خودکار)\n  ↓\nValidation (تست‌های E2E)\n  ↓\nProduction (استقرار دستی با تأیید)\n```"
    },
    {
      "level": 3,
      "heading": "محدودیت‌های مصوب",
      "content": "| روش | وضعیت | دلیل |\n|-----|-------|------|\n| Canary Deployment | ❌ خارج از معماری فعلی | نیاز به Service Mesh + Flagger |\n| Blue/Green Deployment | ❌ خارج از معماری فعلی | نیاز به مدیریت دو 환경 کامل |\n| Progressive Delivery | ❌ خارج از معماری فعلی | نیاز به Feature Flags + Traffic Split |\n| **Rolling Update** | ✅ تنها روش مجاز | پشتیبانی شده توسط Kubernetes |"
    },
    {
      "level": 3,
      "heading": "مستندات مرتبط",
      "content": "جزئیات بیشتر در [`release-lifecycle-blueprint.md`](../../devops/release-lifecycle-blueprint.md) و [`cicd-architecture-blueprint.md`](../../devops/cicd-architecture-blueprint.md) به عنوان BLUEPRINT ثبت شده‌اند.\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. Registry Architecture",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تصمیم",
      "content": "**ثبت‌کننده رسمی کانتینر: GitHub Container Registry (ghcr.io)**"
    },
    {
      "level": 3,
      "heading": "خلاصه تصمیمات",
      "content": "| مؤلفه | تصمیم |\n|-------|--------|\n| Provider | `ghcr.io/nons/*` |\n| Visibility | همه Private |\n| Naming | `ghcr.io/nons/{service-name}` |\n| Tag Pattern | SemVer برای Release, `sha-{commit}` برای هر commit |\n| Immutability | همه تگ‌ها به جز `latest` |"
    },
    {
      "level": 3,
      "heading": "مستندات مرتبط",
      "content": "این تصمیم به صورت کامل در [`container-delivery-architecture.md`](../../devops/container-delivery-architecture.md) (وضعیت: APPROVED) ثبت شده است. جزئیات را در آن سند ببینید:\n\n| ایتم | ارجاع |\n|------|--------|\n| Repository Naming | `container-delivery-architecture.md#12-نام‌گذاری-مخازن` |\n| Tagging Rules | `container-delivery-architecture.md#22-image-versioning-policy` |\n| Image Lifecycle | `container-delivery-architecture.md#15-retention-policy` |\n| Authentication | `container-delivery-architecture.md#14-احراز-هویت-registry` |\n| Image Promotion | `container-delivery-architecture.md#34-image-promotion-بین-محیط‌ها` |\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. Environment Architecture (ثبت رسمی)",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تصمیم",
      "content": "همان Environments از بخش ۳ با تأکید زیر:\n\n| محیط | Active? | Cluster | Image Source | Deploy Trigger |\n|------|---------|---------|-------------|---------------|\n| **Development** | ✅ Active | K3d | Local build (`latest`) | دستی |\n| **Staging** | ✅ Active | K3s | ghcr.io (`sha-{commit}`) | خودکار (CI) |\n| **Production** | ⏳ Planned | K3s | ghcr.io (`{version}`) | دستی (تأیید) |"
    },
    {
      "level": 3,
      "heading": "اولویت استقرار",
      "content": "1. توسعه‌دهنده روی Development کار می‌کند\n2. کد به main merged می‌شود → Staging خودکار استقرار می‌یابد\n3. Staging تأیید شد → Production دستی استقرار می‌یابد\n4. Production = Planned (فعلاً مرحله ۳ در معماری نیست)\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. Secrets Architecture",
      "content": ""
    },
    {
      "level": 3,
      "heading": "تصمیم",
      "content": "**مدیریت رازها در فاز فعلی از طریق Kubernetes Secrets انجام می‌شود. هیچ Secret Manager (Vault یا مشابه) در معماری فعلی وجود ندارد.**"
    },
    {
      "level": 3,
      "heading": "فهرست رازهای مصوب",
      "content": "| راز | توضیح | مالک | تزریق به | روش تزریق در K8s |\n|-----|-------|------|---------|-----------------|\n| `DB_PASSWORD` | رمز دیتابیس PostgreSQL | Devops | Postgres, Kratos, Hydra, Auth Service | `envFrom.secretRef` |\n| `JWT_PRIVATE_KEY` | کلید خصوصی امضای JWT | Backend | Hydra (OIDC) | ConfigMap (dev) / Secret (stage) |\n| `JWT_SIGNING_KEY` | کلید اشتراکی HMAC | Backend | Auth Service | Secret |\n| `HYDRA_SYSTEM_SECRET` | رمز داخلی Hydra | Backend | Hydra | Secret |\n| `KRATOS_COURIER_SMTP` | رمز SMTP (mailslurper) | Backend | Kratos | ConfigMap (dev) |\n| `REGISTRY_TOKEN` | توکن دسترسی به GHCR | Devops | CI Pipeline + K8s `imagePullSecrets` | GitHub Secrets → K8s Secret |\n| `API_KEYS` | کلید سرویس‌های خارجی (Nobitex, Fixer) | Backend | Currency Service | Secret |\n| `COOKIE_SALT` | نمک کوکی سشن | Backend | Kratos | ConfigMap (dev) / Secret (stage) |\n| `OIDC_SALT` | نمک Subject Identifier | Backend | Hydra | Secret |"
    },
    {
      "level": 3,
      "heading": "نحوه تزریق",
      "content": ""
    },
    {
      "level": 4,
      "heading": "Development (K3d)",
      "content": "```bash"
    },
    {
      "level": 1,
      "heading": "رازها در ConfigMap/Secret تعریف می‌شوند (dev values)",
      "content": "helm install ... -f ./deploy/environments/local/values.yaml\n```"
    },
    {
      "level": 4,
      "heading": "Staging (K3s)",
      "content": "```bash\nkubectl create secret generic auth-service-secrets \\\n  --from-literal=JWT_SIGNING_KEY=... \\\n  -n nons-platform\n\nhelm install ... -f ./deploy/environments/staging/values.yaml\n```"
    },
    {
      "level": 3,
      "heading": "امنیت",
      "content": "| قانون | توضیح |\n|-------|-------|\n| هیچ رازی در git | `.env`, رازها در gitignore — فقط `.env.example` مجاز است |\n| حداقل دسترسی | هر سرویس فقط به رازهای خود دسترسی دارد |\n| چرخش دستی | رازها در فاز فعلی به صورت دستی چرخانده می‌شوند |\n| Vault | به معماری اضافه نخواهد شد مگر در فاز ۵ |\n| Registry Token | در GitHub Secrets ذخیره، به کلاستر تزریق می‌شود |"
    },
    {
      "level": 3,
      "heading": "مستندات مرتبط",
      "content": "جزئیات بیشتر در [`security-policy.md`](../standards/security-policy.md) و ADRهای Backend ثبت شده است.\n\n---"
    },
    {
      "level": 2,
      "heading": "خلاصه",
      "content": "| # | تصمیم | وضعیت | مستندات مرتبط |\n|---|--------|--------|--------------|\n| 1 | Semantic Versioning از هم‌اکنون | ✅ APPROVED | `versioning-policy.md` |\n| 2 | Domain Strategy: Config-Driven | ✅ APPROVED | این سند (جدید) |\n| 3 | Environment Model: Dev + Staging فعال | ✅ APPROVED | `setup-guide.md`, `helm-architecture.md` |\n| 4 | Release: Rolling Update only | ✅ APPROVED | `release-lifecycle-blueprint.md`, `cicd-architecture-blueprint.md` |\n| 5 | Registry: GHCR | ✅ APPROVED | `container-delivery-architecture.md` |\n| 6 | Environment Architecture: ثبت رسمی | ✅ APPROVED | این سند |\n| 7 | Secrets: K8s Secrets (بدون Vault) | ✅ APPROVED | `security-policy.md`, ADRs |\n\n---"
    },
    {
      "level": 2,
      "heading": "موارد خارج از Scope (فعلاً انجام نشود)",
      "content": "موارد زیر در این سند به عنوان تصمیم اجرایی ثبت **نمی‌شوند** و بخشی از معماری فعلی نیستند:\n\n- ❌ ArgoCD / Flux (GitOps)\n- ❌ HashiCorp Vault (Secret Manager)\n- ❌ Canary Deployment\n- ❌ Blue/Green Deployment\n- ❌ Progressive Delivery\n- ❌ Service Mesh (Istio / Linkerd)\n- ❌ Internal mTLS\n- ❌ Image Signing (Cosign) — فاز ۵\n- ❌ SBOM Generation — فاز ۵\n- ❌ Multi-Architecture Build — فاز ۵\n\nاین موارد در `roadmap.md` به عنوان آینده ثبت شده‌اند و تا تصمیم‌گیری جداگانه در معماری جاری اعمال نمی‌شوند."
    }
  ]
}