# TorbatYar SuperApp SaaS Platform

پلتفرم SaaS چندمستأجری (Multi-tenant)، ماژولار، API-first و microservice-ready.

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

## Documentation (source of truth)

شروع از [`docs/README.md`](./docs/README.md).

| Document | Responsibility |
| --- | --- |
| [`docs/architecture/architecture.md`](./docs/architecture/architecture.md) | Architecture overview |
| [`docs/reference/database-schema.md`](./docs/reference/database-schema.md) | Database schema reference |
| [`docs/reference/services-contracts.md`](./docs/reference/services-contracts.md) | Service contracts |
| [`docs/development/developer-guide.md`](./docs/development/developer-guide.md) | Developer guide |
| [`docs/module-registry.md`](./docs/module-registry.md) | Module registry |
| [`docs/provider-registry.md`](./docs/provider-registry.md) | Provider registry |
| [`docs/glossary.md`](./docs/glossary.md) | Glossary |
| [`docs/progress.md`](./docs/progress.md) | Completed work |
| [`docs/next-steps.md`](./docs/next-steps.md) | Immediate next milestone |
| [`docs/roadmap.md`](./docs/roadmap.md) | Future roadmap |
| [`docs/deployment/`](./docs/deployment/) | Deployment runbooks |

## Architecture at a glance

- **Mandatory Frontend/Backend separation** — `backend/` and `frontend/` are independent apps.
- **Database-per-service** — no cross-DB queries ([ADR-001](./docs/architecture/adr/ADR-001.md)).
- **Inter-service communication** — REST, Webhook, Async Event, Outbox/Inbox only.
- **Multi-tenancy** — business tables carry `tenant_id`.

## Project structure

```
TorbatYar/
├── backend/
│   ├── core-service/       # FastAPI Core Platform
│   ├── shared-lib/         # Shared backend library
│   └── services/           # Identity (active) + future modules
├── frontend/               # Next.js
├── docs/                   # Documentation architecture (canonical)
├── infrastructure/         # Nginx, Keycloak, deploy env samples
├── scripts/                # Ops / verification scripts
├── docker-compose.yml
├── .env.example
└── README.md
```

## Quick start (Docker)

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

- **Frontend:** http://localhost:3000
- **Core API:** http://localhost:8000/docs
- **Identity API:** http://localhost:8001/docs
- **Keycloak:** http://localhost:8080

Details: [`docs/development/developer-guide.md`](./docs/development/developer-guide.md).

## Tests (Backend)

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

## Current status

See [`docs/progress.md`](./docs/progress.md). Next milestone: [`docs/next-steps.md`](./docs/next-steps.md).