smart-org/PLAN.md

پلن نسخه وب مستقل Smart Organization

تاریخ تدوین: 2026-10-12
محل توسعه: /Users/mamad/Projects/agy-bot/web
وضعیت: فاز برنامه‌ریزی محصول، معماری و مسیر توسعه

---

1. خلاصه تصمیم اصلی

نسخه جدید نباید بازنویسی خط‌به‌خط ربات تلگرام فعلی باشد. پیشنهاد اصلی این است که محصول جدید به عنوان یک پلتفرم SaaS مستقل برای «نیروی کار هوش مصنوعی سازمانی» ساخته شود؛ یعنی کاربر نهایی مدل‌ها، کلیدها، Providerها و پیچیدگی‌های orchestration را نمی‌بیند، بلکه فقط با سازمان، مدیر هوش مصنوعی، کارمندان هوش مصنوعی، فایل‌ها، پروژه‌ها، مصرف و پرداخت سروکار دارد.

تعریف پیشنهادی محصول:

یک وب اپلیکیشن چندسازمانی که مالک سامانه در آن مدل‌ها، Providerها، سیاست‌های هوش مصنوعی، تعرفه‌ها، ابزارها و محیط‌های اجرای ایزوله را مدیریت می‌کند؛ کاربران سازمان می‌سازند، کارمندهای هوش مصنوعی استخدام/فعال می‌کنند، کارها را به مدیر یا کارمندها می‌سپارند، مصرفشان اندازه‌گیری می‌شود و بر اساس اعتبار یا اشتراک پرداخت انجام می‌دهند.

---

2. هدف نسخه جدید

2.1 هدف‌های محصولی

1. خروج کامل از بستر تلگرام و تبدیل به یک وب اپلیکیشن حرفه‌ای.
2. حذف وابستگی به chat_id، callbackهای تلگرام، message handlerها و محدودیت‌های UI تلگرام.
3. ساخت تجربه کاربری شبیه داشبوردهای مدرن SaaS.
4. پنهان‌سازی کامل مدل‌ها و Providerها از دید مشتری.
5. تعریف «سازمان»، «عضو»، «نقش»، «کارمند هوش مصنوعی»، «مدیر سازمان»، «پروژه»، «محیط اجرا»، «مصرف» و «پرداخت» به عنوان مفاهیم اصلی محصول.
6. ارائه محیط ایزوله برای اجرای کد/اپلیکیشن هر کاربر یا سازمان.
7. ایجاد زیرساخت billing، quota، audit، observability و کنترل کیفیت از روز اول.

2.2 هدف‌های فنی

1. معماری مستقل از کد فعلی؛ فقط از تجربه و منطق دامنه فعلی الهام گرفته شود.
2. طراحی بر اساس Clean Architecture، Hexagonal Architecture و Domain-Driven Design.
3. کنترل کامل multi-tenancy و امنیت داده‌ها.
4. قابلیت scale افقی برای runهای هوش مصنوعی و sandboxها.
5. امکان تغییر Provider و مدل بدون تغییر تجربه مشتری.
6. ثبت کامل eventها برای billing، audit، replay و debug.

---

3. یافته‌های بررسی بازار و نمونه‌های مشابه

این بخش بر اساس جستجوی وب و بررسی منابع رسمی/نزدیک به رسمی تدوین شده است.

3.1 Dify

منبع: https://docs.dify.ai/ و صفحات Model Providers / Agent

ویژگی‌های مهم:

• workspace دارد و Providerهای مدل در سطح workspace مدیریت می‌شوند.
• فقط owner/admin می‌تواند Provider و API key را مدیریت کند.
• appها از مدل‌های متصل‌شده در workspace استفاده می‌کنند.
• Agent app دارد؛ Agent می‌تواند تصمیم بگیرد از tool استفاده کند یا از knowledge base پاسخ بدهد.
• امکان debug با چند مدل، tool calling، RAG، multimodal input و انتشار app وجود دارد.

درس برای محصول ما:

• مدل‌ها باید در یک «AI Control Plane» مرکزی تعریف شوند، نه توسط کاربر نهایی.
• مشتری باید Agent/Employee ببیند، نه مدل خام.
• برای هر Agent باید prompt، ابزار، knowledge و محدودیت‌های اجرای آن قابل نسخه‌بندی باشد.

3.2 LangGraph / LangSmith Deployment

منبع: https://docs.langchain.com/langgraph-platform/ و صفحات LangSmith Deployment

ویژگی‌های مهم:

• مفاهیم production-grade مثل assistants، threads و runs دارد.
• روی durable execution، streaming، horizontal scaling، deployment و observability تمرکز دارد.
• حالت‌های cloud، hybrid، self-hosted و standalone agent server دارد.

درس برای محصول ما:

• اجرای Agent باید به صورت «Run» مستقل، قابل پیگیری، قابل توقف، قابل resume و قابل replay طراحی شود.
• thread/conversation نباید فقط یک لیست پیام ساده باشد؛ باید state، artifact، tool call، sandbox session و billing events را هم داشته باشد.

