# m008v/fbchat-v2 architecture

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

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

## Overview

fbchat-v2 is an async-first Python library for operating a real Facebook account through unofficial web and Messenger interfaces. The main workflow is to obtain or reuse cookies, establish a Facebook session and tokens, then invoke account, thread, or messaging operations; real-time listeners deliver events back to an asyncio application. E2EE messaging is an optional Python-to-Go bridge path. The README documents broader feature coverage than the sampled source excerpts, so unsampled capabilities are represented at their existing feature-directory paths; uncertain wiring is omitted.

Main entry points: [`src/fbchat_v2/_core/_http.py`](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_http.py) (HTTP transport), [`src/fbchat_v2/_messaging/_listening_e2ee.py`](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_listening_e2ee.py) (E2EE listener), [`src/fbchat_v2/_messaging/_listening.py`](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_listening.py) (Realtime listener), [`bridge-e2ee/bridge/client.go`](https://github.com/m008v/fbchat-v2/blob/main/bridge-e2ee/bridge/client.go) (Messenger client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Account and transport"]
  node_storage[("Cookie storage<br/>[_storage.py]")]
  node_login["Credential login<br/>[_facebookLogin.py]"]
  node_session["Session setup<br/>[_session.py]"]
  node_http["HTTP transport<br/>[_http.py]"]
  node_utils["Request utilities<br/>[_utils.py]"]
end

subgraph group_features["Facebook features"]
  node_facebook["Facebook account features"]
  node_thread["Thread administration"]
end

subgraph group_messaging["Messaging"]
  node_send["Send messages<br/>[_send.py]"]
  node_attachments["Attachment handling<br/>[_attachments.py]"]
  node_message_ops["Message operations"]
  node_listener["Realtime listener<br/>[_listening.py]"]
  node_e2ee_listener["E2EE listener<br/>[_listening_e2ee.py]"]
  node_bridge_actions["Bridge actions<br/>[_bridge_actions.py]"]
end

subgraph group_e2ee["E2EE bridge"]
  node_bridge_rpc["JSON-RPC dispatcher<br/>[main.go]"]
  node_bridge_client["Messenger client<br/>[client.go]"]
  node_device_store[("E2EE device state<br/>[client.go]")]
end

node_developer(("Library user"))
node_app(("Async application"))
node_fb(("Facebook web API"))
node_mqtt(("Messenger event service"))
node_messenger(("Messenger E2EE service"))

node_developer -->|"uses"| node_app
node_app -->|"provides credentials"| node_login
node_app -->|"configures cookies"| node_storage
node_session -->|"loads cookies"| node_storage
node_session -->|"fetches homepage"| node_http
node_http -->|"HTTP requests"| node_fb
node_app -->|"initializes session"| node_session
node_app -->|"invokes features"| node_facebook
node_app -->|"manages threads"| node_thread
node_app -->|"sends messages"| node_send
node_app -->|"uses message operations"| node_message_ops
node_facebook -->|"requests data"| node_http
node_thread -->|"requests data"| node_http
node_send -->|"posts messages"| node_http
node_attachments -->|"uploads files"| node_http
node_app -->|"starts listener"| node_listener
node_listener -->|"subscribes"| node_mqtt
node_listener -->|"dispatches events"| node_app
node_app -.->|"starts E2EE listener"| node_e2ee_listener
node_e2ee_listener -.->|"JSON-RPC stdin/stdout"| node_bridge_rpc
node_bridge_rpc -.->|"dispatches methods"| node_bridge_client
node_bridge_client -.->|"connects and exchanges E2EE"| node_messenger
node_bridge_client -.->|"reads and writes"| node_device_store
node_bridge_actions -.->|"issues bridge actions"| node_e2ee_listener
node_e2ee_listener -.->|"delivers events"| node_app

click node_storage "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_storage.py"
click node_login "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_facebookLogin.py"
click node_session "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_session.py"
click node_http "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_http.py"
click node_utils "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_utils.py"
click node_facebook "https://github.com/m008v/fbchat-v2/tree/main/src/fbchat_v2/_features/_facebook"
click node_thread "https://github.com/m008v/fbchat-v2/tree/main/src/fbchat_v2/_features/_thread"
click node_send "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_send.py"
click node_attachments "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_attachments.py"
click node_message_ops "https://github.com/m008v/fbchat-v2/tree/main/src/fbchat_v2/_messaging"
click node_listener "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_listening.py"
click node_e2ee_listener "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_listening_e2ee.py"
click node_bridge_actions "https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_bridge_actions.py"
click node_bridge_rpc "https://github.com/m008v/fbchat-v2/blob/main/bridge-e2ee/main.go"
click node_bridge_client "https://github.com/m008v/fbchat-v2/blob/main/bridge-e2ee/bridge/client.go"
click node_device_store "https://github.com/m008v/fbchat-v2/blob/main/bridge-e2ee/bridge/client.go"

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_storage,node_login,node_session,node_http,node_utils,node_developer toneBlue
class node_facebook,node_thread toneAmber
class node_send,node_attachments,node_message_ops,node_listener,node_e2ee_listener,node_bridge_actions,node_fb toneMint
class node_bridge_rpc,node_bridge_client,node_device_store toneRose
class node_app,node_mqtt,node_messenger toneIndigo
```

## Components

### Account and transport

- [Cookie storage](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_storage.py): `src/fbchat_v2/_core/_storage.py`
- [Credential login](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_facebookLogin.py): `src/fbchat_v2/_core/_facebookLogin.py`
- [Session setup](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_session.py): `src/fbchat_v2/_core/_session.py`
- [HTTP transport](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_http.py): `src/fbchat_v2/_core/_http.py`
- [Request utilities](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_core/_utils.py): `src/fbchat_v2/_core/_utils.py`

### Facebook features

- [Facebook account features](https://github.com/m008v/fbchat-v2/tree/main/src/fbchat_v2/_features/_facebook): `src/fbchat_v2/_features/_facebook`
- [Thread administration](https://github.com/m008v/fbchat-v2/tree/main/src/fbchat_v2/_features/_thread): `src/fbchat_v2/_features/_thread`

### Messaging

- [Send messages](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_send.py): `src/fbchat_v2/_messaging/_send.py`
- [Attachment handling](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_attachments.py): `src/fbchat_v2/_messaging/_attachments.py`
- [Message operations](https://github.com/m008v/fbchat-v2/tree/main/src/fbchat_v2/_messaging): `src/fbchat_v2/_messaging`
- [Realtime listener](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_listening.py): `src/fbchat_v2/_messaging/_listening.py`
- [E2EE listener](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_listening_e2ee.py): `src/fbchat_v2/_messaging/_listening_e2ee.py`
- [Bridge actions](https://github.com/m008v/fbchat-v2/blob/main/src/fbchat_v2/_messaging/_bridge_actions.py): `src/fbchat_v2/_messaging/_bridge_actions.py`

### E2EE bridge

- [JSON-RPC dispatcher](https://github.com/m008v/fbchat-v2/blob/main/bridge-e2ee/main.go): `bridge-e2ee/main.go`
- [Messenger client](https://github.com/m008v/fbchat-v2/blob/main/bridge-e2ee/bridge/client.go): `bridge-e2ee/bridge/client.go`
- [E2EE device state](https://github.com/m008v/fbchat-v2/blob/main/bridge-e2ee/bridge/client.go): `bridge-e2ee/bridge/client.go`

### Other components

- **Library user**
- **Async application**
- **Facebook web API**
- **Messenger event service**
- **Messenger E2EE service**

## Connections

- Library user → Async application: uses
- Async application → Credential login: provides credentials
- Async application → Cookie storage: configures cookies
- Session setup → Cookie storage: loads cookies
- Session setup → HTTP transport: fetches homepage
- HTTP transport → Facebook web API: HTTP requests
- Async application → Session setup: initializes session
- Async application → Facebook account features: invokes features
- Async application → Thread administration: manages threads
- Async application → Send messages: sends messages
- Async application → Message operations: uses message operations
- Facebook account features → HTTP transport: requests data
- Thread administration → HTTP transport: requests data
- Send messages → HTTP transport: posts messages
- Attachment handling → HTTP transport: uploads files
- Async application → Realtime listener: starts listener
- Realtime listener → Messenger event service: subscribes
- Realtime listener → Async application: dispatches events
- Async application → E2EE listener: starts E2EE listener
- E2EE listener → JSON-RPC dispatcher: JSON-RPC stdin/stdout
- JSON-RPC dispatcher → Messenger client: dispatches methods
- Messenger client → Messenger E2EE service: connects and exchanges E2EE
- Messenger client → E2EE device state: reads and writes
- Bridge actions → E2EE listener: issues bridge actions
- E2EE listener → Async application: delivers events