# jmurrah/discord-bouncer architecture

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

- Interactive diagram: https://gitdiagram.com/jmurrah/discord-bouncer
- Repository: https://github.com/jmurrah/discord-bouncer

## Overview

##### Project Type & Purpose
- The project is a specialized Discord Bot designed for managing role assignments based on Stripe payment completion. Its primary function is to handle payment events (via Stripe) and then use Discord's API to assign appropriate roles in a Discord Server.
- From the README, note that the process involves user reactions in Discord, payment links sent by the bot via DM, receiving a Stripe “checkout.session.completed” event via a third-party service, and finally updating the Discord Guild by assigning roles.

##### Analyzing the File Structure
- The main source code resides in the “discord_bouncer” directory and includes modules for:
- Payment handling (checkout_session.py): Likely manages the Stripe checkout sessions and related webhook events.
- Database interactions (database.py): Integrates with services such as Google Firestore to store or retrieve necessary data.
- Discord API actions (discord_actions.py): Contains functions to interact with the Discord API (sending DMs, assigning roles).
- Setup and initialization (setup.py, __init__.py): Bootstraps the application, likely configuring dependencies and app-wide settings.
- The presence of a Dockerfile and pyproject.toml indicate containerization and dependency management with Poetry.
- A “tests” directory ensures that key functionalities are covered by unit tests, which is typical for maintaining code integrity.

##### Core Components
- Discord Bot Service:
- Contains the bot’s logic including listening for reaction events, sending DMs, and assigning roles.
- Payment Processing & Webhook Handler:
- Module managing the creation of Stripe checkout sessions and receiving ‘checkout.session.completed’ events.
- Database Module:
- Integrates with Google Firestore, storing payment and user state information.
- External Integration & Cloud Infrastructure:
- Stripe for payment processing.
- Google Cloud components including: Compute Instance (where the bot is deployed), Firestore (NoSQL database), Secrets Manager (for managing sensitive credentials).
- Make.com Scenarios for additional automation and continuous operation.
- Deployment & Containerization:
- Docker environment used for encapsulating the bot application.
- Testing Suite:
- Provides assurance of component functionality through unit tests.

##### Relationships & Interactions
- The Discord Bot listens for specific message reactions within a Discord Guild.
- Upon a reaction, the bot triggers a sequence where:
- A direct message is sent to the user with a Stripe checkout session link.
- Once payment is completed, Stripe (or the third-party Make.com service) sends a 'checkout.session.completed' event to the backend.
- The webhook or event handler (in checkout_session.py) processes this event, updates the database via the database module, and sends a confirmation to the Discord Bot.
- Finally, the bot uses Discord actions to assign the correct role to the user.
- These components are logically separated but interact closely through defined interfaces and data flows.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Split between distinct responsibilities (payment handling, database operations, and Discord API interactions).
- Event-Driven Architecture: Emphasized by the asynchronous trigger from Stripe to the bot upon payment completion.
- Containerization: The Dockerfile and cloud deployment suggest a microservice or container-based deployment.
- External Services Integration: Clearly delineate interactions with Stripe, Google Cloud services, and Make.com, showing dependencies and communication channels.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Core Components
    subgraph "Application Core"
        U["Discord User Reaction"]:::internal
        DB["Discord Bot Service"]:::internal
        PS["Payment Processing & Webhook Handler"]:::internal
        DI["Database Integration"]:::internal
        S["Setup"]:::internal
        I["Init"]:::internal
    end

    %% External Services
    subgraph "External Services"
        SP["Stripe Payment Gateway"]:::external
        GC["Google Cloud Infrastructure"]:::external
        MC["Make.com Automation"]:::external
    end

    %% Deployment & Other
    subgraph "Deployment & Testing"
        DC["Deployment (Docker Container)"]:::deployment
        TS["Testing Suite"]:::test
    end

    %% Data Flows
    U -->|"detectsReaction"| DB
    DB -->|"sendsDM(withPaymentLink)"| SP
    SP -->|"sendsCheckoutEvent"| PS
    MC -.->|"triggersEvent"| PS
    PS -->|"updatesState"| DI
    PS -->|"notifies(assignRole)"| DB

    %% Initialization & Deployment Dependencies
    S --> DB
    I --> DB
    S --> PS
    I --> PS
    DC --> DB
    DC --> PS
    DI --> GC
    PS --> GC

    %% Styling
    classDef internal stroke:#145A32,fill:#82E0AA,stroke-width:2px;
    classDef external stroke:#7D3C98,fill:#F9E79F,stroke-width:2px;
    classDef deployment stroke:#1B4F72,fill:#AED6F1,stroke-width:2px;
    classDef test stroke:#424949,fill:#D5D8DC,stroke-width:2px;

    %% Click Events
    click DB "https://github.com/jmurrah/discord-bouncer/blob/main/discord_bouncer/discord_actions.py"
    click PS "https://github.com/jmurrah/discord-bouncer/blob/main/discord_bouncer/checkout_session.py"
    click DI "https://github.com/jmurrah/discord-bouncer/blob/main/discord_bouncer/database.py"
    click S "https://github.com/jmurrah/discord-bouncer/blob/main/discord_bouncer/setup.py"
    click I "https://github.com/jmurrah/discord-bouncer/blob/main/discord_bouncer/__init__.py"
    click DC "https://github.com/jmurrah/discord-bouncer/tree/main/Dockerfile"
    click TS "https://github.com/jmurrah/discord-bouncer/tree/main/tests/"
```
