TorbatYar/README.md

SuperApp SaaS Platform

پلتفرم SaaS چندمستأجری (Multi-tenant)، ماژولار، API-first و microservice-ready. این مخزن شامل فاز ۱ (Core Platform) و فاز ۲ (Identity & Access + SSO) است.

برند، رنگ‌ها و تنظیمات هیچ‌کدام در کد hardcode نشده‌اند و همگی از .env / config / دیتابیس خوانده می‌شوند.

معماری در یک نگاه

• جداسازی اجباری Frontend/Backend: دو اپلیکیشن کاملاً مستقل (backend/ و frontend/).
• الگوی دیتابیس: Database-per-service. هر سرویس فقط دیتابیس خودش را می‌شناسد.
• ارتباط بین سرویس‌ها: فقط از طریق REST API، Webhook، Async Event و الگوی Outbox/Inbox.
• چندمستأجری: همه جداول بیزینسی ستون tenant_id دارند.

جزئیات کامل در پوشه docs/ موجود است:

فایل	توضیح
docs/architecture.md	معماری کلان و جداسازی Frontend/Backend
docs/database_schema.md	مدل دیتابیس Core
docs/services_contracts.md	قراردادهای ارتباطی سرویس‌ها
docs/developer_guide.md	راهنمای توسعه‌دهنده
docs/progress.md	چک‌لیست پیشرفت فازها
docs/last_step.md	آخرین وضعیت

ساختار پروژه

superapp-platform/
├── backend/
│   ├── core-service/    # FastAPI Core Platform
│   ├── shared-lib/      # کتابخانه مشترک backend
│   └── services/        # placeholder سرویس‌های آینده
├── frontend/            # Next.js (کاملاً جدا)
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── hooks/
│   ├── styles/
│   └── public/
├── docs/
├── docker-compose.yml
├── .env.example
└── README.md

راه‌اندازی سریع (Docker)

cp .env.example .env
docker compose up -d --build

سایت: http://localhost:3000

سرویس‌ها پس از بالا آمدن (یک دستور: docker compose up -d --build):

• Frontend: http://localhost:3000 (login: http://localhost:3000/login)
• Core API: http://localhost:8000 (مستندات: http://localhost:8000/docs)
• Identity API: http://localhost:8001 (SSO: http://localhost:8001/docs)
• Keycloak: http://localhost:8080 (admin/admin — کاربر نمونه: platform.admin/admin123)
• PostgreSQL: localhost:5432
• Redis: localhost:6379

Frontend داخل Docker با hot-reload اجرا می‌شود؛ دیگر نیازی به npm run dev جداگانه نیست.

راه‌اندازی محلی

Backend

cd backend/core-service
python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

Frontend

# ترجیحاً از Docker (همراه بقیه سرویس‌ها):
docker compose up -d --build

# یا اجرای مستقیم برای دیباگ UI:
cd frontend
npm install
npm run dev

Frontend: http://localhost:3000

اجرای تست‌ها (Backend)

cd backend/core-service
pytest -q

فازهای بعدی

سرویس‌های آینده در backend/services/ به‌صورت placeholder آماده‌اند. UI کامل در frontend/ توسعه می‌یابد.