> ## 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.

# Mahalaxmi - Local Setup

> Clone, configure, and run the platform locally

## Prerequisites

* Node.js >= 18
* npm >= 9
* Docker + Docker Compose (for local MySQL & Redis)
* Git

## Setup Steps

### 1. Clone the repo

```bash theme={null}
git clone https://github.com/prativahq/sahyogi.git
cd sahyogi
```

### 2. Install dependencies

```bash theme={null}
npm install
```

### 3. Configure environment

Copy or create a `.env` file in the project root. See [Environment Variables](/internal/mahalaxmi/env) for the full reference. At minimum you need the database, JWT secrets, and any integration keys you're working with.

```bash theme={null}
cp .env.example .env
```

### 4. Start local services

```bash theme={null}
docker-compose up mysql redis -d
```

This starts:

* **MySQL 8** on port `3306` — db: `sahyogi`, user: `dbuser`, password: `sin90is1`
* **Redis 7** on port `6380` — no auth (dev only)

### 5. Run migrations

```bash theme={null}
npm run db:push
```

To generate SQL migration files instead:

```bash theme={null}
npm run db:migrate
```

### 6. Seed the database (optional)

```bash theme={null}
npm run db:seed
```

### 7. Start the dev server

```bash theme={null}
npm run dev
```

The server runs on **[http://localhost:5001](http://localhost:5001)**. The Vite frontend is served by Express (integrated, not a separate port).

***

## Project Structure

```
sahyogi/
├── client/                     # React frontend (Vite)
│   └── src/
│       ├── pages/              # Route-level page components
│       ├── components/         # Shared UI components
│       ├── hooks/              # Custom React hooks
│       ├── lib/                # Utilities, API clients
│       ├── App.tsx             # Router + layout
│       └── main.tsx            # Entry point
│
├── server/                     # Express backend
│   ├── index.ts                # Server entry point
│   ├── routes.ts               # ALL API routes (~5300 lines)
│   ├── db.ts                   # Database connection (mysql2 pool)
│   ├── jwt-auth.ts             # JWT middleware + helpers
│   ├── storage.ts              # DB operations (queries/mutations)
│   ├── stripe.ts               # Stripe client + webhook handler
│   ├── subscription.ts         # Subscription & billing logic
│   ├── access-control.ts       # RBAC implementation
│   ├── websocket.ts            # WebSocket server
│   ├── cron.ts                 # Scheduled jobs (node-cron)
│   ├── controllers/wapp/       # WhatsApp-specific route handlers
│   ├── webhooks/               # Incoming webhook handlers
│   ├── middleware/             # RBAC middleware
│   └── utils/                  # vectorSearch, encryption, event-emitter
│
├── shared/
│   ├── schema.ts               # Drizzle schema + Zod types (source of truth)
│   ├── gupshup.ts              # Gupshup API client
│   └── wasimple.ts             # Wasimple API client
│
├── db/
│   ├── index.ts                # DB pool initialization
│   ├── seed.ts                 # Seed data
│   └── migrations/             # SQL migration files
│
├── agent/                      # Standalone AI agent process (port 5555)
├── uploads/                    # Local file upload directory
├── drizzle.config.ts           # ORM configuration
├── docker-compose.yml          # Local dev services
├── Dockerfile                  # Production Docker image
└── package.json
```

### Path aliases

| Alias      | Resolves to   |
| ---------- | ------------- |
| `@/`       | `client/src/` |
| `@shared/` | `shared/`     |
| `@db`      | `db/index.ts` |

***

## Useful Commands

```bash theme={null}
# Development
npm run dev                         # Start dev server (http://localhost:5001)
npm run check                       # TypeScript type check

# Database
npm run db:push                     # Push schema to DB (dev)
npm run db:migrate                  # Generate SQL migration files
npm run db:seed                     # Seed initial data

# Build & Production
npm run build                       # Build client + server
npm run start                       # Start production server

# Docker
docker-compose up mysql redis -d    # Start local DB + Redis
docker-compose down                 # Stop services
docker-compose down -v              # Stop + delete volumes (DELETES DATA)
docker-compose exec mysql mysql -u dbuser -psin90is1 sahyogi
docker-compose exec redis redis-cli

# One-off scripts
npx tsx server/scripts/processTrainingFiles.ts
npx tsx server/scripts/processTrainingUrls.ts
npx tsx server/scripts/createQdrantCollection.ts
npx tsx server/scripts/update-gupshup-subscription.ts
```