# fbchat-dev/fbchat architecture

> Architecture diagram of the GitHub repository fbchat-dev/fbchat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fbchat-dev/fbchat
- Repository: https://github.com/fbchat-dev/fbchat

## Overview

fbchat is an unofficial Python client for using a normal Facebook account with Messenger. A developer logs in to obtain a session, then uses the client or thread objects to discover conversations, retrieve or search messages, and send messages or manage conversations. Separately, the listener consumes real-time Messenger updates and parses them into typed events. The graph retains documented capabilities such as attachments, polls, and group management; their exact internal wiring is not fully visible in the sampled excerpts.

Main entry points: [`fbchat/_session.py`](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_session.py) (Session and login), [`fbchat/_client.py`](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_client.py) (Client discovery), [`fbchat/_threads/_abc.py`](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_threads/_abc.py) (Thread operations), [`fbchat/_models/_message.py`](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_models/_message.py) (Messages and replies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth_transport["Authentication and transport"]
  node_session["Session and login<br/>[_session.py]"]
  node_graphql["GraphQL operations<br/>[_graphql.py]"]
end

subgraph group_discovery["Client and discovery"]
  node_client["Client discovery<br/>[_client.py]"]
end

subgraph group_messaging["Threads and messages"]
  node_threads["Thread operations<br/>[_abc.py]"]
  node_group["Group threads<br/>[_group.py]"]
  node_user_page["User and page threads<br/>[_user.py]"]
  node_message["Messages and replies<br/>[_message.py]"]
  node_attachments["File attachments<br/>[_file.py]"]
  node_domain_models["Polls and plans"]
end

subgraph group_realtime["Real-time events"]
  node_event_listener["Event listener<br/>[_listen.py]"]
  node_event_dispatch["Event dispatch<br/>[__init__.py]"]
  node_delta_events["Delta events<br/>[_delta_class.py]"]
  node_payload_events["Payload events<br/>[_client_payload.py]"]
  node_admin_events["Admin events<br/>[_delta_type.py]"]
end

node_developer(("Python developer"))
node_facebook_http{{"Facebook web endpoints"}}
node_messenger_mqtt{{"Messenger MQTT"}}

node_developer -->|"logs in"| node_session
node_developer -->|"uses"| node_client
node_session -->|"sends HTTP requests"| node_facebook_http
node_client -->|"queries session"| node_session
node_client -->|"builds queries"| node_graphql
node_client -->|"returns threads"| node_threads
node_threads -->|"sends requests"| node_session
node_threads -->|"builds queries"| node_graphql
node_threads -->|"parses messages"| node_message
node_message -->|"parses attachments"| node_attachments
node_group -->|"manages membership"| node_session
node_group -->|"parses plans"| node_domain_models
node_user_page -->|"parses plans"| node_domain_models
node_developer -->|"listens"| node_event_listener
node_event_listener -->|"connects and subscribes"| node_messenger_mqtt
node_event_listener -->|"parses updates"| node_event_dispatch
node_event_dispatch -->|"dispatches deltas"| node_delta_events
node_event_dispatch -->|"dispatches payloads"| node_payload_events
node_delta_events -->|"parses admin deltas"| node_admin_events
node_delta_events -->|"builds message events"| node_message
node_payload_events -->|"builds message events"| node_message

click node_session "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_session.py"
click node_graphql "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_graphql.py"
click node_client "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_client.py"
click node_threads "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_threads/_abc.py"
click node_group "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_threads/_group.py"
click node_user_page "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_threads/_user.py"
click node_message "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_models/_message.py"
click node_attachments "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_models/_file.py"
click node_event_listener "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_listen.py"
click node_event_dispatch "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/__init__.py"
click node_delta_events "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/_delta_class.py"
click node_payload_events "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/_client_payload.py"
click node_admin_events "https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/_delta_type.py"
click node_domain_models "https://github.com/fbchat-dev/fbchat/tree/master/fbchat/_models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session,node_graphql toneBlue
class node_client toneAmber
class node_threads,node_group,node_user_page,node_message,node_attachments,node_domain_models toneMint
class node_event_listener,node_event_dispatch,node_delta_events,node_payload_events,node_admin_events toneRose
class node_developer,node_facebook_http,node_messenger_mqtt toneIndigo
```

## Components

### Authentication and transport

- [Session and login](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_session.py): `fbchat/_session.py`
- [GraphQL operations](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_graphql.py): `fbchat/_graphql.py`

### Client and discovery

- [Client discovery](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_client.py): `fbchat/_client.py`

### Threads and messages

- [Thread operations](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_threads/_abc.py): `fbchat/_threads/_abc.py`
- [Group threads](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_threads/_group.py): `fbchat/_threads/_group.py`
- [User and page threads](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_threads/_user.py): `fbchat/_threads/_user.py`
- [Messages and replies](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_models/_message.py): `fbchat/_models/_message.py`
- [File attachments](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_models/_file.py): `fbchat/_models/_file.py`
- [Polls and plans](https://github.com/fbchat-dev/fbchat/tree/master/fbchat/_models): `fbchat/_models`

### Real-time events

- [Event listener](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_listen.py): `fbchat/_listen.py`
- [Event dispatch](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/__init__.py): `fbchat/_events/__init__.py`
- [Delta events](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/_delta_class.py): `fbchat/_events/_delta_class.py`
- [Payload events](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/_client_payload.py): `fbchat/_events/_client_payload.py`
- [Admin events](https://github.com/fbchat-dev/fbchat/blob/master/fbchat/_events/_delta_type.py): `fbchat/_events/_delta_type.py`

### Other components

- **Python developer**
- **Facebook web endpoints**
- **Messenger MQTT**

## Connections

- Python developer → Session and login: logs in
- Python developer → Client discovery: uses
- Session and login → Facebook web endpoints: sends HTTP requests
- Client discovery → Session and login: queries session
- Client discovery → GraphQL operations: builds queries
- Client discovery → Thread operations: returns threads
- Thread operations → Session and login: sends requests
- Thread operations → GraphQL operations: builds queries
- Thread operations → Messages and replies: parses messages
- Messages and replies → File attachments: parses attachments
- Group threads → Session and login: manages membership
- Group threads → Polls and plans: parses plans
- User and page threads → Polls and plans: parses plans
- Python developer → Event listener: listens
- Event listener → Messenger MQTT: connects and subscribes
- Event listener → Event dispatch: parses updates
- Event dispatch → Delta events: dispatches deltas
- Event dispatch → Payload events: dispatches payloads
- Delta events → Admin events: parses admin deltas
- Delta events → Messages and replies: builds message events
- Payload events → Messages and replies: builds message events