# cloudmaker97/discord-captcha-verification architecture

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

- Interactive diagram: https://gitdiagram.com/cloudmaker97/discord-captcha-verification
- Repository: https://github.com/cloudmaker97/discord-captcha-verification

## Overview

##### Project type and purpose
- This is a Node.js–based full-stack microservice application whose primary function is to provide Discord user verification via a Cloudflare Turnstile captcha.
- It consists of a Discord bot, a lightweight web server hosting the captcha flow, an event-driven communication layer, and a simple logging/database module.

##### File structure
- Top-level files:
- index.js – application entry point that wires up all modules
- config.example.json / .config.json – runtime configuration for Discord, HTTP server, and captcha settings
- docker-compose.yml – defines two containers (bot + web server)
- modules/discord – encapsulates Discord.js client, command/button handlers, role assignment, and log posting
- modules/website – Express (or native HTTP) server delivering static files and Turnstile form, handling form submission callbacks
- modules/events – EventEmitter instance bridging the Discord bot and web server
- modules/database – simple key-value or file-based logging (IP, timestamp)
- modules/network – blacklist management (reads/writes blacklist.txt)
- modules/…/public – static assets (HTML, JS, Tailwind CSS) for the captcha page

##### README for insights
- Workflow:
a. Bot posts an embed in a designated Discord channel with a “Verify” button
b. User clicks the button → bot issues a one-time link
c. Link opens the website hosting a Turnstile captcha form
d. Upon successful captcha, website emits a “verified” event
e. Bot listens for that event → assigns user role + posts log (IP & time) in log channel
- Dependencies: Discord.js, Cloudflare Turnstile, Express (or HTTP), Tailwind CSS
- Deployment: can run locally or via Docker Compose

##### Elements
- Blue for internal services (Bot, Web, Event Bus)
- Green for external dependencies (Discord API, Cloudflare)
- Gray for storage components (Database, Blacklist file)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Docker Compose Layer
    subgraph "Docker Compose"
        direction TB
        subgraph "Discord Bot Service"
            direction TB
            Bot["Discord Bot Service"]:::internal
        end
        subgraph "Web Server Service"
            direction TB
            Web["Web Server Service (HTTP:3000)"]:::internal
            StaticHTML["index.html"]:::internal
            StaticJS["script.js"]:::internal
            CSSInput["input.css"]:::internal
            CSSOutput["output.css"]:::internal
        end
    end

    %% Central Event Bus
    EventBus["Event Bus"]:::internal

    %% Storage Components
    Database["Database / Logs Storage"]:::storage
    BlacklistModule["Blacklist Module"]:::storage
    BlacklistFile["Blacklist File"]:::storage

    %% External Services
    DiscordAPI["Discord API"]:::external
    Cloudflare["Cloudflare Turnstile API"]:::external

    %% Repo Files
    Entry["Application Entry (index.js)"]:::config
    ConfigFile["Configuration (config.example.json)"]:::config
    ComposeFile["Docker Compose (docker-compose.yml)"]:::config
    TailwindConfig["Tailwind Config (tailwind.config.js)"]:::config

    %% Connections
    Bot -->|"posts embed & roles"| DiscordAPI
    Bot -->|"optional: store state"| Database
    Bot -->|"check/append blacklist"| BlacklistModule
    BlacklistModule -->|"reads/writes"| BlacklistFile

    Web -->|"serves captcha page"| StaticHTML
    StaticHTML -->|"loads"| StaticJS
    StaticHTML -->|"loads styles"| CSSInput
    StaticHTML --> CSSOutput

    Web -->|"verifyCaptcha() request"| Cloudflare
    Cloudflare -->|"token success/fail"| Web

    Web -->|"emit('verified',{userId,ip,timestamp})"| EventBus
    EventBus -->|"on('verified') assign role"| Bot
    EventBus -->|"log IP & timestamp"| Database

    Bot -->|"post log message"| DiscordAPI

    %% Repo connections
    Entry --> Bot
    Entry --> Web
    Entry --> EventBus
    Entry --> Database
    Entry --> BlacklistModule
    Entry --> ConfigFile
    ComposeFile --- Entry
    TailwindConfig --- StaticCSS

    %% Click Events
    click Bot "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/discord/index.js"
    click Web "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/website/index.js"
    click StaticHTML "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/website/public/index.html"
    click StaticJS "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/website/public/script.js"
    click CSSInput "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/website/public/stylesheet/input.css"
    click CSSOutput "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/website/public/stylesheet/output.css"
    click EventBus "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/events/index.js"
    click Database "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/database/index.js"
    click BlacklistModule "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/network/blacklist.js"
    click BlacklistFile "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/modules/network/blacklist.txt"
    click Entry "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/index.js"
    click ConfigFile "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/config.example.json"
    click ComposeFile "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/docker-compose.yml"
    click TailwindConfig "https://github.com/cloudmaker97/discord-captcha-verification/blob/main/tailwind.config.js"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef external fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef storage fill:#F2F3F4,stroke:#B2BABB,color:#566573
    classDef config fill:#FCF3CF,stroke:#F4D03F,color:#7D6608
```
