# bilkentai/bilgpt architecture

> Architecture diagram of the GitHub repository bilkentai/bilgpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bilkentai/bilgpt
- Repository: https://github.com/bilkentai/bilgpt

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Containerization"
        D("Deployment"):::deployment
    end

    subgraph "Core Application"
        A("Entry Point"):::core
        C("Configuration"):::core
    end

    subgraph "Handlers"
        H1("Admin Handler"):::handler
        H2("Message Handler"):::handler
    end

    subgraph "AI Modules"
        AI1("AI Chat Module"):::ai
        AI2("URL Analysis Module"):::ai
    end

    subgraph "System Prompts"
        P1("AI Chat Prompt"):::prompt
        P2("URL Analysis Prompt"):::prompt
    end

    subgraph "Services"
        S1("Debug Service"):::service
        S2("Group Manager"):::service
        S3("Group Storage"):::service
    end

    subgraph "Utilities"
        U1("WhatsApp Client"):::util
        U2("Health Check"):::util
    end

    subgraph "External Data"
        PS("Persistent Storage"):::storage
        CD("Critics Data"):::storage
    end

    T("Testing Suite"):::test

    %% Data Flow Connections
    D -->|"deploys"| A
    A -->|"configures"| C
    A -->|"initiates"| H1
    A -->|"initiates"| H2
    A -->|"initializes"| U1
    U1 -->|"receives"| H2
    H2 -->|"routes"| AI1
    H2 -->|"routes"| AI2
    AI1 -->|"uses"| P1
    AI2 -->|"uses"| P2
    H1 -->|"triggers"| S2
    H1 -->|"triggers"| S3
    H1 -->|"triggers"| S1
    S3 -->|"persists"| PS
    S2 -->|"updates"| PS
    AI2 -->|"saves"| CD
    U2 -->|"checks"| A
    S1 -->|"reports"| A
    T -->|"verifies"| A

    %% Styles
    classDef deployment fill:#FFCCFF,stroke:#333,stroke-width:2px;
    classDef core fill:#CCFFFF,stroke:#333,stroke-width:2px;
    classDef handler fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef ai fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef prompt fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef service fill:#CCFCEE,stroke:#333,stroke-width:2px;
    classDef util fill:#FFCCFF,stroke:#333,stroke-width:2px;
    classDef storage fill:#EFEFEF,stroke:#333,stroke-width:2px;
    classDef test fill:#FFF0B3,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/bilkentai/bilgpt/blob/main/src/index.js"
    click C "https://github.com/bilkentai/bilgpt/blob/main/src/config/env.js"
    click AI1 "https://github.com/bilkentai/bilgpt/blob/main/src/ai/chatbot.js"
    click AI2 "https://github.com/bilkentai/bilgpt/blob/main/src/ai/critic.js"
    click H1 "https://github.com/bilkentai/bilgpt/blob/main/src/handlers/adminHandler.js"
    click H2 "https://github.com/bilkentai/bilgpt/blob/main/src/handlers/messageHandler.js"
    click P1 "https://github.com/bilkentai/bilgpt/blob/main/src/prompts/ai_bot_prompt.md"
    click P2 "https://github.com/bilkentai/bilgpt/blob/main/src/prompts/critic_prompt.md"
    click S1 "https://github.com/bilkentai/bilgpt/blob/main/src/services/debugService.js"
    click S2 "https://github.com/bilkentai/bilgpt/blob/main/src/services/groupManager.js"
    click S3 "https://github.com/bilkentai/bilgpt/blob/main/src/services/groupStorage.js"
    click U1 "https://github.com/bilkentai/bilgpt/blob/main/src/utils/clientUtils.js"
    click U2 "https://github.com/bilkentai/bilgpt/blob/main/src/utils/healthCheck.js"
    click T "https://github.com/bilkentai/bilgpt/tree/main/src/tests/"
    click D "https://github.com/bilkentai/bilgpt/tree/main/Dockerfile"
```
