TorbatYar/docs/architecture.md

# معماری کلان پلتفرم SuperApp SaaS

## ۱. اهداف
ساخت یک SuperApp SaaS **چندمستأجری (Multi-tenant)**، **ماژولار**،
**API-first** و **microservice-ready** که ابتدا روی VPS و در آینده روی
زیرساخت مقیاس‌پذیر اجرا شود.

فاز ۱ تنها **Core Platform** را می‌سازد؛ اما ساختار پروژه به‌گونه‌ای است که
افزودن سرویس‌های بعدی بدون بازنویسی معماری ممکن باشد.

## ۲. سبک معماری
- **Service-oriented / Microservice-ready:** هر قابلیت بزرگ یک سرویس مستقل است.
- **Database-per-service:** هر سرویس فقط دیتابیس خودش را می‌شناسد.
- **API-first:** همه تعامل‌ها از طریق API/Event تعریف‌شده انجام می‌شوند.
- **Multi-tenancy:** همه جداول بیزینسی ستون `tenant_id` دارند.

### سرویس‌های اصلی (فعلی و آینده)
Core Platform (فاز ۱)، Identity & Access، Subscription & Entitlement،
Accounting، CRM، Ecommerce، Website Builder، Live Chat، AI Assistant،
Smart Messenger، SMS Panel، Link Shortener، Notification، File Storage،
Restaurant و ماژول‌های آینده Marketplace.

> در فاز ۱ فقط Core Platform پیاده شده است. بقیه سرویس‌ها در پوشه `backend/services/`
> به‌صورت placeholder با README مسئولیت‌ها موجودند.

## ۲.۱ Frontend & Backend Separation (اجباری)

### قانون معماری (سخت‌گیرانه)

پروژه **باید** از معماری کاملاً جدا (decoupled) پیروی کند. Backend و Frontend
دو اپلیکیشن کاملاً مستقل هستند و **هرگز نباید با هم مخلوط شوند.**

### Backend

تمام کد منبع backend فقط داخل پوشه `backend/` قرار می‌گیرد (Core Service و
سرویس‌های آینده).

**مسئولیت‌ها:**
- FastAPI
- SQLAlchemy
- Alembic
- Business Logic
- Authentication
- Authorization
- Database
- Background Workers
- APIs
- Event Processing

**Backend هرگز نباید شامل موارد زیر باشد:**
- React / Next.js
- Tailwind
- UI Components
- صفحات HTML
- Frontend assets

### Frontend

Frontend یک اپلیکیشن Next.js کاملاً جدا در پوشه `frontend/` است.

**مسئولیت‌ها:**
- UI
- Dashboard
- Forms
- Pages
- Components
- Layouts
- State Management
- API Client
- Theme

**Frontend هرگز نباید شامل موارد زیر باشد:**
- کد FastAPI
- دسترسی مستقیم به دیتابیس
- مدل‌های SQLAlchemy
- Alembic
- Business Logic
- کوئری مستقیم دیتابیس

### ارتباط (Communication)

Frontend فقط از طریق **REST API نسخه‌دار** (و در آینده WebSocket در صورت نیاز)
با backend ارتباط برقرار می‌کند.

هیچ کد منبع مشترکی بین frontend و backend وجود ندارد، **به‌جز:**
- قراردادهای API
- اسکیماهای مشترک
- SDKهای تولیدشده
- تعاریف نوع (type definitions) مشترک

### ساختار پوشه‌ها (اجباری)

```
superapp-platform/
├── backend/
│   ├── core-service/
│   ├── shared-lib/
│   └── services/
│
├── frontend/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── hooks/
│   ├── styles/
│   └── public/
│
├── docs/
├── docker-compose.yml
├── .env.example
└── README.md
```

> این جداسازی در کل پروژه اجباری است. فایل‌های frontend هرگز نباید به پوشه‌های
> backend منتقل شوند و بالعکس — حتی برای راحتی. هر قابلیت جدید باید این
> معماری را حفظ کند.

## ۳. تصمیم معماری دیتابیس
- الگوی **Database-per-service**.
- **ارتباط مستقیم بین دیتابیس سرویس‌ها ممنوع است.**
- ارتباط بین سرویس‌ها فقط از طریق:
  - REST API
  - Webhook
  - Async Event
  - الگوی Outbox/Inbox
