How bilkentai/bilgpt works
Project Type & Purpose
• BilGPT is a full-stack Node.js application designed as an intelligent WhatsApp bot.
• It provides two main AI features: natural language chat (“AI Chat”) and URL content analysis (“URL Analysis”).
• The bot interacts via the WhatsApp API (using whatsapp-web.js) and is integrated with OpenAI for generating responses and content insights.
• The project is containerized (Dockerfile, docker-compose.yml) and includes thorough configuration and testing components.
Main Components
• Core Application Startup:
• File: src/index.js
• Role: Ties together all modules, initializes the bot, and manages the main lifecycle.
• AI Modules:
• Directory: src/ai/
• Files: chatbot.js (handles conversational AI responses) and critic.js (handles URL analysis with structured criticism).
• Interaction: These modules consume system prompts provided in the src/prompts directory.
• Configuration:
• Directory: src/config/
• File: env.js
• Purpose: Centralizes environment variables and other configuration settings.
• Handlers:
• Directory: src/handlers/
• Files: adminHandler.js (manages admin commands and group controls) and messageHandler.js (processes incoming messages including both chat and URL analysis requests).
• System Prompts:
• Directory: src/prompts/
• Files: ai_bot_prompt.md (for AI chat conversations) and critic_prompt.md (for URL analysis).
• Use: They define the behavior and personality of the AI.
• Services:
• Directory: src/services/
• Files: debugService.js, groupManager.js, groupStorage.js.
• Function: Encapsulate business logic including debugging support, group management, and persistent storage management (with JSON-based storage like active-groups.json in the data directory).
• Utilities:
• Directory: src/utils/
• Files: clientUtils.js (handles WhatsApp client operations) and healthCheck.js (exposes health/status endpoints).
• Persistence & External Data:
• Data directory (data/active-groups.json) holds persistent group data.
• The critics/ folder holds saved analysis results.
• Testing:
• Directory: src/tests/
• Contains test files validating chat functionality, message order, and storage.
• Infrastructure & Deployment:
• Files: Dockerfile, docker-compose.yml, and docker-entrypoint.sh indicate containerized deployment and orchestration.
• Environment file (.env.example) provides a template for runtime configuration.
Relationships & Data Flow
• WhatsApp Input: Incoming messages are received by the WhatsApp client (handled by clientUtils).
• Message Handling: The messageHandler (in src/handlers) ingests these messages and routes them:
• To the AI chatbot module for conversational queries.
• To the critic module for URL content analysis.
• Admin Commands: Are managed by adminHandler and tied to group management logic in groupManager and storage in groupStorage.
• AI Processing: The AI modules use system prompt files from src/prompts to guide response formatting.
• Debug and Health Checks: The debugService and healthCheck utilities monitor performance and system state.
• Data Persistence: The groupStorage service, along with persistent JSON files, ensures that active group data is retained across sessions.
Architectural Patterns & Design Principles
• Modular Architecture: Clear separation of concerns (configuration, AI processing, handlers, services, and utilities).
• Microservices-like Decomposition: While contained in one codebase, different responsibilities (chat, URL analysis, admin features) are isolated in separate modules.
• Containerization: Use of Docker and docker-compose emphasizes deployment encapsulation.