3.3 CrewAI Enterprise

منبع: https://crewai.com/agent-management-platform

ویژگی‌های مهم:

• build، deploy، observe و govern برای Agentها را به صورت یک control plane ارائه می‌کند.
• روی multi-agent workflows، tracing، human-in-the-loop، audit trail، RBAC و governance تأکید دارد.
• برای سازمان‌هایی طراحی شده که Agentهای زیادی در مقیاس production دارند.

درس برای محصول ما:

• فقط chat کافی نیست؛ باید management، governance و visibility داشته باشیم.
• مدیر سازمان باید بفهمد کدام Agent چه کاری انجام داده، چقدر هزینه داشته و کجا گیر کرده است.

3.4 Dust

منبع: https://dust.tt/

ویژگی‌های مهم:

• platform برای همکاری انسان و Agentهاست.
• اتصال به knowledge و ابزارهای سازمانی مثل Slack، Notion، Google Drive، GitHub، Salesforce و Zendesk دارد.
• multi-model است و مدل مناسب برای هر workflow قابل انتخاب است.
• permissions، audit logs، analytics، usage، costs و ROI دارد.

درس برای محصول ما:

• باید data permission و agent permission جدا باشند: اینکه Agent به چه داده‌ای دسترسی دارد، با اینکه چه کسی می‌تواند از Agent استفاده کند فرق دارد.
• analytics و cost visibility باید از ابتدا بخشی از محصول باشد.

3.5 Zapier Agents

منبع: https://zapier.com/agents

ویژگی‌های مهم:

• Agentها به هزاران اپلیکیشن متصل می‌شوند.
• Agent templates دارد.
• کاربر می‌تواند Agent بسازد، مانیتور کند، با آن chat کند و آن را در automationها به کار بگیرد.

درس برای محصول ما:

• marketplace/template برای کارمندهای آماده بسیار مهم است.
• اتصال به ابزارهای بیرونی باید با connector abstraction ساخته شود.

3.6 Relevance AI و Lindy

منابع جستجوشده: صفحات محصول و نتایج معرفی AI Workforce / AI Employees

ویژگی‌های قابل توجه:

• تمرکز روی AI workforce و AI employee.
• Agentهای آماده برای فروش، پشتیبانی، تحقیق، عملیات و automation.
• no-code/low-code builder برای تیم‌های غیرتوسعه‌دهنده.

درس برای محصول ما:

• زبان محصول باید از «مدل» و «workflow خام» به سمت «کارمند»، «مدیر»، «وظیفه»، «تیم» و «نتیجه کار» برود.
• تجربه کاربر باید شبیه استخدام و مدیریت نیروی کار هوش مصنوعی باشد.

3.7 E2B

منبع: https://docs.e2b.dev/

ویژگی‌های مهم:

• sandbox ایزوله برای اجرای کد، پردازش داده و ابزارها.
• sandbox سریع و امن، قابل pause/resume.
• template برای تعریف محیط شروع.
• persistence با ذخیره filesystem و memory هنگام pause.

درس برای محصول ما:

• اجرای کد Agent یا نرم‌افزار مشتری نباید روی host اصلی انجام شود.
• sandbox باید lifecycle مستقل، template و persistence داشته باشد.

3.8 Daytona

منبع: https://www.daytona.io/docs

ویژگی‌های مهم:

• sandboxهای کاملاً ایزوله با kernel، filesystem، network stack و منابع اختصاصی.
• اجرای Python، TypeScript و JavaScript.
• snapshot برای تداوم state.
• SDK، API و CLI برای lifecycle، filesystem و process execution.

درس برای محصول ما:

• برای MVP می‌توان به جای ساخت sandbox infra از صفر، یک لایه Sandbox Gateway روی Daytona/E2B ساخت.
• snapshot برای محیط‌های کاربری و پروژه‌های طولانی‌مدت ضروری است.

3.9 Modal Sandboxes

منبع جستجو: Modal Sandboxes docs

ویژگی‌های مهم:

• sandbox برای اجرای کد untrusted یا agent-generated.
• مناسب اجرای command روی repo، تست، jobهای موقت و workloadهای AI.

درس برای محصول ما:

• برای کارهای کوتاه‌مدت و compute موقت، sandboxهای serverless سریع گزینه خوبی هستند.

3.10 Firecracker

منبع: https://firecracker-microvm.github.io/

ویژگی‌های مهم:

• microVM برای سرویس‌های multi-tenant، function-based و container-based.
• VM-level isolation با سرعت و overhead نزدیک به container.
• KVM، jailer، rate limiter و attack surface کوچک.
• boot سریع و مناسب workloadهای multi-tenant.

درس برای محصول ما:

