93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
# 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.
|