# GEMINI.md - Project Context & Instructions

## Project Overview
**wajs-server** is a full-stack WhatsApp integration platform built with Bun, ElysiaJS, and React. It provides a robust API and a web-based dashboard to manage WhatsApp sessions, send/receive messages, and integrate with external systems via webhooks.

### Main Technologies
- **Runtime**: [Bun](https://bun.sh/)
- **Backend Framework**: [ElysiaJS](https://elysiajs.com/)
- **Frontend Library**: [React](https://react.dev/) with [Mantine UI](https://mantine.dev/)
- **Database ORM**: [Prisma](https://www.prisma.io/) (Targeting PostgreSQL)
- **WhatsApp Integration**: [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js)
- **State Management/Data Fetching**: [SWR](https://swr.vercel.app/)
- **Routing**: [React Router](https://reactrouter.com/)

### Architecture
- **Server Entry Point**: `src/index.tsx` - Orchestrates the ElysiaJS server and serves the React frontend.
- **WhatsApp Service**: `src/server/lib/wa/wa_service.ts` - A singleton service managing the WhatsApp client lifecycle, event handling, and webhook dispatching.
- **API Routes**: Located in `src/server/routes/`, including:
  - `wa_route.ts`: Core WhatsApp operations (send message, QR status, etc.).
  - `webhook_route.ts`: CRUD for external webhooks.
  - `auth_route.ts` & `apikey_route.ts`: Authentication and API key management.
- **Frontend**: Located in `src/pages/`, with routes defined in `src/AppRoutes.tsx`. It uses a dashboard layout (`src/pages/sq/dashboard/`).
- **Database Schema**: `prisma/schema.prisma` defines models for `User`, `ApiKey`, `WebHook`, `WaHook`, and `ChatFlows`.

---

## Building and Running

### Prerequisites
- [Bun](https://bun.sh/) installed.
- A PostgreSQL database instance.

### Setup
1. **Install dependencies**:
   ```bash
   bun install
   ```
2. **Environment Configuration**:
   Copy `.env.example` to `.env` and fill in the required variables:
   - `DATABASE_URL`: PostgreSQL connection string.
   - `JWT_SECRET`: Secret for JWT signing.
   - `PORT`: Server port (default: 3000).

3. **Database Migration**:
   ```bash
   bunx prisma migrate dev
   ```

### Development
Start the development server with hot-reloading:
```bash
bun dev
```

### Production
1. **Build the frontend**:
   ```bash
   bun build
   ```
2. **Start the server**:
   ```bash
   bun start
   ```

---

## Development Conventions

### Coding Style
- **TypeScript**: The project is strictly typed. Ensure new features are properly typed.
- **Functional Components**: React frontend uses functional components and hooks.
- **Elysia Patterns**: Use Elysia's `use()` plugin system for modular routes and middlewares.

### Key Workflows
- **WhatsApp Lifecycle**: The client uses `LocalAuth` for session persistence (stored in `.wwebjs_auth/`). In production, the client starts automatically on server boot.
- **Webhooks**: WhatsApp events are broadcast to all enabled webhooks defined in the database.
- **API Security**: Protected routes use the `apiAuth` middleware, which checks for either a valid JWT or a registered API key.

### Directory Structure
- `src/server/`: Backend logic.
- `src/pages/`: Frontend views.
- `src/components/`: Reusable React components.
- `prisma/`: Database configuration and migrations.
- `generated/prisma/`: Auto-generated Prisma client (output directory is customized in `schema.prisma`).

---

## Instructional Context for AI
- When modifying the WhatsApp logic, refer to `src/server/lib/wa/wa_service.ts`.
- When adding new API endpoints, register them in `src/index.tsx`.
- Frontend routing is managed in `src/AppRoutes.tsx`; follow the nested structure under `/sq/dashboard/` for new dashboard pages.
- Use `prisma` from `src/server/lib/prisma.ts` for database interactions.