• اگر بخواهیم sandbox را خودمان در مقیاس production بسازیم، microVM جدی‌ترین مسیر امنیتی است.
• container تنها برای اجرای کد untrusted کافی نیست مگر اینکه با policy و isolation سخت‌گیرانه ترکیب شود.

3.11 Stripe Billing

منبع: https://docs.stripe.com/billing

ویژگی‌های مهم:

• subscription، invoice، pricing model، usage-based billing، tiered pricing و customer portal.
• مناسب ثبت مصرف، صدور invoice و مدیریت اشتراک.

درس برای محصول ما:

• billing باید event-driven باشد: هر model call، sandbox runtime، storage، tool call و خروجی قابل اندازه‌گیری باید usage event تولید کند.

3.12 Supabase

منبع: https://supabase.com/docs

ویژگی‌های مهم:

• Postgres، Auth، Storage، Realtime، Edge Functions، RLS، API، Cron و Queues.
• self-host و managed دارد.

درس برای محصول ما:

• اگر سرعت MVP مهم‌تر از کنترل کامل infra باشد، Supabase برای auth/storage/database سریع است.
• اما برای محصول چندسازمانی با billing و sandbox جدی، بهتر است schema و backend core تحت کنترل خودمان باشد.

---

4. مشکلات فعلی که نسخه جدید باید حل کند

بررسی کد فعلی نشان می‌دهد پروژه فعلی یک Telegram Bot بسیار بزرگ و پیچیده است. مهم‌ترین نقاط درد:

4.1 وابستگی عمیق به تلگرام

نمونه فایل‌ها:

• bot.py: import مستقیم telegram، Application، CommandHandler، MessageHandler، CallbackQueryHandler، InlineKeyboardMarkup و منطق اصلی پیام/کلیک.
• config.py: تنظیمات TELEGRAM_BOT_TOKEN، BOT_MODE، webhook، polling و secret token.
• web_panel.py: اعتبارسنجی Telegram WebApp initData و استفاده از X-Telegram-Init-Data.
• bot_menus.py و bot_org_models.py: UI بر اساس inline keyboard و callback_data.

نتیجه:

• UI، احراز هویت، state machine و domain logic با Telegram coupling ساخته شده‌اند.
• تغییر به وب واقعی با patch کردن همین کد، پیچیدگی را بیشتر می‌کند.

4.2 state و wizardهای وابسته به پیام

نمونه‌ها:

• USER_INPUT_STATES
• callbackهای کوتاه callback_data
• wizardهای چندمرحله‌ای داخل پیام‌ها
• tokenهای موقت داخل memory مثل PANEL_TOKENS

راه‌حل نسخه جدید:

• استفاده از session واقعی، فرم‌های وب، route state، database-backed workflow state و optimistic UI.
• wizardها باید entity مستقل در DB باشند، نه state موقت داخل process.

4.3 هویت کاربر بر پایه chat_id

نمونه‌ها:

• workspace_for(chat_id, project_name)
• owner_id در بسیاری از جدول‌ها که عملاً با Telegram user id یکی شده است.

راه‌حل نسخه جدید:

• مدل هویتی جدید: User, Organization, Membership, Role, Workspace, Project.
• هیچ منطق جدیدی نباید به Telegram id وابسته باشد.

4.4 SQLite و migrationهای runtime

پروژه فعلی از SQLite مرکزی (data/memory.db) و تعداد زیادی migration داخل کد runtime استفاده می‌کند.

راه‌حل نسخه جدید:

• PostgreSQL به عنوان دیتابیس اصلی.
• migration رسمی با Alembic یا Prisma/Drizzle.
• multi-tenancy با organization_id و در لایه حساس با Row Level Security یا policy enforcement.

4.5 monolith نامنظم و فایل‌های بسیار بزرگ

نمونه‌ها:

• bot.py چندین مسئولیت دارد: routing، UI، auth، org، engine، menus، background task، webhook.
• web_panel.py هم API، auth، template، org endpoints و integrationهای مختلف را در یک فایل ترکیب کرده است.

راه‌حل نسخه جدید:

• Modular Monolith تمیز در شروع؛ نه microservice زودهنگام.
• هر bounded context پوشه و interface خودش را داشته باشد.

4.6 اجرای process و ابزار روی سرور اصلی

نمونه‌ها:

• agy_engine.py مدیریت process، timeout، kill group و registry دارد.
• remote_dev_executor.py تلاش کرده sandbox محدود بسازد اما همچنان سطح امنیتی آن با microVM برابر نیست.

راه‌حل نسخه جدید:

• اجرای هر کد untrusted فقط از مسیر Sandbox Gateway.
• host اصلی فقط control plane باشد، نه محل اجرای کد مشتری.

---

5. پیشنهاد محصول برای نسخه وب

5.1 نقش‌ها

