# fbsamples/messenger-platform-samples architecture

> Architecture diagram of the GitHub repository fbsamples/messenger-platform-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-platform-samples
- Repository: https://github.com/fbsamples/messenger-platform-samples

## Overview

##### Project type and purpose
- This is an open-source “Knowledge Bank” of sample Messenger Platform applications. Each top-level folder (e.g. `quick-start`, `handover_protocol`, `inter-page`, `messenger-api`, `node`, `webview`) is a self-contained sample illustrating Messenger webhook handling, API calls, handover protocols, inter-bot thread control, or webview integration.

##### File structure
- Top-level sample directories correspond to independent micro-services/bots:
- `quick-start` – a minimal Node.js Express bot
- `node` – a more advanced Node.js sample with views, static assets
- `handover_protocol` – two‐app handover‐protocol demo with utilities (`utils/api.js`, `utils/handover-protocol.js`, `utils/quick-reply.js`)
- `inter-page` – two bots (marketing & support) showing thread control, each in its own dir
- `messenger-api` – language‐specific “Knowledge Bank” demos (Python Flask, Node.js JS/TS, Java)
- `webview` – Express server serving a Webview HTML page
- Shared configuration & scripts: `package.json` in each, `.env` or `config/default.json` for credentials, `README.md` in each illustrating setup.
- CI/CD: GitHub Actions workflow (`.github/workflows/postman-sync.yaml`), Postman collections in `/postman`.