- در فاز ۱ فقط دیتابیس `core_platform_db` ساخته می‌شود.
- طراحی اولیه دیتابیس سرویس‌های آینده در `database_schema.md` آمده اما
  migration واقعی آن‌ها ساخته نشده است.

## ۴. Core Platform Service
مسئول مفاهیم مشترک و مرکزی پلتفرم:
- مدیریت Tenant و Domain
- مدیریت Plan / Feature / Subscription و بررسی دسترسی (Entitlement)
- Service Registry و Module Registry
- توکن‌های داخلی سرویس (Internal Service Tokens)
- الگوی Outbox/Inbox و Audit Log

### لایه‌بندی داخلی سرویس هسته
```
API (routers)  →  Services (business logic)  →  Repositories  →  Models (DB)
                         ↑
                     Schemas (Pydantic)
```
- **core/**: زیرساخت (config, database, cache, security, logging)
- **middlewares/**: تشخیص tenant
- **workers/**: Celery و taskها

## ۵. Multi-tenancy و Tenant Resolution
ترتیب تشخیص tenant در middleware:
1. هدر `X-Tenant-ID`
2. هدر `X-Tenant-Slug`
3. Subdomain (از روی Host و `base_domain`)
4. Custom domain (از روی Host)

نتیجه در `request.state.tenant_id` و `request.state.tenant_slug` قرار می‌گیرد.
برای endpointهای tenant-aware از dependency `require_tenant` استفاده می‌شود که
در نبود tenant خطای `tenant_not_resolved` برمی‌گرداند.

## ۶. Entitlement (بررسی دسترسی قابلیت)
تابع مرکزی `EntitlementService.check_feature_access(tenant_id, feature_key)`:
1. ابتدا Redis cache بررسی می‌شود.
2. در نبود cache، از دیتابیس محاسبه می‌شود.
3. نتیجه با TTL در Redis ذخیره می‌گردد.

قواعد: اگر tenant غیرفعال باشد، اشتراک غیرفعال باشد، یا قابلیت در پلن نباشد →
دسترسی false. دسترسی سفارشی (custom access) بالاترین اولویت را دارد.

## ۷. رویدادها (Outbox/Inbox)
- رویدادهای خروجی ابتدا در جدول `outbox_events` و در **همان تراکنش** عملیات
  بیزینسی ذخیره می‌شوند (تضمین atomicity).
- یک task دوره‌ای Celery (`process_outbox_events`) رویدادهای pending را پردازش
  و وضعیت آن‌ها را به‌روزرسانی می‌کند.
- جدول `inbox_events` برای idempotency رویدادهای ورودی است.

## ۸. امنیت و SSO (فاز ۲ و ۳)

### اصل یکپارچگی: شماره موبایل الزامی است

در سامانه یکپارچه TorbatYar، **شماره موبایل برای همه کاربران واجب** است و
با **OTP پیامکی** تأیید می‌شود.

### لایه‌های هویت (تفکیک اجباری)

| لایه | چه کسی | SSO مرکزی Keycloak |
|------|--------|-------------------|
| **هسته TorbatYar** | مدیر پلتفرم، صاحب/کارمند tenant | **اجباری** |
| **زیرسیستم‌ها (staff)** | پنل کافه، CRM، … | **اجباری** — همان JWT |
| **مشتری tenant** | سفارش‌دهنده منوی دیجیتال | **اختیاری** — auth محلی tenant |

- `frontend/lib/optional-sso.ts` — برای UIs زیرسیستم: اگر session مرکزی هست، login دوباره لازم نیست.
- مشتری end-user در `restaurant_db` / `crm_db` ذخیره می‌شود، نه Keycloak مرکزی.

**ورود مرکزی فقط از Keycloak** (تم torbatyar) با دو تب «رمز عبور» و «موبایل»؛ frontend فقط redirect می‌کند.

```
┌─────────────────────────────────────────────────────────────────┐
│     F) ورود مرکزی Keycloak — تنها نقطه ورود کاربر              │
├─────────────────────────────────────────────────────────────────┤
│  Keycloak /realms/superapp/.../auth (تم torbatyar)             │
│    تب «رمز عبور»: نام کاربری / ایمیل / موبایل + رمز            │
│    تب «موبایل»: OTP + ثبت‌نام inline (mobile-auth.js)          │
│    → Identity /auth/mobile/* → handoff → /auth/callback        │
│  Frontend /login و /register → redirect به Keycloak            │
│  Admin: همان SSO — /admin/login → Keycloak → /admin/tenants       │
└─────────────────────────────────────────────────────────────────┘
```

### احراز هویت OTP (Core Service)
```
کاربر → Frontend → POST /api/v1/auth/otp/request?context=public|admin
                → Payamak (pattern 245189)
                → POST /api/v1/auth/otp/verify
                → JWT محلی (HS256)
```

- `context=public`: نقش پیش‌فرض `user` (ثبت‌نام عمومی)
- `context=admin`: نقش `pending_tenant_admin` (پنل tenant)
- `PLATFORM_ADMIN_MOBILES`: ارتقا به `platform_admin`

جدول `users` در Core: `mobile` (unique)، `mobile_verified`، `keycloak_sub` (لینک SSO).

### معماری SSO مرکزی
```
کاربر → Frontend → Keycloak (OIDC) → JWT
                                      ↓
              Identity /auth/me → requires_mobile_verification?
                                      ↓
              همه سرویس‌ها JWT را validate می‌کنند
```

### Identity & Access Service
- دیتابیس: `identity_access_db`
- جدول `user_profiles`: `mobile`, `mobile_verified`, `core_user_id`
- APIهای جدید:
  - `POST /api/v1/auth/mobile/start` — تشخیص login/register + ارسال OTP
  - `POST /api/v1/auth/mobile/complete` — تأیید OTP + صدور توکن SSO
  - `POST /api/v1/auth/session/redeem` — handoff از Keycloak theme
  - `POST /api/v1/auth/register` (legacy)
  - `POST /api/v1/auth/register/verify-mobile`
  - `POST /api/v1/auth/register/mobile`
  - `POST /api/v1/auth/register/mobile/verify`
  - `POST /api/v1/auth/mobile/request` (کاربر SSO لاگین‌شده)
  - `POST /api/v1/auth/mobile/verify`
- OTP از طریق Core Service (`CoreOtpClient`) — بدون تکرار منطق SMS

### Keycloak
- تم `torbatyar`: **ورود مرکزی** — تب رمز عبور + تب موبایل (OTP)
- `theme.properties`: `identityApiUrl`, `frontendCallbackUrl`
- attribute کاربر: `mobile` در Admin API
- Realm: `superapp` — زبان پیش‌فرض `fa`

### اعتبارسنجی JWT
- کتابخانه مشترک: `shared/auth/jwt.py`
- نرمال‌سازی موبایل مشترک: `shared/phone.py`

## ۹. زیرساخت
- Docker و docker-compose (postgres, redis, keycloak, core-service,
  identity-access-service, frontend, celery-worker, celery-beat).
- همه تنظیمات از `.env` خوانده می‌شوند؛ **هیچ چیز hardcode نمی‌شود**.
- Nginx/Traefik در فازهای بعدی به‌عنوان reverse proxy اضافه می‌شوند.

## ۱۰. White-label
برند (نام، رنگ، لوگو، ایمیل پشتیبانی) از `env`/config/دیتابیس خوانده می‌شود.
Frontend در `frontend/` رنگ‌ها را از طریق **CSS Variables** و `public/theme.config.json`
اعمال می‌کند تا تغییر برند بدون build مجدد ممکن باشد.

## ۱۱. فاز ۴ — Tenant Onboarding و Workspace Activation

> در بریف پروژه این کار با عنوان **«Phase 3: operationalizing tenant onboarding
> and workspace activation»** معرفی شده است؛ چون در شماره‌گذاری داخلی مستندات
> پیش‌تر «فاز ۳» به OTP Login + Tenant Management اختصاص یافته بود (نگاه کنید
> به `progress.md`)، این کار به‌عنوان **فاز ۴** پروژه ثبت می‌شود تا تاریخچه
> پیاده‌سازی واقعی حفظ شود. محتوای این فاز دقیقاً همان چیزی است که در بریف
> «Phase 3» خوانده می‌شود.

### هدف
سیستم را از «هویت + لیست ادمین» به یک **workspace عملیاتی چندمستأجری واقعی**
تبدیل می‌کند: کاربر OTP/SSO می‌زند، در نبود tenant به onboarding هدایت می‌شود،
یک workspace (tenant) می‌سازد، مالک آن می‌شود، پلن پیش‌فرض و دامنه اولیه
می‌گیرد، برندینگ را تنظیم می‌کند و در پایان وارد یک داشبورد واقعی tenant
می‌شود (نه فقط صفحات لیست ادمین).

### مدل عضویت Tenant (Tenant Membership)
جدول جدید `tenant_memberships` در **`core_platform_db`** رابطهٔ واقعی
کاربر↔tenant را نگه می‌دارد (مستقل از جدول هم‌نام و ساده‌تر
`tenant_memberships` در `identity_access_db` که برای مدیریت اعضای هویتی
استفاده می‌شود؛ این دو جدول در دو دیتابیس/سرویس متفاوت‌اند و هیچ ارتباط
مستقیمی ندارند).

نقش‌ها: `platform_admin`, `tenant_owner`, `tenant_admin`, `tenant_editor`,
`tenant_viewer`. وضعیت عضویت: `active` / `invited` / `disabled`. هر tenant
باید حداقل یک `tenant_owner` فعال داشته باشد (بررسی در زمان
`POST /onboarding/tenant/{id}/complete`). یک کاربر می‌تواند در آینده عضو چند
tenant باشد (`current_tenant_id` روی `users` مشخص می‌کند کدام tenant «جاری»
است).

### چرخهٔ عمر Tenant (Activation Lifecycle)
`tenant.status` اکنون این مقادیر عملیاتی را پشتیبانی می‌کند:

```
draft → pending_activation → active → suspended / archived
```

- tenant تازه‌ساخته‌شده از مسیر onboarding با `pending_activation` شروع می‌شود.
- با تکمیل onboarding (`POST .../complete`) و اعتبارسنجی (نام/slug موجود و
  حداقل یک owner فعال) به `active` تغییر می‌کند.
- `suspended`/`archived` فقط توسط پنل ادمین (فاز‌های قبلی، `PATCH
  /admin/tenants/{id}`) قابل تنظیم‌اند.
- مقادیر قدیمی `inactive`/`deleted` برای سازگاری با داده‌های فاز ۱ حفظ شده‌اند.

### پروفایل و برندینگ Tenant
ستون‌های برندینگ/تنظیمات مستقیماً روی جدول `tenants` اضافه شده‌اند (بدون
جدول جدا، چون حجم کم و همیشه ۱به۱ با tenant است): `business_type`,
`default_locale`, `timezone`, `primary_color`, `secondary_color`,
`logo_url`, `favicon_url`, `onboarding_completed`.

### پلن / اشتراک (بدون درگاه پرداخت)
ساختار `plans` و `tenant_subscriptions` از فاز ۱ موجود بود؛ در این فاز:
- یک پلن پیش‌فرض «FREE» (و «STARTER» برای آینده) از طریق migration seed
  می‌شود (`PlanService.ensure_default_plan` idempotent است).
- هنگام `POST /onboarding/tenant`، به‌صورت خودکار یک `tenant_subscriptions`
  با `plan=FREE` و `status=active` ساخته می‌شود.
- درگاه پرداخت پیاده‌سازی **نشده** — فقط ساختار provisioning است.

### نگاشت دامنه (Tenant Domain Mapping)
جدول `domains` (فاز ۱) با دو ستون جدید تقویت شده: `is_primary` (دامنهٔ
اصلی/پیش‌فرض tenant) و `verification_status` (`pending`/`verified`/`failed`).
هنگام `POST /onboarding/tenant`، اگر `PLATFORM_BASE_DOMAIN` تنظیم شده باشد،
زیردامنهٔ `{slug}.{PLATFORM_BASE_DOMAIN}` به‌صورت خودکار و از پیش
verified ساخته می‌شود. دامنهٔ اختصاصی (custom) از طریق
`PATCH /onboarding/tenant/{id}/domain` با وضعیت `pending` اضافه می‌شود و
تأیید واقعی آن به فازهای بعدی موکول شده است.

### Tenant Resolution و Current Tenant Context
علاوه بر middleware قبلی (`X-Tenant-ID` → `X-Tenant-Slug` → subdomain →
custom domain)، این dependencyهای جدید اضافه شدند:
- `get_current_core_user` / `get_optional_core_user`: رکورد واقعی
  `users` را چه برای JWT محلی (OTP) و چه برای JWT کیکلوک (SSO، بر اساس
  `keycloak_sub`) resolve می‌کنند.
- `get_tenant_resolution`: اول هدر/دامنه (middleware)، در نبود آن
  `current_tenant_id` کاربر جاری را برمی‌گرداند؛ endpointهای platform-admin
  فعلی تحت تأثیر قرار نمی‌گیرند.
- `TenantContextService.resolve_current_tenant`: برای `GET /tenant/current`
  استفاده می‌شود (بر اساس `current_tenant_id` یا اولین عضویت کاربر).

### رابطهٔ ورود OTP/SSO با provisioning workspace
هر دو مسیر احراز هویت (JWT محلی OTP فاز ۱ صادرشده از Core، و JWT کیکلوک SSO
فاز ۲ صادرشده از Identity) در نهایت باید به یک رکورد `users` در
`core_platform_db` متصل شوند تا onboarding معنا پیدا کند:

```
JWT محلی (HS256)  → users.id  ──┐
                                 ├─→ UserService.resolve_current() → User
JWT کیکلوک (RS256) → users.keycloak_sub ──┘
```

اگر کاربر SSO هنوز به هیچ رکورد Core لینک نشده باشد (یعنی هرگز از مسیر OTP
محلی Core عبور نکرده)، `resolve_current` خطای `forbidden` برمی‌گرداند — به
این معنا که JIT provisioning کامل کاربر Core از JWT کیکلوک فعلاً در محدودهٔ
این فاز پیاده نشده و به فاز بعدی موکول شده (نگاه کنید به `last_step.md`).

### APIهای Onboarding
جزئیات کامل در `services_contracts.md`؛ خلاصه:
`GET /me`, `GET /me/tenants`, `POST /onboarding/tenant`,
`PATCH /onboarding/tenant/{id}/branding`,
`PATCH /onboarding/tenant/{id}/domain`,
`POST /onboarding/tenant/{id}/complete`, `GET /tenant/current`,
`POST /tenant/switch`.

### Authorization
`MembershipService.ensure_role` بررسی می‌کند که کاربر جاری روی tenant مقصد
نقش `tenant_owner` یا `tenant_admin` داشته باشد (پیش‌فرض برای مدیریت
برندینگ/دامنه/تکمیل onboarding)؛ `platform_admin` همیشه bypass می‌شود.
endpointهای onboarding فقط نیاز به کاربر احرازهویت‌شده دارند (بدون بررسی
نقش برای ساخت tenant جدید، چون هر کاربر می‌تواند workspace خودش را بسازد).

### Frontend
- **Bootstrap:** پس از ورود، `hooks/useMe.ts` نتیجهٔ `GET /api/v1/me` را
  می‌گیرد. صفحهٔ `/dashboard` اگر `onboarding_required=true` باشد کاربر را
  به `/onboarding` هدایت می‌کند.
- **Onboarding Wizard:** صفحهٔ تک‌فایلی `app/onboarding/page.tsx` با ۴ گام
  (اطلاعات کسب‌وکار → برندینگ → دامنه → بازبینی) که به‌ترتیب APIهای
  onboarding را صدا می‌زند و در پایان به `/dashboard` هدایت می‌کند.
- **Tenant Dashboard:** `app/dashboard/page.tsx` اطلاعات tenant جاری
  (`GET /tenant/current`) را نمایش می‌دهد: نام، وضعیت، پلن، دامنه، وضعیت
  onboarding و نقش کاربر.
- **Tenant Switcher:** `components/TenantSwitcher.tsx` — فقط وقتی کاربر
  بیش از یک عضویت داشته باشد نمایش داده می‌شود و از `POST /tenant/switch`
  استفاده می‌کند.