پیاده‌سازی‌شده (ساختار مالکیت پلتفرم): مالک سامانه دقیقاً یک نفر است و این یک قاعدهٔ دیتابیسی است (ایندکس یکتای جزئی روی users.platform_role). فقط او می‌تواند مدیر بسازد؛ هر مدیر می‌تواند سازمان خودش را بسازد یا با دعوت در سازمان مدیران دیگر عضو شود. ثبت‌نام عمومی وجود ندارد و حساب‌ها فقط توسط مالک یا با پذیرش لینک دعوت ساخته می‌شوند. جزئیات در README.md و docs/security-checklist.md §۱۹.۲.

5.1.1 مالک سامانه

توانایی‌ها:

• ساخت و تنزل مدیران، انتقال مالکیت سامانه، فعال/غیرفعال‌سازی حساب‌ها.
• تعریف Providerهای AI و API keyها.
• تعریف مدل‌های مجاز و مدل‌های داخلی پنهان.
• تعریف routing policy: ارزان، سریع، دقیق، reasoning، multimodal.
• تعریف تعرفه‌ها و markup روی مصرف.
• تعریف sandbox templates.
• مشاهده کل مصرف، درآمد، خطاها، سازمان‌ها و runها.
• تعریف Agent/Employee templateهای پیش‌فرض.

5.1.2 مدیر (platform manager)

حسابی که فقط مالک سامانه می‌سازد. توانایی‌ها:

• ساخت سازمان (و مالک شدن آن) و پیوستن با دعوت به سازمان مدیران دیگر.
• دعوت اعضا.
• خرید اعتبار یا اشتراک.
• ساخت پروژه.
• فعال‌سازی کارمندهای هوش مصنوعی.
• تعریف knowledge base سازمان.
• مشاهده مصرف و خروجی کارمندها.
• تنظیم approval policy.

5.1.3 عضو سازمان

توانایی‌ها:

• chat با مدیر یا کارمندهای مجاز.
• ساخت task.
• آپلود فایل.
• مشاهده artifactها و نتیجه کار.
• اجرای app یا preview در محیط ایزوله در صورت داشتن دسترسی.

5.1.4 کارمند هوش مصنوعی

در UI مانند یک نیروی کاری نمایش داده می‌شود، اما در backend ترکیبی است از:

• role/persona
• prompt version
• tool permissions
• model routing policy
• sandbox permissions
• knowledge scope
• budget cap
• approval requirements

---

6. قابلیت‌های پیشنهادی برای افزودن

6.1 داشبورد سازمانی

• نمای سازمان‌ها و پروژه‌ها.
• وضعیت مصرف اعتبار.
• runهای فعال.
• خطاها و taskهای منتظر تأیید.
• خلاصه عملکرد کارمندها.

6.2 AI Workforce Hub

• لیست کارمندها: مدیر، برنامه‌نویس، تحلیل‌گر، بازبین، تستر، تولیدکننده محتوا، پشتیبان، محقق.
• templateهای آماده برای فعال‌سازی سریع.
• قابلیت ساخت کارمند سفارشی.
• سطح دسترسی هر کارمند به ابزارها، فایل‌ها و sandbox.

6.3 Manager Chat

• مدیر سازمان یک Agent ویژه است که کارها را triage می‌کند.
• کاربر با مدیر حرف می‌زند، نه با مدل.
• مدیر می‌تواند task بسازد، کارمند انتخاب کند، approval بگیرد و نتیجه را جمع‌بندی کند.

6.4 Workflow و Task Board

• taskها به صورت Kanban/List: New، Planning، Running، Waiting Approval، Done، Failed.
• هر task دارای run history، artifactها، cost، duration، logs و decisionهاست.
• هر run قابل replay/debug باشد.

6.5 Knowledge Base سازمانی

• upload فایل، URL، متن، repo، docs.
• tagging و scope.
• اتصال knowledge به Agentهای خاص.
• permission-aware retrieval.

6.6 Sandbox Apps

• هر سازمان/پروژه بتواند محیط اجرا داشته باشد.
• preview URL موقت برای app.
• اجرای command، تست، build، deploy preview.
• snapshot و restore.
• محدودیت CPU/RAM/disk/time/network.

6.7 Billing و Usage

• credit wallet.
• subscription plan.
• usage-based billing.
• نرخ جدا برای model calls، sandbox runtime، storage، connectors و premium employees.
• هشدار نزدیک شدن به سقف مصرف.
• invoice و payment history.

6.8 Observability

• trace هر Agent run.
• tool call timeline.
• token/cost breakdown.
• sandbox logs.
• error classification.
• quality metrics: success rate، retry rate، human intervention، average cost per task.

6.9 Governance و امنیت

• RBAC در سطح سازمان.
• approval برای عملیات خطرناک.
• audit log غیرقابل حذف.
• secret vault.
• data retention policy.
• خروجی‌های حساس با redaction.

6.10 Marketplace داخلی

• Agent templates.
• workflow templates.
• sandbox templates.
• connector templates.
• prompt packs.

---

7. پیشنهاد محیط ایزوله برای هر کاربر/سازمان

