# 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) موجود است:

| فایل | توضیح |
| --- | --- |
| [`docs/architecture.md`](./docs/architecture.md) | معماری کلان و جداسازی Frontend/Backend |
| [`docs/database_schema.md`](./docs/database_schema.md) | مدل دیتابیس Core |
| [`docs/services_contracts.md`](./docs/services_contracts.md) | قراردادهای ارتباطی سرویس‌ها |
| [`docs/developer_guide.md`](./docs/developer_guide.md) | راهنمای توسعه‌دهنده |
| [`docs/progress.md`](./docs/progress.md) | چک‌لیست پیشرفت فازها |
| [`docs/last_step.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)

```bash
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
```bash
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
```bash
# ترجیحاً از Docker (همراه بقیه سرویس‌ها):
docker compose up -d --build

# یا اجرای مستقیم برای دیباگ UI:
cd frontend
npm install
npm run dev
```
Frontend: http://localhost:3000

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

```bash
cd backend/core-service
pytest -q
```

## فازهای بعدی

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