# fbsamples/messenger-bot-samples architecture

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

- Interactive diagram: https://gitdiagram.com/fbsamples/messenger-bot-samples
- Repository: https://github.com/fbsamples/messenger-bot-samples

## Overview

##### Project Type and Purpose
- This is a catalog of standalone Messenger‐Platform bot samples (account-linking, chat-extensions, chat_plugin_autodetect, customer-care-csat, gui-webview).
- Each sample is a Node.js/Express microservice demonstrating best practices (webhooks, API helpers, optional DB, optional client UI, real-time sockets, webview, etc.).

##### File Structure
- Top-level: multiple directories, one per sample.
- Each sample has:
– an Express entry point (app.js or index.js + bin/www)
– routes (webhooks, index, resource-specific)
– messenger-api-helpers (send/receive, thread setup)
– models and optional stores (data access, e.g. Knex migrations/seeds for chat-extensions)
– public assets or client folder (React components for gui-webview, static CSS/images)
– views (Jade/EJS templates for account linking or webview fallbacks)
– test folders, config files, build scripts (webpack in gui-webview).

##### README
- Describes: “Example bots to demonstrate best practices for the Messenger Platform.”
- No single unified architecture—rather, a family of patterns.

##### Main Components (per sample)
a. HTTP Server (Express)
b. Messenger-API-Helpers module (wraps Graph API calls)
c. Webhook Controller (routes/webhooks.js): receives events from Facebook
d. Business Logic (models, stores, FBA logic in customer-care-csat)
e. Persistent Storage (in chat-extensions: Knex + migrations/seeds; other samples may use in-memory stores)
f. Frontend/UI (views for webviews, static public files, React SPA in gui-webview)
g. Real-Time Layer (chat-extensions sockets using socket.io)
h. External Service: Facebook Messenger Platform (Graph API, Webhook callbacks)

##### Relationships & Data Flow
1. User interacts in Messenger → Facebook Messenger Platform
2. Platform POSTs webhook to your Express Webhook endpoint
3. Webhook Controller invokes business logic (models/stores)
4. Business logic may read/write to DB or in-memory store
5. Business logic calls Messenger-API-Helpers → Facebook Graph API → back to user
6. For samples with a client (gui-webview):
- User taps webview link in Messenger → loads React app from Express static public folder
- Client may make REST calls or rely on postMessage / webview controls via messenger-api-helpers
7. For chat-extensions real-time: server also maintains WebSocket channel to push updates to client