7.1 پیشنهاد نهایی

بهترین مسیر پیشنهادی:

1. برای MVP از یک abstraction به نام Sandbox Gateway استفاده شود.
2. پشت این Gateway در فاز اول از Daytona یا E2B استفاده شود، چون آماده، سریع، snapshot/persistence محور و مخصوص Agent/code execution هستند.
3. هم‌زمان interface داخلی طوری طراحی شود که بعداً بتوان backend sandbox را به Firecracker microVM یا Kubernetes self-hosted تغییر داد.
4. برای production جدی و کاهش هزینه در مقیاس، مسیر نهایی Firecracker microVM یا Kubernetes به همراه RuntimeClass/gVisor/Kata Containers بررسی شود.

7.2 چرا مستقیم روی سرور اصلی اجرا نکنیم؟

چون کاربر قرار است نرم‌افزارش را در محیط اجرا کند. این یعنی:

• امکان اجرای کد مخرب وجود دارد.
• امکان مصرف بی‌نهایت CPU/RAM/disk وجود دارد.
• امکان دسترسی به فایل‌های دیگران وجود دارد.
• امکان network abuse وجود دارد.
• امکان استخراج secretها وجود دارد.

پس اجرای مستقیم روی host اصلی ممنوع است.

7.3 سطح‌بندی isolation

سطح 1: Container ساده

مناسب فقط برای dev داخلی. برای untrusted code کافی نیست.

سطح 2: Kubernetes namespace per organization

کنترل‌ها:

• namespace جدا برای هر سازمان یا workspace.
• RBAC جدا.
• NetworkPolicy با deny-by-default.
• ResourceQuota و LimitRange.
• PodSecurity.
• Secretهای جدا.

مزیت: عملی و قابل scale.
ضعف: اگر kernel مشترک compromise شود، isolation کامل نیست.

سطح 3: Container سخت‌شده با gVisor/Kata

مزیت: امنیت بهتر از container معمولی.
ضعف: پیچیدگی عملیاتی بیشتر.

سطح 4: Firecracker microVM per run/workspace

مزیت: بهترین تعادل امنیت و سرعت برای multi-tenant untrusted workloads.
ضعف: ساخت و مدیریت infra پیچیده‌تر است.

7.4 معماری پیشنهادی Sandbox Gateway

Sandbox Gateway تنها API مجاز برای اجرای کد است:

• createWorkspace(org_id, project_id, template_id)
• startSession(workspace_id)
• runCommand(session_id, command, timeout, resources)
• readFile(session_id, path)
• writeFile(session_id, path, content)
• snapshot(session_id)
• pause(session_id)
• resume(session_id)
• destroy(session_id)
• getPreviewUrl(session_id, port)

قوانین:

• هیچ Agent مستقیمی حق دسترسی به shell host ندارد.
• هر command دارای timeout و resource limit است.
• egress network با allowlist کنترل می‌شود.
• secretها فقط از Secret Broker تزریق می‌شوند، نه env آزاد.
• هر sandbox event برای billing و audit ثبت می‌شود.

7.5 مدل ذخیره‌سازی محیط کاربر

پیشنهاد:

• source code در Git repository یا object storage versioned نگهداری شود.
• sandboxها disposable باشند.
• state مهم با snapshot/volume ذخیره شود.
• artifactها در object storage ذخیره شوند.
• database اپ مشتری، اگر لازم شد، به شکل service جدا و محدود provision شود.

---

8. پیشنهاد زبان و تکنولوژی

8.1 پاسخ کوتاه

برای نسخه جدید، «فقط Python» پیشنهاد نمی‌شود. بهترین ترکیب:

• TypeScript برای وب اپلیکیشن، UI، API layer و تجربه SaaS.
• Python برای AI runtime، Agent orchestration، evaluation، RAG و workerهای سنگین.

8.2 گزینه پیشنهادی اصلی

Frontend و BFF:

• Next.js + TypeScript
• React Server Components در صورت نیاز
• Tailwind CSS یا design system اختصاصی
• TanStack Query برای data fetching سمت client
• Zustand یا Jotai برای state سبک UI

Backend اصلی:

• Python FastAPI یا Litestar برای AI Runtime API
• PostgreSQL
• Redis برای queue/cache/rate limit
• Temporal یا Prefect برای workflowهای طولانی؛ اگر ساده‌تر بخواهیم، Celery/Dramatiq در MVP
• SQLAlchemy + Alembic یا در مسیر TypeScript، Prisma/Drizzle

AI Runtime:

• Python
• Provider adapter برای OpenAI/Anthropic/Gemini/OpenRouter/local
• LangGraph یا OpenAI Agents SDK فقط در جاهایی که ارزش افزوده واقعی دارند، نه برای قفل شدن کل معماری
• tracing داخلی مستقل از framework

Sandbox:

• فاز اول: Daytona یا E2B پشت Sandbox Gateway
• فاز بعد: Kubernetes + gVisor/Kata یا Firecracker

