wajs-server/GEMINI.md

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
• Backend Framework: ElysiaJS
• Frontend Library: React with Mantine UI
• Database ORM: Prisma (Targeting PostgreSQL)
• WhatsApp Integration: whatsapp-web.js
• State Management/Data Fetching: SWR
• Routing: React Router

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 installed.
• A PostgreSQL database instance.

Setup

1. Install dependencies:

   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:

   bunx prisma migrate dev
   

Development

Start the development server with hot-reloading:

bun dev

Production

1. Build the frontend:

   bun build
   

2. Start the server:

   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.