# europython/internal-bot architecture

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

- Interactive diagram: https://gitdiagram.com/europython/internal-bot
- Repository: https://github.com/europython/internal-bot

## Overview

##### Project Type and Purpose
- This repository is an internal bot designed to assist conference teams by streamlining workflows. It has multiple entry points: an HTTP endpoint (webhooks), a Discord bot for interactive communication, and a background worker for processing tasks.
- The project is a full-stack web application that uses Django for the HTTP layer, a PostgreSQL database, and discord.py for Discord integration.

##### File Structure
- Notice several top-level components:
- The “intbot” directory contains the Django project (with settings, URL configurations, WSGI/ASGI, management commands, and migrations).
- “client” holds additional scripts such as send_test_webhook.py showcasing how to interact with the bot externally.
- “deploy” includes Ansible playbooks and Docker-compose templates, indicating containerized deployment and operational management.
- Dockerfile and docker-compose.yml at the root signal usage of Docker for both development and production.
- Several directories (like “.github/workflows”) handle CI/CD through GitHub Actions.

##### README for Additional Insights
- The README clearly delineates the design decisions: one codebase supporting multiple entry points (HTTP, Discord, background worker) and emphasizes that the bot is built on Django with integrated Discord support.
- It highlights the small-scale setup, use of docker-compose, Ansible for deployment, and CI/CD pipelines using GitHub Actions.

a. Main Components:
- External Interfaces:
- HTTP Clients: Services sending webhooks.
- Discord: Users and channels interacting with the Discord bot.
- Application Layer:
- Django App: Acts as the core of the system, hosting the HTTP endpoint, background worker tasks, and managing business logic.
- Discord Bot: Implemented as a management command inside Django to work with discord.py.
- Channel Routing/Task Handling: Components inside “intbot/core/bot” and “intbot/core/tasks.py” that orchestrate message flows.
- Integrations:
- Third-party services (GitHub, Zammad) are integrated via dedicated modules in “intbot/core/integrations”.
- Data Layer:
- PostgreSQL: The central database (configured via docker-compose) that stores models, tasks, and Django’s state.
- Deployment and Infrastructure:
- Docker Containers: The Dockerfile and docker-compose.yml indicate that the whole system is containerized.
- Nginx: A reverse proxy (configured via Ansible playbooks and provided nginx.conf.j2 templates) to route HTTP requests.
- CI/CD: GitHub Actions workflows control the build and deploy pipelines.
- Ansible Scripts: Deployment automation ensured by the “deploy” folder’s playbooks and templates.

b. Relationships and Interactions:
- External webhooks and Discord messages come into the system via their respective endpoints and are directed towards the Django application.
- The Django application processes HTTP requests with its views/endpoints (as seen in “intbot/core/endpoints”).
- The background worker (triggered either via scheduled tasks or events from the Discord bot) processes jobs asynchronously, storing or retrieving data from PostgreSQL.
- The integrations modules facilitate outbound or inbound communication with external services like GitHub and Zammad.
- Containers interconnect through Docker Compose, with Nginx routing external traffic to the appropriate application ports.
- CI/CD pipelines (GitHub Actions) automatically build and deploy these containers to a dedicated VPS.

c. Architectural Patterns and Design Principles:
- Single Codebase with Multiple Entry Points: Modular design with HTTP, Discord, and background workers sharing common business logic.
- Containerization: Use of Docker and Docker Compose for encapsulation and ease of deployment.
- Infrastructure as Code: Deployment automation via Ansible playbooks.
- Dependency Management and Task Management: Handling tasks with Django’s built-in facilities and django-tasks.

d. Technologies, Frameworks, or Libraries:
- Django: Provides the HTTP server, ORM, migrations, and overall framework.
- discord.py: Powers the Discord bot functionality.
- PostgreSQL: Serves as the relational database.
- Docker & Docker Compose: Containerize and orchestrate the environment.
- Ansible: Manages server setup and deployment.
- GitHub Actions: For CI/CD pipelines.
- Additional utilities: uv for dependency management, and tools provided in Makefiles and configuration templates for deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces Layer
    subgraph "External Interfaces"
        ext_http(("HTTP Client")):::external
        ext_discord(("Discord User")):::external
        ext_client(("Client Script")):::external
    end

    %% Deployment and Infrastructure Layer
    subgraph "Deployment & Infrastructure"
        cicd["CI/CD Pipeline"]:::deployment
        ansible["Ansible Playbooks"]:::deployment
        docker["Docker Configuration"]:::deployment
        nginx["Nginx Reverse Proxy"]:::deployment
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph "Django Application"
            django["Django Project"]:::application
            endpoints["Endpoint Handlers"]:::application
            django -->|"uses"| endpoints
        end
        subgraph "Discord Bot"
            bot_cmd["Command Implementation"]:::application
            bot_core["Discord Bot Core"]:::application
            bot_cmd -->|"triggers"| bot_core
        end
        worker["Background Worker"]:::application
        integrations["Integrations"]:::application
    end

    %% Data Layer
    subgraph "Data Layer"
        db[(PostgreSQL Database)]:::db
    end

    %% Connections from External Interfaces to Deployment/Application
    ext_http -->|"routes"| nginx
    ext_client -->|"calls"| endpoints
    ext_discord -->|"interacts"| bot_core

    %% Deployment Chain
    cicd -->|"triggers"| ansible
    ansible -->|"deploysVia"| docker
    docker -->|"orchestrates"| nginx
    docker -->|"orchestrates"| django
    docker -->|"orchestrates"| worker
    docker -->|"orchestrates"| bot_core

    %% Application to Data Connections
    django -->|"readWrite"| db
    bot_core -->|"readWrite"| db
    worker -->|"readWrite"| db

    %% Internal Application Interactions
    endpoints -->|"schedules"| worker
    django -->|"uses"| integrations
    worker -->|"uses"| integrations

    %% Click Events for Component Mapping
    click django "https://github.com/europython/internal-bot/tree/main/intbot/intbot/"
    click endpoints "https://github.com/europython/internal-bot/tree/main/intbot/core/endpoints/"
    click bot_cmd "https://github.com/europython/internal-bot/blob/main/intbot/core/management/commands/run_bot.py"
    click bot_core "https://github.com/europython/internal-bot/tree/main/intbot/core/bot/"
    click worker "https://github.com/europython/internal-bot/blob/main/intbot/core/tasks.py"
    click integrations "https://github.com/europython/internal-bot/tree/main/intbot/core/integrations/"
    click ext_client "https://github.com/europython/internal-bot/blob/main/client/send_test_webhook.py"
    click docker "https://github.com/europython/internal-bot/tree/main/Dockerfile"
    click ansible "https://github.com/europython/internal-bot/tree/main/deploy/playbooks/"
    click nginx "https://github.com/europython/internal-bot/tree/main/deploy/templates/nginx/"
    click cicd "https://github.com/europython/internal-bot/blob/main/.github/workflows/build_and_deploy.yml"

    %% Styling Definitions
    classDef external fill:#ffd1dc,stroke:#ff69b4,stroke-width:2px;
    classDef application fill:#bbf,stroke:#333,stroke-width:2px;
    classDef db fill:#fc9,stroke:#b5651d,stroke-width:2px;
    classDef deployment fill:#cff,stroke:#008b8b,stroke-width:2px;
```