Billing:

• Stripe Billing برای بازار بین‌المللی
• abstraction داخلی برای payment providerهای دیگر
• usage ledger داخلی مستقل از Stripe

8.3 چرا TypeScript لازم است؟

• UI وب حرفه‌ای با Python-only سخت‌تر و کندتر توسعه می‌یابد.
• اکوسیستم SaaS dashboard، realtime، forms، tables، charts و component library در TypeScript بالغ‌تر است.
• type sharing بین API و frontend مفید است.
• استخدام/نگهداری frontend مدرن با TypeScript ساده‌تر است.

8.4 چرا Python را حذف نکنیم؟

• AI orchestration، ابزارهای LLM، RAG، data processing و sandbox clientها در Python قوی هستند.
• کد فعلی تجربه زیادی در Python دارد.
• workerهای AI بهتر است Python بمانند.

8.5 تصمیم پیشنهادی

برای شروع در پوشه web:

• apps/web: Next.js + TypeScript
• apps/api: FastAPI/Python یا NestJS/TypeScript؛ پیشنهاد من FastAPI برای نزدیکی به AI runtime است.
• packages/shared: schemaها و قراردادهای مشترک، اگر monorepo TypeScript انتخاب شود.
• services/ai-runtime: Python worker/runtime
• services/sandbox-gateway: wrapper برای Daytona/E2B/Firecracker

اگر بخواهیم پیچیدگی MVP کمتر شود:

• یک Next.js app برای UI و API routes سبک.
• یک FastAPI service برای AI runtime و sandbox orchestration.
• PostgreSQL و Redis.

---

9. Design Pattern و معماری پیشنهادی

9.1 الگوی اصلی

پیشنهاد قطعی:

• Clean Architecture
• Hexagonal Architecture / Ports and Adapters
• Domain-Driven Design برای bounded contextها
• Event-Driven Architecture برای billing، audit و observability
• Modular Monolith در فاز اول

Microservice از روز اول پیشنهاد نمی‌شود، چون محصول هنوز در حال شکل‌گیری است. اما مرزبندی‌ها باید طوری باشد که بعداً هر context قابل جدا شدن باشد.

9.2 Bounded Contextها

Identity & Access

Entityها:

• User
• Organization
• Membership
• Role
• Permission
• Invite
• Session

Billing & Usage

Entityها:

• Plan
• Subscription
• CreditWallet
• UsageEvent
• Invoice
• Payment
• RateCard

AI Control Plane

Entityها:

• Provider
• Model
• ModelCredential
• RoutingPolicy
• Capability
• CostProfile
• SafetyPolicy

Agent Workforce

Entityها:

• AgentTemplate
• Employee
• Manager
• ToolPermission
• PromptVersion
• Run
• Thread
• Task
• Artifact

Sandbox

Entityها:

• SandboxTemplate
• Workspace
• SandboxSession
• CommandRun
• Snapshot
• PreviewUrl
• ResourceLimit

Knowledge

Entityها:

• KnowledgeSource
• Document
• Chunk
• EmbeddingJob
• RetrievalPolicy
• DataPermission

Observability & Audit

Entityها:

• AuditEvent
• Trace
• Span
• ToolCall
• ErrorEvent
• QualityMetric

9.3 Ports and Adapters

نمونه portها:

• ModelProviderPort
• PaymentProviderPort
• SandboxProviderPort
• StoragePort
• EmailPort
• VectorStorePort
• NotificationPort

نمونه adapterها:

• OpenAIAdapter
• AnthropicAdapter
• GeminiAdapter
• StripeAdapter
• DaytonaSandboxAdapter
• E2BSandboxAdapter
• S3StorageAdapter
• PostgresVectorAdapter

مزیت:

• Provider عوض می‌شود، domain logic عوض نمی‌شود.
• مدل از مشتری پنهان می‌ماند.
• sandbox backend قابل تعویض است.

9.4 Design Patternهای کاربردی

Strategy Pattern

برای انتخاب مدل، Provider، pricing و execution policy.

مثال:

• FastCheapRoutingStrategy
• HighReasoningRoutingStrategy
• VisionRoutingStrategy
• FallbackRoutingStrategy

Factory Pattern

برای ساخت Agent/Employee از template.

State Machine

برای Task و Run lifecycle.

وضعیت‌های پیشنهادی Run:

• queued
• planning
• waiting_approval
• running
• tool_calling
• sandbox_running
• completed
• failed
• cancelled
• timed_out

Saga / Workflow Pattern

برای taskهای چندمرحله‌ای:

• دریافت درخواست
• تحلیل
• انتخاب کارمند
• اجرای sandbox
• تولید artifact
• محاسبه مصرف
• ثبت audit
• گرفتن approval
• تحویل خروجی

Outbox Pattern

برای اینکه usage/audit/billing eventها از بین نروند.

Repository Pattern

برای جدا کردن domain از دیتابیس.

