> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Heena - Local Setup

> Get Heena Jewellers running locally

## Tech Stack

### Backend

| Package         | Version | Purpose                 |
| --------------- | ------- | ----------------------- |
| Python          | ≥ 3.12  | Language                |
| FastAPI         | ≥ 0.121 | Web framework           |
| SQLAlchemy      | ≥ 2.0   | ORM                     |
| Alembic         | ≥ 1.17  | Database migrations     |
| psycopg2-binary | ≥ 2.9   | PostgreSQL driver       |
| OpenAI SDK      | ≥ 2.7   | AI order parsing        |
| reportlab       | ≥ 4.0   | PDF generation          |
| pdf2image       | ≥ 1.17  | PDF to image conversion |
| Poetry          | —       | Dependency management   |

### Frontend

| Package          | Version | Purpose             |
| ---------------- | ------- | ------------------- |
| React            | 19.2.0  | UI framework        |
| TypeScript       | 5.9.3   | Type safety         |
| Vite             | 7.2.2   | Build tool          |
| Tailwind CSS     | 4.1.17  | Styling             |
| React Router DOM | 7.9.5   | Client-side routing |
| Zustand          | 5.0.8   | State management    |
| Axios            | 1.13.2  | HTTP client         |
| Lucide React     | 0.553.0 | Icons               |

***

## Environment Setup

### Backend — `backend/.env`

```env theme={null}
# PostgreSQL
DATABASE_URL=postgresql://postgres:PASSWORD@localhost:5432/sahyogi

# OpenAI (for WhatsApp order parsing)
OPENAI_API_KEY=sk-proj-...

# Gupshup WhatsApp
GUPSHUP_HEENA_ORDER_PLACEMENT_SUB_TAG=sahyogi_jewellers_order_hook
GUPSHUP_PARTNER_EMAIL=your-email@example.com
GUPSHUP_PARTNER_PASSWORD=your-password
GUPSHUP_APP_ID=your-gupshup-app-id

# URLs
PUBLIC_API_URL=http://localhost:8000
FRONTEND_URL=http://localhost:3000

# Allowed WhatsApp numbers (comma-separated, with country code)
ALLOWED_PHONE_NUMBERS=917595903437,918902673788
```

### Frontend — `.env`

```env theme={null}
VITE_API_BASE_URL=http://localhost:8000
```

If not set, the Axios instance defaults to `http://localhost:8000`.

***

## Running the App

### Backend

```bash theme={null}
cd backend

# Install dependencies
poetry install

# Create the database
psql -U postgres -c "CREATE DATABASE sahyogi;"

# Apply migrations
alembic upgrade head

# Start dev server
poetry run uvicorn sj.app:app --reload --host 0.0.0.0 --port 8000
```

<Check>
  API available at **[http://localhost:8000](http://localhost:8000)**
  Swagger UI at **[http://localhost:8000/docs](http://localhost:8000/docs)**
</Check>

### Frontend

```bash theme={null}
cd frontend

npm install
npm run dev
```

<Check>
  Frontend available at **[http://localhost:5173](http://localhost:5173)**
</Check>

***

## Running Tests

```bash theme={null}
cd backend

# Run all tests
poetry run pytest

# Run a specific file
poetry run pytest tests/test_karigar_routes.py

# Verbose output
poetry run pytest -v
```

**Test files:**

* `test_bank_routes.py`
* `test_bullion_routes.py`
* `test_client_routes.py`
* `test_karigar_routes.py`
* `test_polisher_routes.py`
* `test_client_order_routes.py`
* `test_calculations.py`
* `test_services.py`