# Architecture — Modular Monolith

## اجزای اصلی

```mermaid
flowchart TD
 A[Admin Browser] --> B[PHP public/index.php]
 C[Bale Webhook HTTPS] --> B
 B --> D[App Controller / Auth]
 D --> E[(MySQL)]
 D --> F[Graph Draft/Publish]
 G[Cron / Supervisor Worker] --> E
 G --> H[Engine: pinned published graph]
 H --> E
 G --> I[Bale API Adapter]
 I --> J[Bale HTTPS API]
```

- `App`: مسیرها، بررسی مجوز، فرم مدیریتی، مدیریت جریان، export، webhook.
- `BaleApi`: allowlist متدها؛ هیچ بخش دیگری نباید URL بله را مستقیم بسازد.
- `Graph`: اعتبارسنجی، مسیرها، قالب‌بندی متغیرها، ارزیابی شرط و ورودی.
- `Engine`: پردازش آپدیت، نگهداری نشست، اجرای گره‌ها و صف خروجی.
- `Worker`: lock در MySQL، پردازش inbound و outbound، retry/backoff.
- `Security`: رمزنگاری توکن، auth، cookie و CSRF.

## چرخه Webhook

```mermaid
flowchart TD
 A[Bale POST] --> B{Random secret path correct?}
 B -- No --> X[404]
 B -- Yes --> C{Valid JSON/update_id?}
 C -- No --> Y[422]
 C -- Yes --> D[INSERT IGNORE inbound_updates]
 D --> E[HTTP 200]
 F[Cron worker] --> G[Claim pending update]
 G --> H[MySQL transaction]
 H --> I[Update user and session]
 I --> J[Queue outbound response]
 J --> K[Commit]
 L[Worker] --> M[Bale sendMessage]
 M --> N[Mark sent or retry]
```

**نکته:** API عادی بله در متد sendMessage تضمین exactly-once ارائه نمی‌کند. در وقوع crash پس از ارسال و قبل از ثبت sent، تشخیص تحویل ممکن نیست. با این نسخه از موازی‌کردن worker خودداری کنید. برای پیام‌های حساس مالی باید طراحی idempotency سطح سرویس و reconciliation مستقل افزوده شود.

## توسعه بلندمدت

درگاه ارتباط بله را مستقل نگه دارید؛ پرداخت، مینی‌اپ، AI و APIهای خارجی باید ماژول جدا، قرارداد اجرا و آزمایش مستقل داشته باشند. Sessionهای گذشته تا انتشار و انتقال کنترل‌شده نباید زیر نسخه جدید قرار گیرند. برای حجم بالا معماری Queue مقاوم و event bus جداسازی می‌شوند؛ پیش‌نیاز نسخه ابتدایی نیستند.