Policy Object

برای approval، access control، budget cap، model routing و sandbox limits.

---

10. معماری سطح بالا

Browser / Web UI
    |
    | HTTPS
    v
Web App / BFF
    |
    | Authenticated API
    v
Application Services
    |-------------------------|
    |                         |
    v                         v
Domain Modules             Event Bus / Outbox
    |                         |
    v                         v
PostgreSQL               Workers
                              |
             |----------------|----------------|
             v                v                v
        AI Runtime       Sandbox Gateway    Billing Processor
             |                |                |
             v                v                v
      Model Providers   E2B/Daytona/etc.   Stripe/Payment Adapter

---

11. مدل داده اولیه

11.1 User و Organization

• users
• organizations
• memberships
• roles
• permissions
• invites

11.2 AI

• ai_providers
• ai_model_credentials
• ai_models
• routing_policies
• agent_templates
• employees
• employee_tools
• prompt_versions

11.3 Task و Run

• projects
• threads
• tasks
• runs
• run_steps
• tool_calls
• artifacts

11.4 Sandbox

• sandbox_templates
• workspaces
• sandbox_sessions
• command_runs
• snapshots
• preview_urls

11.5 Billing

• plans
• subscriptions
• credit_wallets
• usage_events
• invoices
• payments
• rate_cards

11.6 Audit و Observability

• audit_events
• traces
• spans
• error_events
• quality_metrics

---

12. تجربه کاربری پیشنهادی

12.1 صفحات اصلی

1. Landing / Login
2. Organization Switcher
3. Dashboard
4. AI Workforce
5. Manager Chat
6. Tasks
7. Projects
8. Sandbox / App Runtime
9. Knowledge Base
10. Billing
11. Settings
12. Admin Console برای مالک سامانه

12.2 اصول طراحی UI

• کاربر نباید Provider و model id ببیند.
• به جای «run model» باید ببیند «کارمند در حال انجام کار است».
• هر خروجی باید artifact واضح داشته باشد.
• cost و مصرف باید شفاف اما ساده باشد.
• کارهای خطرناک باید approval modal داشته باشند.
• dashboard باید حس کنترل و اعتماد بدهد.

12.3 تم و طراحی بصری

پیشنهاد برای UI:

• Dark-first professional dashboard.
• sidebar ثابت برای Organization، Workforce، Tasks، Projects، Billing.
• command palette برای حرکت سریع.
• کارت کارمندها با status، توانایی‌ها، مصرف امروز و taskهای فعال.
• timeline برای runها.
• split view برای chat + artifacts + logs.

---

13. مسیر توسعه پیشنهادی

فاز صفر: آماده‌سازی پوشه web

خروجی:

• ساختار monorepo.
• انتخاب stack.
• setup lint/test/typecheck.
• طراحی schema اولیه.

فاز یک: SaaS Shell

قابلیت‌ها:

• auth
• organization
• membership
• dashboard اولیه
• settings
• PostgreSQL

فاز دو: AI Control Plane

قابلیت‌ها:

• Provider مخفی برای مالک سامانه.
• Model registry.
• Routing policy.
• Agent template.
• Employee creation.

فاز سه: Manager Chat و Run Engine

قابلیت‌ها:

• chat با مدیر.
• task creation.
• run lifecycle.
• streaming response.
• artifact ساده.
• trace پایه.

فاز چهار: Sandbox Gateway

قابلیت‌ها:

• اتصال به Daytona یا E2B.
• اجرای command.
• file read/write.
• preview URL.
• snapshot.
• resource limits.

فاز پنج: Billing

قابلیت‌ها:

• usage event.
• credit wallet.
• rate card.
• invoice آماده‌سازی.
• Stripe integration یا adapter پرداخت.

فاز شش: Knowledge و Connectors

قابلیت‌ها:

• upload docs.
• vector indexing.
• permission-aware retrieval.
• اتصال GitHub/Git/GDrive در آینده.

فاز هفت: Governance و کیفیت

قابلیت‌ها:

• approvals.
• audit logs.
• human-in-the-loop.
• replay/debug.
• evaluation metrics.

---

14. پیشنهاد ساختار پوشه web

web/
  PLAN.md
  apps/
    web/
      src/
        app/
        components/
        features/
        lib/
        styles/
    api/
      app/
        main.py
        modules/
        infrastructure/
        domain/
        application/
  services/
    ai-runtime/
    sandbox-gateway/
    billing-worker/
  packages/
    contracts/
    ui/
  infra/
    docker/
    migrations/
  docs/
    architecture/
    product/

اگر بخواهیم ساده‌تر شروع کنیم:

web/
  PLAN.md
  frontend/
  backend/
  workers/
  infra/

پیشنهاد من همان ساختار apps و services است، چون برای محصول آینده تمیزتر است.

---

15. تصمیم‌های پیشنهادی اولیه