##### Architectural Patterns & Principles
- MVC-style separation: routes/controllers → models/stores → views/UI
- Layered approach:
– Transport layer (Express HTTP, WebSockets)
– Business layer (models, stores, FBA payload logic)
– Integration layer (Messenger-API-Helpers)
- Optional data persistence: relational via Knex or simple in-memory store
- Client-Server SPA in gui-webview: webpack bundle, React components
- Configuration via environment or sample.config.js

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    FB["Facebook Messenger Platform"]:::external

    %% Account-Linking Sample
    subgraph "Account-Linking Sample"
        direction TB
        AL_Server["Express Server (app.js)"]:::transport
        AL_Webhook["Webhook Controller"]:::transport
        AL_Biz["Business Logic (models & stores)"]:::business
        AL_Integration["Messenger-API-Helpers"]:::integration
        AL_Data["In-Memory Store"]:::data
        AL_UI["Frontend/UI (public & views)"]:::frontend

        AL_Server -->|“POST /webhook”| AL_Webhook
        AL_Webhook -->|invokes| AL_Biz
        AL_Biz -->|reads/writes| AL_Data
        AL_Biz -->|calls| AL_Integration
        AL_Integration -->|Graph API calls| FB
        AL_Server -->|serves| AL_UI
    end

    %% Chat-Extensions Sample
    subgraph "Chat-Extensions Sample"
        direction TB
        CE_Server["Express Server (app.js & bin/www)"]:::transport
        CE_Webhook["Webhook Controller"]:::transport
        CE_Biz["Business Logic (models)"]:::business
        CE_Data["Knex DB"]:::data
        CE_Integration["Messenger-API-Helpers"]:::integration
        CE_WS["WebSocket Layer"]:::transport
        CE_UI["Client React & Views"]:::frontend

        CE_Server -->|“POST /webhook”| CE_Webhook
        CE_Webhook -->|invokes| CE_Biz
        CE_Biz -->|reads/writes| CE_Data
        CE_Biz -->|calls| CE_Integration
        CE_Integration -->|Graph API calls| FB
        CE_Server -->|serves| CE_UI
        CE_WS <-->|real-time updates| CE_UI
        CE_Biz -->|emits| CE_WS
    end

    %% Chat-Plugin-Autodetect Sample
    subgraph "Chat-Plugin-Autodetect Sample"
        direction TB
        CP_Server["Express Server (app.js)"]:::transport
        CP_Router["Routing Layer"]:::transport
        CP_UI["Static UI & Views"]:::frontend

        FB -->|loads plugin| CP_Server
        CP_Server -->|routes| CP_Router
        CP_Router -->|serves| CP_UI
    end

    %% Customer-Care-CSAT Sample
    subgraph "Customer-Care-CSAT Sample"
        direction TB
        CC_Server["Express Server (index.js)"]:::transport
        CC_Biz["Business Logic (bot & payloads)"]:::business
        CC_Integration["Messenger-API-Helpers"]:::integration
        CC_Config["Config (sample.config.js)"]:::data

        FB -->|“POST /webhook”| CC_Server
        CC_Server -->|invokes| CC_Biz
        CC_Biz -->|uses| CC_Config
        CC_Biz -->|calls| CC_Integration
        CC_Integration -->|Graph API calls| FB
    end

    %% GUI-Webview Sample
    subgraph "GUI-Webview Sample"
        direction TB
        GUI_Server["Express Server (app.js & bin/www)"]:::transport
        GUI_Webhook["Webhook Controller"]:::transport
        GUI_Biz["Business Logic (models & stores)"]:::business
        GUI_Integration["Messenger-API-Helpers"]:::integration
        GUI_UI["React SPA & Views"]:::frontend
        GUI_Data["Stores (data)"]:::data
        GUI_Util["Utils & Build Config"]:::data

        FB -->|“POST /webhook”| GUI_Server
        GUI_Server -->|routes| GUI_Webhook
        GUI_Webhook -->|invokes| GUI_Biz
        GUI_Biz -->|reads/writes| GUI_Data
        GUI_Biz -->|calls| GUI_Integration
        GUI_Integration -->|Graph API calls| FB
        GUI_Server -->|serves| GUI_UI
        GUI_Util -.-> GUI_UI

    end

    %% Click Events Account-Linking
    click AL_Server "https://github.com/fbsamples/messenger-bot-samples/blob/master/account-linking/app.js"
    click AL_Webhook "https://github.com/fbsamples/messenger-bot-samples/blob/master/account-linking/routes/webhooks.js"
    click AL_Integration "https://github.com/fbsamples/messenger-bot-samples/tree/master/account-linking/messenger-api-helpers/"
    click AL_Biz "https://github.com/fbsamples/messenger-bot-samples/blob/master/account-linking/models/user.js"
    click AL_Data "https://github.com/fbsamples/messenger-bot-samples/blob/master/account-linking/stores/store.js"
    click AL_UI "https://github.com/fbsamples/messenger-bot-samples/tree/master/account-linking/public/"
    click AL_UI "https://github.com/fbsamples/messenger-bot-samples/tree/master/account-linking/views/"

    %% Click Events Chat-Extensions
    click CE_Server "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/app.js"
    click CE_Server "https://github.com/fbsamples/messenger-bot-samples/tree/master/chat-extensions/bin/www"
    click CE_Webhook "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/routes/webhooks.js"
    click CE_Integration "https://github.com/fbsamples/messenger-bot-samples/tree/master/chat-extensions/messenger-api-helpers/"
    click CE_Data "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/db/knex.js"
    click CE_Server "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/knexfile.js"
    click CE_WS "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/sockets/index.js"
    click CE_UI "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/client/index.js"
    click CE_UI "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/public/style.css"
    click CE_UI "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat-extensions/views/index.ejs"

    %% Click Events Chat-Plugin-Autodetect
    click CP_Server "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat_plugin_autodetect/app.js"
    click CP_Router "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat_plugin_autodetect/router.js"
    click CP_UI "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat_plugin_autodetect/public/style.css"
    click CP_UI "https://github.com/fbsamples/messenger-bot-samples/blob/master/chat_plugin_autodetect/views/index.ejs"

    %% Click Events Customer-Care-CSAT
    click CC_Server "https://github.com/fbsamples/messenger-bot-samples/blob/master/customer-care-csat/index.js"
    click CC_Biz "https://github.com/fbsamples/messenger-bot-samples/blob/master/customer-care-csat/app/bot.js"
    click CC_Config "https://github.com/fbsamples/messenger-bot-samples/blob/master/customer-care-csat/config/sample.config.js"

    %% Click Events GUI-Webview
    click GUI_Server "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/app.js"
    click GUI_Server "https://github.com/fbsamples/messenger-bot-samples/tree/master/gui-webview/bin/www"
    click GUI_Webhook "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/routes/webhooks.js"
    click GUI_Integration "https://github.com/fbsamples/messenger-bot-samples/tree/master/gui-webview/messenger-api-helpers/"
    click GUI_Biz "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/models/user.js"
    click GUI_Data "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/stores/store.js"
    click GUI_UI "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/client/index.js"
    click GUI_UI "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/public/bundle.js"
    click GUI_Util "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/utils/date-string-format.js"
    click GUI_Util "https://github.com/fbsamples/messenger-bot-samples/blob/master/gui-webview/webpack.config.js"

    %% Styles
    classDef transport fill:#cce5ff,stroke:#0066cc,color:#000;
    classDef business fill:#d4edda,stroke:#28a745,color:#000;
    classDef integration fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef data fill:#fff3cd,stroke:#ffcd39,color:#000;
    classDef frontend fill:#e2d4f0,stroke:#800080,color:#000;
    classDef external fill:#f0f0f0,stroke:#999,color:#000;
```
