# Desi Clans

Premium Bengaluru-based platform for **Indian cultural events**—Holi, Garba, Dandiya, and related celebrations.

---

## Stack

| Layer | Technologies |
|-------|----------------|
| Frontend | React (JSX), Vite, Tailwind CSS 3, React Router, Axios, GSAP, Lucide React |
| Backend | FastAPI, Python, SQLAlchemy, Pydantic, Alembic, JWT, PostgreSQL |

---

## Repository structure

```
DESI-CLANS/
├── frontend/          # Vite + React foundation
├── backend/           # FastAPI foundation (+ routers for next phase)
├── docs/              # PRD, architecture, API, database, design system
├── scripts/           # Dev helpers (PowerShell + shell)
├── docker-compose.yml # Local PostgreSQL
└── README.md
```

---

## Quick start

### 1. Database

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

Default URL matches `backend/.env.example`:

`postgresql://desiclans:desiclans_dev@localhost:5432/desiclans`

### 2. Backend

```bash
cd backend
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS/Linux
pip install -r requirements.txt
cp .env.example .env            # if .env does not exist
python scripts/migrate.py       # optional until business routers are enabled
uvicorn app.main:app --reload --port 8000
```

Or from repo root (Windows): `.\scripts\dev-backend.ps1`

Health check: `http://localhost:8000/api/health`

### 3. Frontend

```bash
cd frontend
npm install
cp .env.example .env
npm run dev
```

Or: `.\scripts\dev-frontend.ps1`

App: `http://localhost:5173` (proxies `/api` to the backend in dev)

---

## Documentation

| Doc | Purpose |
|-----|---------|
| [docs/PRD.md](./docs/PRD.md) | Product scope |
| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | System design & phases |
| [docs/DESIGN_SYSTEM.md](./docs/DESIGN_SYSTEM.md) | UI tokens & components |
| [docs/API_SPEC.md](./docs/API_SPEC.md) | REST API |
| [docs/DATABASE.md](./docs/DATABASE.md) | Schema |
| [docs/PROGRESS.md](./docs/PROGRESS.md) | Implementation status |

---

## Implementation status

**Phase 1 foundation** (current): project scaffolding, env templates, dev scripts, health endpoint, frontend shell—**no business features wired yet**.

See [docs/PROGRESS.md](./docs/PROGRESS.md) for the checklist.