1. محصول جدید مستقل از Telegram Bot فعلی باشد.
2. هیچ فایل اصلی نسخه فعلی در runtime نسخه جدید import نشود.
3. نام مفهومی محصول: AI Workforce Platform یا Smart Organization.
4. زبان محصولی: کارمند، مدیر، سازمان، پروژه، وظیفه، خروجی؛ نه model، prompt، token برای کاربر عادی.
5. stack پیشنهادی: Next.js/TypeScript + FastAPI/Python + PostgreSQL + Redis.
6. معماری: Modular Monolith با Clean Architecture و Ports/Adapters.
7. sandbox: ابتدا Daytona/E2B پشت Sandbox Gateway؛ سپس Firecracker/Kubernetes در مقیاس بالا.
8. billing: usage ledger داخلی از روز اول، حتی اگر payment integration بعداً وصل شود.
9. observability: trace و audit از روز اول، نه بعداً.
10. UI: داشبورد dark، سریع، شفاف و سازمان‌محور.

---

16. مواردی که نباید از پروژه فعلی تکرار شوند

1. UI logic داخل handlerهای پیام.
2. stateهای حساس داخل memory process.
3. coupling به platform خارجی مثل Telegram.
4. اجرای کد کاربر روی host اصلی.
5. hardcode مدل‌ها در فایل‌های runtime.
6. migration پنهان و پراکنده داخل فایل‌های domain.
7. ترکیب auth، UI، API، engine و billing در یک فایل بزرگ.
8. وابستگی business logic به شناسه‌های تلگرام.
9. نبود ledger رسمی برای usage و billing.
10. نبود trace کامل برای تصمیم‌های Agent.

---

17. ریسک‌ها و کنترل‌ها

17.1 ریسک امنیت sandbox

کنترل:

• هیچ command بدون Sandbox Gateway اجرا نشود.
• deny-by-default network.
• secret injection محدود.
• resource quota.
• teardown خودکار.

17.2 ریسک هزینه مدل‌ها

کنترل:

• budget cap در سطح سازمان/کارمند/task.
• routing policy.
• cache و summarization.
• هشدار مصرف.

17.3 ریسک پیچیدگی معماری

کنترل:

• Modular Monolith در شروع.
• boundary واضح بین contextها.
• event bus داخلی ساده.
• microservice فقط بعد از فشار واقعی.

17.4 ریسک تجربه کاربری پیچیده

کنترل:

• کاربر عادی فقط مدیر، کارمند، task، فایل و خروجی ببیند.
• تنظیمات مدل فقط برای مالک سامانه و adminهای فنی.
• onboarding مرحله‌ای.

---

18. MVP پیشنهادی

MVP نباید همه چیز را داشته باشد. MVP مناسب:

1. ثبت‌نام و ورود.
2. ساخت سازمان.
3. خرید/افزایش اعتبار نمایشی یا واقعی.
4. داشبورد سازمان.
5. تعریف Provider مخفی توسط مالک سامانه.
6. ساخت چند کارمند آماده.
7. chat با مدیر.
8. ساخت task.
9. اجرای یک task توسط کارمند AI.
10. ثبت usage event.
11. نمایش مصرف.
12. اجرای command ساده در sandbox.
13. نمایش artifact خروجی.
14. audit log پایه.

چیزهایی که می‌توانند بعد از MVP بیایند:

• marketplace کامل.
• connectorهای زیاد.
• workflow builder تصویری.
• fine-grained data permission.
• self-host sandbox infra.
• advanced evaluation.

---

19. تعریف موفقیت نسخه اول

نسخه اول زمانی موفق است که:

1. کاربر بدون تلگرام وارد شود.
2. سازمان بسازد.
3. اعتبار/پلن داشته باشد.
4. یک مدیر AI ببیند.
5. یک task واقعی بسپارد.
6. backend بدون نمایش مدل، model routing انجام دهد.
7. task run شود و خروجی/artifact بدهد.
8. مصرف ثبت شود.
9. اگر اجرای کد لازم بود، داخل sandbox انجام شود.
10. مدیر سامانه بتواند Provider، مدل، تعرفه و مصرف کل را کنترل کند.

---

20. قدم بعدی پیشنهادی

قدم بعدی بعد از این پلن:

1. تصمیم نهایی درباره stack: Next.js + FastAPI یا Next.js + NestJS.
2. ساخت اسکلت پروژه داخل web.
3. طراحی ERD اولیه برای Organization، User، Employee، Run، Usage.
4. طراحی UI wireframe برای dashboard، workforce و manager chat.
5. پیاده‌سازی auth و organization.
6. پیاده‌سازی اولین Provider adapter و اولین Manager Agent.
7. اتصال اولین Sandbox Provider پشت Gateway.

پیشنهاد اجرایی من: از فاز SaaS Shell شروع کنیم، نه از Agent engine. اگر shell، auth، organization و data model درست ساخته شود، بقیه قابلیت‌ها تمیز روی آن سوار می‌شوند.