# ckt1031/discord-captcha-bot architecture

> Architecture diagram of the GitHub repository ckt1031/discord-captcha-bot, 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/ckt1031/discord-captcha-bot
- Repository: https://github.com/ckt1031/discord-captcha-bot

## Overview

##### Project type and purpose
- This is a backend-focused, containerized Node.js/Express web application that provides a CAPTCHA verification flow for new members of a Discord server.
- It serves static HTML pages for the user’s browser, integrates with external CAPTCHA providers (reCAPTCHA, hCaptcha, Cloudflare Turnstile), and uses the Discord API (via discord.js) to assign roles.

##### File structure
- Top level
- Dockerfile, .dockerignore, GitHub Actions workflows → container build and CI/CD
- env example, validate-env.ts → environment variable management
- package.json, tsconfig.json, eslint.config.mjs → Node.js/TypeScript build and linting
- html/ directory → static pages (captcha, success, error, verified)
- assets/ directory → static assets (CSS, images, scripts)
- src/
- index.ts → entry point, wraps server
- server.ts → Express app setup, route definitions, middleware
- validate-env.ts → loads and verifies required environment variables
- type.d.ts → shared TypeScript types
- No database; state is ephemeral. Interactions are limited to CAPTCHA provider APIs and Discord’s REST API.

##### README for additional insights
- The service exposes a /verify endpoint to present and process CAPTCHA challenges.
- On success, the bot assigns a “Verified” role and sends a DM via Discord.js.
- Docker can run the app; environment variables configure ports, credentials, callback URL.

##### Elements
- “User Browser”
- “Docker Container” with sub-components: Env Loader, Express App, Static HTML/Assets
- “CAPTCHA Provider API”
- “Discord API”
- HTTP requests/responses between Browser ↔ Express
- API calls Express → CAPTCHA Provider
- API calls Express → Discord

##### Final advice
- Every integration point (env loader, Discord role assignment, DM sending).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    Browser["User Browser"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB
        EnvLoader["Environment Loader"]:::internal
        EnvExample[".env.example"]:::internal
        Index["Application Entry Point"]:::internal
        Server["Express App & Handlers"]:::internal
        Types["Shared TypeScript Types"]:::internal
        StaticPages["Static HTML Pages"]:::internal
        Assets["Static Assets Directory"]:::internal
        DockerFile["Dockerfile"]:::internal
        DockerIgnore[".dockerignore"]:::internal
        CI["CI/CD Pipeline"]:::internal
        BuildCfg["Build & Lint Configuration"]:::internal
    end

    %% External Services
    CaptchaProv["CAPTCHA Provider APIs"]:::external
    DiscordAPI["Discord API (discord.js)"]:::external

    %% Interactions
    Browser -->|GET /verify| Server
    Server -->|serves captcha.html| StaticPages
    Browser -->|loads CAPTCHA widget| CaptchaProv
    Browser -->|POST /verify| Server
    Server -->|verify token API call| CaptchaProv
    Server -->|assign role & send DM| DiscordAPI
    Server -->|redirect success.html| StaticPages
    Server -->|redirect error.html| StaticPages
    EnvLoader -->|provides env vars| Index
    Index -->|bootstraps| Server
    Types -->|used by| Index
    Types -->|used by| Server
    BuildCfg -->|configures build| Index
    BuildCfg -->|configures lint| Index

    %% Click Events
    click EnvLoader "https://github.com/ckt1031/discord-captcha-bot/blob/main/src/validate-env.ts"
    click EnvExample "https://github.com/ckt1031/discord-captcha-bot/blob/main/.env.example"
    click Index "https://github.com/ckt1031/discord-captcha-bot/blob/main/src/index.ts"
    click Server "https://github.com/ckt1031/discord-captcha-bot/blob/main/src/server.ts"
    click Types "https://github.com/ckt1031/discord-captcha-bot/blob/main/src/type.d.ts"
    click StaticPages "https://github.com/ckt1031/discord-captcha-bot/blob/main/html/captcha.html"
    click StaticPages "https://github.com/ckt1031/discord-captcha-bot/blob/main/html/success.html"
    click StaticPages "https://github.com/ckt1031/discord-captcha-bot/blob/main/html/error.html"
    click StaticPages "https://github.com/ckt1031/discord-captcha-bot/blob/main/html/verified.html"
    click Assets "https://github.com/ckt1031/discord-captcha-bot/tree/main/assets/"
    click DockerFile "https://github.com/ckt1031/discord-captcha-bot/tree/main/Dockerfile"
    click DockerIgnore "https://github.com/ckt1031/discord-captcha-bot/blob/main/.dockerignore"
    click CI "https://github.com/ckt1031/discord-captcha-bot/blob/main/.github/workflows/docker.yml"
    click BuildCfg "https://github.com/ckt1031/discord-captcha-bot/blob/main/package.json"
    click BuildCfg "https://github.com/ckt1031/discord-captcha-bot/blob/main/tsconfig.json"
    click BuildCfg "https://github.com/ckt1031/discord-captcha-bot/blob/main/eslint.config.mjs"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#005cbf,color:#005cbf
    classDef external fill:#d4edda,stroke:#155724,color:#155724
```
