# Cetana — Backend

Django + Django REST Framework backend for the **Cetana** configurable
pistachio-processing reservation & management platform.

The single most important architectural property: the **workflow engine is
database-driven**. Processing steps, transitions, conditions, pricing rules and
notifications are configuration — never hard-coded business logic.

## Architecture

```
apps/
├── core/            # base models, error envelope, pagination
├── accounts/        # User (JWT auth), Customer profile (Odoo-keyed identity)
├── rbac/            # Role / Permission / UserRole + DRF permission classes
├── reservations/    # Slot availability, double-booking prevention
├── orders/          # ProcessingOrder + immutable snapshots + order numbers
├── workflows/       # Workflow / Version / Step / Transition + engine
├── processing/      # StepExecution state machine + rework
├── pricing/         # PricingRule + PricingEngine (backend-authoritative)
├── payments/        # Payment + gateway abstraction (idempotent)
├── invoicing/       # Invoice + Odoo sync state machine + Celery task
├── notifications/   # Templates, rules, SMS provider abstraction
├── reports/         # Dynamic report fields
├── live_monitoring/ # Cameras, streams, per-step authorization
├── audit/           # Immutable audit log
└── integrations/    # odoo/ client + services (mock-backed when unconfigured)
```

Key service/domain classes:

- `apps.workflows.engine.WorkflowEngine` — version validation, publish,
  condition evaluation, transition availability.
- `apps.pricing.engine.PricingEngine` — full price breakdown with snapshots.
- `apps.reservations.services.ReservationService` — availability + locking.
- `apps.processing.services.ProcessingService` — step state machine + rework.

## Requirements

- Python 3.11+
- PostgreSQL (optional for local dev — SQLite is used when `DATABASE_URL` is unset)

## Setup

```bash
cd cetana-backend
python -m venv .venv
# Windows: .venv\Scripts\activate   |  Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env   # then edit secrets
python manage.py migrate
python manage.py seed_demo
python manage.py runserver
```

## Environment variables

See `.env.example`. Important ones: `SECRET_KEY`, `DEBUG`, `ALLOWED_HOSTS`,
`DATABASE_URL`, `ODOO_*`, `PAYMENT_GATEWAY_*`, `SMS_PROVIDER_*`,
`CELERY_BROKER_URL`, `BASE_CURRENCY`. Secrets are never committed.

## Workers

```bash
celery -A config worker -l info
celery -A config beat -l info
```

## Tests

```bash
python manage.py test
```

## API

- Auth: `POST /api/v1/auth/login/` (JWT), `POST /api/v1/auth/refresh/`
- Workflows: `/api/v1/workflows/`, `/api/v1/workflows/versions/`,
  `/api/v1/workflows/steps/`, `/api/v1/workflows/transitions/`,
  `POST /api/v1/workflows/{id}/publish/`
- Reservations: `/api/v1/reservations/`, `/api/v1/reservations/slots/`
- OpenAPI: `/api/v1/schema/`, Swagger UI: `/api/v1/docs/`

## Docker

From the repository root:

```bash
docker compose up -d
```

## Production notes

- Use PostgreSQL (`DATABASE_URL`), set a strong `SECRET_KEY`, `DEBUG=0`,
  restrict `ALLOWED_HOSTS` and `CORS_ALLOWED_ORIGINS`.
- Run with gunicorn behind a reverse proxy; configure secure headers there.
- Keep Odoo / payment / SMS / camera credentials in environment variables.