##### README for additional insights
- It describes this repo as “sample applications to learn building on the Messenger Platform.”
- The “Knowledge Bank: Messenger API” section lists the `messenger-api` subdirectories as code snippets for Python, Node.js, and Java integrations.
- No central database—these are stateless webhook services invoking Messenger Graph API.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User and Platform
    User[/"User"/]:::external
    MessengerPlatform(("Facebook Messenger Platform")):::external
    Postman[/"Postman Collections"/]:::postman

    User -->|"Sends Message"| MessengerPlatform
    Postman -->|"Simulates Webhook/API"| MessengerPlatform

    %% Quick-start Service
    subgraph "Quick-start Express Service" 
        QSApp["Express Bot /quick-start/app.js"]:::node
        QSPkg["package.json"]:::util
    end
    MessengerPlatform -->|"/webhook"| QSApp
    QSApp -->|"Calls Graph API"| MessengerPlatform
    click QSApp "https://github.com/fbsamples/messenger-platform-samples/blob/main/quick-start/app.js"
    click QSPkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/quick-start/package.json"

    %% Node.js Sample Service
    subgraph "Node.js Sample Service" 
        NodeApp["Express Bot /node/app.js"]:::node
        NodeConfig["config/default.json"]:::util
        NodeView["authorize.ejs"]:::util
        NodeAssets["public/ (assets & index.html)"]:::util
        NodePkg["package.json"]:::util
    end
    MessengerPlatform -->|"/webhook"| NodeApp
    NodeApp -->|"Calls Graph API"| MessengerPlatform
    click NodeApp "https://github.com/fbsamples/messenger-platform-samples/blob/main/node/app.js"
    click NodeConfig "https://github.com/fbsamples/messenger-platform-samples/blob/main/node/config/default.json"
    click NodeView "https://github.com/fbsamples/messenger-platform-samples/blob/main/node/views/authorize.ejs"
    click NodeAssets "https://github.com/fbsamples/messenger-platform-samples/tree/main/node/public/"
    click NodePkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/node/package.json"

    %% Handover Protocol Demo
    subgraph "Handover Protocol Demo"
        HPApp["Bot App /handover_protocol/index.js"]:::node
        HPPkg["package.json"]:::util
        subgraph "Utils"
            APIUtil["api.js"]:::util
            HPUtil["handover-protocol.js"]:::util
            QRUtil["quick-reply.js"]:::util
        end
    end
    MessengerPlatform -->|"/webhook"| HPApp
    HPApp -->|"Uses Utilities"| APIUtil
    HPApp -->|"Uses Utilities"| HPUtil
    HPApp -->|"Uses Utilities"| QRUtil
    HPApp -->|"Graph API: Handover"| MessengerPlatform
    click HPApp "https://github.com/fbsamples/messenger-platform-samples/blob/main/handover_protocol/index.js"
    click HPPkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/handover_protocol/package.json"
    click APIUtil "https://github.com/fbsamples/messenger-platform-samples/blob/main/handover_protocol/utils/api.js"
    click HPUtil "https://github.com/fbsamples/messenger-platform-samples/blob/main/handover_protocol/utils/handover-protocol.js"
    click QRUtil "https://github.com/fbsamples/messenger-platform-samples/blob/main/handover_protocol/utils/quick-reply.js"

    %% Inter-page Bots
    subgraph "Inter-page Bots"
        subgraph Marketing
            MApp["marketing-bot/app.js"]:::node
            MPkg["package.json"]:::util
        end
        subgraph Support
            SApp["support-bot/app.js"]:::node
            SPkg["package.json"]:::util
        end
    end
    MessengerPlatform -->|"/webhook"| MApp
    MessengerPlatform -->|"/webhook"| SApp
    MApp -->|"Thread Control Handover"| SApp
    MApp -->|"Calls Graph API"| MessengerPlatform
    SApp -->|"Calls Graph API"| MessengerPlatform
    click MApp "https://github.com/fbsamples/messenger-platform-samples/blob/main/inter-page/marketing-bot/app.js"
    click MPkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/inter-page/marketing-bot/package.json"
    click SApp "https://github.com/fbsamples/messenger-platform-samples/blob/main/inter-page/support-bot/app.js"
    click SPkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/inter-page/support-bot/package.json"

    %% Messenger-API Demos
    subgraph "Messenger-API Demos"
        %% Python
        subgraph "Python Flask Demo" 
            PyApp["app.py"]:::python
            PyLib["messenger_platform.py"]:::python
        end
        %% Node.js JS
        subgraph "Node.js JavaScript Version"
            JSIndex["index.js"]:::node
            JSLib["messenger.js"]:::node
            JSPkg["package.json"]:::util
        end
        %% Node.js TS
        subgraph "Node.js TypeScript Version"
            TSIndex["index.ts"]:::node
            TSLib["messenger.ts"]:::node
            TSConfig["tsconfig.json"]:::util
            TSPkg["package.json"]:::util
        end
        %% Java
        subgraph "Java Service"
            JavaMain["Main.java"]:::java
            JavaSend["MessageSender.java"]:::java
            JavaPom["pom.xml"]:::util
        end
    end
    MessengerPlatform -->|"/webhook"| PyApp
    MessengerPlatform -->|"/webhook"| JSIndex
    MessengerPlatform -->|"/webhook"| TSIndex
    MessengerPlatform -->|"/webhook"| JavaMain
    PyApp -->|"Calls Graph API"| MessengerPlatform
    JSIndex -->|"Calls Graph API"| MessengerPlatform
    TSIndex -->|"Calls Graph API"| MessengerPlatform
    JavaMain -->|"Calls Graph API"| MessengerPlatform
    click PyApp "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-and-webhooks/app.py"
    click PyLib "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-python/messenger_platform.py"
    click JSIndex "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-nodejs/javascript-version/index.js"
    click JSLib "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-nodejs/javascript-version/messenger.js"
    click JSPkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-nodejs/javascript-version/package.json"
    click TSIndex "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-nodejs/typescript-version/src/index.ts"
    click TSLib "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-nodejs/typescript-version/src/messenger.ts"
    click TSConfig "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-nodejs/typescript-version/tsconfig.json"
    click TSPkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-nodejs/typescript-version/package.json"
    click JavaMain "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-java/src/main/java/org/example/Main.java"
    click JavaSend "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-java/src/main/java/org/example/MessageSender.java"
    click JavaPom "https://github.com/fbsamples/messenger-platform-samples/blob/main/messenger-api/messenger-api-with-java/pom.xml"

    %% Webview Host Service
    subgraph "Webview Host Service"
        WVApp["app.js"]:::node
        WVPkg["package.json"]:::util
        WVDotEnv[".env"]:::util
        WVPage["options.html"]:::util
    end
    MessengerPlatform -->|"/webview"| WVApp
    WVApp -->|"Serves Page"| WVPage
    click WVApp "https://github.com/fbsamples/messenger-platform-samples/blob/main/webview/app.js"
    click WVPkg "https://github.com/fbsamples/messenger-platform-samples/blob/main/webview/package.json"
    click WVDotEnv "https://github.com/fbsamples/messenger-platform-samples/blob/main/webview/.env"
    click WVPage "https://github.com/fbsamples/messenger-platform-samples/blob/main/webview/public/options.html"

    %% CI/CD & API Testing
    subgraph "CI/CD & API Testing"
        GHAction["postman-sync.yaml"]:::util
        PM1["messenger-platform-api.postman_collection.json"]:::postman
        PM2["instagram-platform-api.postman_collection.json"]:::postman
    end
    GHAction -->|"Triggers Sync"| PM1
    GHAction -->|"Triggers Sync"| PM2
    click GHAction "https://github.com/fbsamples/messenger-platform-samples/blob/main/.github/workflows/postman-sync.yaml"
    click PM1 "https://github.com/fbsamples/messenger-platform-samples/blob/main/postman/messenger-platform-api.postman_collection.json"
    click PM2 "https://github.com/fbsamples/messenger-platform-samples/blob/main/postman/instagram-platform-api.postman_collection.json"

    %% Styles
    classDef node fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
    classDef python fill:#aed6f1,stroke:#2e86c1,stroke-width:2px
    classDef java fill:#f5b7b1,stroke:#c0392b,stroke-width:2px
    classDef util fill:#d5d8dc,stroke:#7f8c8d,stroke-width:1px
    classDef external fill:#f4f6f7,stroke:#95a5a6,stroke-width:1px
    classDef postman fill:#f9e79f,stroke:#b7950b,stroke-width:1px
```
