# Architecture — @dongdev/fca-unofficial (4.x)

This document describes the internal architecture of the library. The overarching goal is to **separate session management, HTTP transport, and MQTT realtime** from **business-logic domains**, while preserving full **backward compatibility** with the flat FCA API and offering a **modern event-driven bot** interface on top.

---

## Table of Contents

1. [Design Principles](#design-principles)
2. [Bootstrap Flow](#bootstrap-flow)
3. [Source Tree](#source-tree)
4. [Layer Diagram](#layer-diagram)
5. [Core Layer](#core-layer)
6. [Transport Layer](#transport-layer)
7. [Domain Layer](#domain-layer)
8. [Application Layer](#application-layer)
9. [Compatibility Layer](#compatibility-layer)
10. [Database Layer](#database-layer)
11. [Utilities](#utilities)
12. [Type System](#type-system)
13. [Realtime Subsystem (Deep Dive)](#realtime-subsystem-deep-dive)
14. [MessengerBot (Deep Dive)](#messengerbot-deep-dive)
15. [Thread Cache & Realtime Sync](#thread-cache--realtime-sync)
16. [Related Documentation](#related-documentation)

---

## Design Principles

1. **Domain isolation** — Each business area (messages, threads, users, account) is a self-contained domain module with its own types, commands, and queries.
2. **Transport abstraction** — HTTP (GraphQL, Mercury, form-data) and MQTT are in the `transport/` layer, decoupled from domain logic.
3. **Backward compatibility** — The flat `api.sendMessage(...)` surface is preserved via `attachLegacyApiSurface`. Existing bots need zero migration.
4. **Progressive API** — New users can choose `createMessengerBot` (event-driven) or `createFcaClient` (namespaced facade) without understanding the internals.
5. **Optional persistence** — SQLite + Sequelize for caching is opt-in. Everything works in-memory when the database is absent.

---

## Bootstrap Flow

After cookie parsing or credential-based authentication, the following sequence runs:

```
1. core/login-helper.impl.ts
   └─ Completes the session, creates `ctx` (FcaContext) and base `api` facade.

2. core/state.ts → attachThreadUpdater(ctx, models, logger)
   └─ Wires DB-based message counting per thread (if Thread model exists).

3. app/attach-legacy-api.ts → attachLegacyApiSurface(ctx, api, ...)
   └─ Attaches all flat methods + domain namespace methods onto `api`.

4. core/thread-info-realtime-sync.ts → attachThreadInfoRealtimeSync(ctx, models, logger, api)
   └─ Hooks MQTT "event" deltas to invalidate / update the thread cache.
      Requires `api.getUserInfo` to be present on `api`.

5. compat/api-registry.ts → attachClientFacade(ctx)
   └─ Adds `ctx.client` (the namespaced FcaClientFacade).
```

Each step is optional when composing a custom login flow — functions are exported individually.

---

## Source Tree

```
src/
├── core/                      # Session, config, state, fundamental helpers
│   ├── auth.ts                  # login(), loginLegacy(), loginViaAPI(), tokensViaAPI()
│   ├── auth-helpers.ts          # createAuthCore() — low-level auth plumbing
│   ├── config.ts                # loadConfig(), defaultConfig(), resolveConfig()
│   ├── login-helper.ts          # High-level login orchestration (entry)
│   ├── login-helper.impl.ts     # Login implementation: session init, ctx creation
│   ├── mqtt.ts                  # listenMqtt() helper
│   ├── options.ts               # setOptions() — validates and applies FcaOptions
│   ├── request.ts               # createRequestHelper() — authenticated HTTP
│   ├── state.ts                 # FcaContext, createFcaState(), attachThreadUpdater()
│   ├── thread-info-realtime-sync.ts  # Cache sync from MQTT events
│   └── update-check.ts         # npm version check
│
├── transport/                 # Protocol-level I/O
│   ├── http/
│   │   ├── facebook.ts          # Core Facebook HTTP endpoints
│   │   ├── form-data.ts         # Multipart form-data uploads
│   │   ├── graphql.ts           # GraphQL query execution
│   │   ├── mercury.ts           # Mercury endpoint (message operations)
│   │   ├── shared-photos.ts     # Shared photos endpoint
│   │   ├── threads.ts           # Thread-specific HTTP calls
│   │   └── upload-attachment.ts # Attachment upload transport
│   └── realtime/
│       ├── connect-mqtt.ts      # WebSocket MQTT connection, subscribe, reconnect
│       ├── get-seq-id.ts        # Fetch sequence ID via GraphQL
│       ├── ls-requests.ts       # Lightspeed request builder
│       ├── publish.ts           # MQTT publish helpers
│       ├── stream.ts            # Duplex stream adapter for MQTT
│       ├── task-response.ts     # Parse MQTT task response payloads
│       └── topics.ts            # MQTT topic constants
│
├── domains/                   # Business logic grouped by concern
│   ├── messages/
│   │   ├── index.ts             # createMessagesDomain()
│   │   ├── message.types.ts     # Domain-specific types
│   │   ├── commands/            # sendMessage, editMessage, unsendMessage, ...
│   │   └── queries/             # getMessage, getEmojiUrl, resolvePhotoUrl, ...
│   ├── threads/
│   │   ├── index.ts             # createThreadsDomain()
│   │   ├── thread.types.ts
│   │   ├── commands/            # createNewGroup, addUserToGroup, setTitle, ...
│   │   └── queries/             # getThreadInfo, getThreadList, searchForThread, ...
│   ├── users/
│   │   ├── index.ts             # createUsersDomain()
│   │   ├── user.types.ts
│   │   ├── shared.ts            # Shared user utilities
│   │   └── queries/             # getUserInfo, getUserInfoV2, getUserID, getFriendsList
│   ├── account/
│   │   ├── index.ts             # createAccountDomain()
│   │   ├── account.types.ts
│   │   └── commands/            # changeAvatar, changeBio, logout, unfriend, ...
│   ├── realtime/
│   │   ├── index.ts             # createRealtimeDomain()
│   │   ├── listener.ts          # MQTT lifecycle: getSeqID → listen → retry
│   │   ├── emit-auth.ts         # MQTT auth emission
│   │   ├── middleware.ts        # Realtime middleware chain
│   │   └── parse-delta.ts       # Delta → event transformation
│   ├── http/
│   │   ├── index.ts             # createHttpDomain()
│   │   ├── commands/            # httpPost, postFormData
│   │   └── queries/             # httpGet
│   └── scheduler/
│       └── index.ts             # createSchedulerDomain()
│
├── app/                       # High-level application constructs
│   ├── attach-legacy-api.ts     # Attaches flat methods + namespaces onto api
│   ├── create-client.ts         # createFcaClient() — namespaced facade factory
│   ├── messenger-bot.ts         # MessengerBot class (EventEmitter + composer)
│   └── messenger-context.ts     # MessengerContext — per-message context object
│
├── compat/                    # Backward-compatibility adapters
│   ├── api-registry.ts          # attachClientFacade() — ctx.client wiring
│   ├── callbackify.ts           # Promise → callback adapter
│   └── legacy-promise.ts        # Legacy promise wrapper
│
├── database/                  # Optional SQLite + Sequelize persistence
│   ├── helpers.ts               # DB initialization helpers
│   ├── models/
│   │   ├── index.ts             # Model registry
│   │   ├── thread.ts            # Thread model (threadID, data, messageCount)
│   │   └── user.ts              # User model
│   ├── threadData.ts            # Thread data access layer
│   └── userData.ts              # User data access layer
│
├── session/                   # Session management
│   ├── capability-resolver.ts   # Resolves available capabilities
│   └── session.ts               # Session abstraction
│
├── remote/                    # Remote control
│   └── remoteClient.ts         # WebSocket client for external dashboards
│
├── func/                      # Logging infrastructure
│   ├── logger.ts                # Main logger
│   └── logAdapter.ts            # Log format adapter
│
├── utils/                     # Shared utilities
│   ├── broadcast.ts             # Broadcast helper
│   ├── client.ts                # Client utilities
│   ├── constants.ts             # Shared constants
│   ├── cookies.ts               # Cookie manipulation
│   ├── headers.ts               # HTTP header construction
│   ├── format/                  # Data formatting
│   │   ├── index.ts             # Format barrel export
│   │   ├── attachment.ts        # Attachment formatting
│   │   ├── cookie.ts            # Cookie formatting
│   │   ├── date.ts              # Date formatting
│   │   ├── decode.ts            # Decoding utilities
│   │   ├── delta.ts             # MQTT delta formatting
│   │   ├── ids.ts               # ID formatting
│   │   ├── message.ts           # Message formatting
│   │   ├── presence.ts          # Presence formatting
│   │   ├── readTyp.ts           # Read/typing formatting
│   │   ├── thread.ts            # Thread formatting
│   │   └── utils.ts             # General format utilities
│   ├── loginParser/             # Login response parsing
│   │   ├── index.ts             # Parser barrel export
│   │   ├── autoLogin.ts         # Auto-login logic
│   │   ├── helpers.ts           # Parser helpers
│   │   ├── parseAndCheckLogin.ts # Main login response parser
│   │   └── textUtils.ts         # Text parsing utilities
│   └── request/                 # HTTP request infrastructure
│       ├── index.ts             # Request barrel export
│       ├── client.ts            # HTTP client setup
│       ├── config.ts            # Request configuration
│       ├── defaults.ts          # Default request options
│       └── helpers.ts           # Request helpers
│
├── types/                     # Public TypeScript types
│   ├── index.ts                 # Type barrel export
│   ├── client.ts                # FcaClientFacade, FcaClientNamespace
│   ├── core.ts                  # Core types (FcaID, etc.)
│   ├── core-modules.ts          # Core module types
│   ├── events.ts                # MqttEvent, MessageEvent, ReactionEvent, ...
│   ├── messaging.ts             # Messaging types
│   ├── threads.ts               # Thread types
│   └── scheduler.ts             # Scheduler types
│
├── global-types.d.ts          # Global type declarations (Loose, etc.)
└── index.ts                   # Package entry — re-exports everything public
```

---

## Layer Diagram

```
┌───────────────────────────────────────────────────┐
│                  Consumer Code                     │
│         (bot scripts, integrations, etc.)          │
└───────────┬──────────────┬──────────────┬─────────┘
            │              │              │
    ┌───────▼──────┐ ┌────▼─────┐ ┌──────▼──────┐
    │ MessengerBot │ │ FcaClient│ │  Flat API   │
    │  (app/)      │ │  Facade  │ │ (legacy)    │
    └───────┬──────┘ └────┬─────┘ └──────┬──────┘
            │              │              │
            └──────────────┼──────────────┘
                           │
              ┌────────────▼────────────┐
              │     Domain Layer        │
              │  messages / threads /   │
              │  users / account /      │
              │  realtime / http /      │
              │  scheduler              │
              └────────────┬────────────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
    ┌───────▼──────┐ ┌────▼─────┐ ┌──────▼──────┐
    │  Transport   │ │   Core   │ │  Database   │
    │  http/       │ │  auth,   │ │  (optional) │
    │  realtime/   │ │  state,  │ │  SQLite +   │
    │              │ │  config  │ │  Sequelize  │
    └──────────────┘ └──────────┘ └─────────────┘
```

---

## Core Layer

**`src/core/`** manages authentication, session state, configuration, and fundamental helpers that every other layer depends on.

| File                          | Responsibility                                                    |
|-------------------------------|-------------------------------------------------------------------|
| `auth.ts`                     | Entry points: `login()`, `loginLegacy()`, `loginViaAPI()`, `tokensViaAPI()` |
| `auth-helpers.ts`             | Low-level auth plumbing: cookie extraction, token refresh         |
| `config.ts`                   | Load, merge, and write `fca-config.json`                          |
| `login-helper.ts`             | High-level login orchestration                                    |
| `login-helper.impl.ts`        | Session initialization, `ctx` and `api` creation                  |
| `mqtt.ts`                     | `listenMqtt()` — thin wrapper that delegates to `domains/realtime` |
| `options.ts`                  | Validate and apply `FcaOptions` onto global state                 |
| `request.ts`                  | `createRequestHelper()` — authenticated HTTP client               |
| `state.ts`                    | `FcaContext` type, `createFcaState()`, `createApiFacade()`, `attachThreadUpdater()` |
| `thread-info-realtime-sync.ts`| Sync thread cache from realtime MQTT events                       |
| `update-check.ts`             | Check npm registry for newer versions                             |

---

## Transport Layer

**`src/transport/`** handles raw protocol-level communication. Domain modules call into transport functions rather than making HTTP or MQTT calls directly.

### HTTP (`transport/http/`)

| File                  | Purpose                                           |
|-----------------------|---------------------------------------------------|
| `facebook.ts`         | General Facebook API endpoints                    |
| `graphql.ts`          | Execute GraphQL queries with authenticated context |
| `mercury.ts`          | Mercury endpoint for message-related operations   |
| `form-data.ts`        | Multipart form-data POST requests                 |
| `upload-attachment.ts`| Upload attachments to Facebook's CDN              |
| `shared-photos.ts`    | Shared photos endpoint                            |
| `threads.ts`          | Thread-specific HTTP operations                   |

### Realtime (`transport/realtime/`)

| File               | Purpose                                                            |
|--------------------|--------------------------------------------------------------------|
| `connect-mqtt.ts`  | Establish WebSocket connection to Facebook MQTT; subscribe to topics in batch, then publish sync; handle reconnection safely |
| `get-seq-id.ts`    | Fetch the latest sequence ID via GraphQL (required before listening) |
| `publish.ts`       | MQTT publish helpers                                               |
| `stream.ts`        | Duplex stream adapter for the MQTT wire protocol                   |
| `task-response.ts` | Parse task/response payloads from MQTT frames                      |
| `topics.ts`        | Topic string constants (`/t_ms`, `/thread_typing`, etc.)           |
| `ls-requests.ts`   | Build Lightspeed request payloads                                  |

---

## Domain Layer

**`src/domains/`** contains all business logic organized by concern. Each domain exports a `create*Domain()` factory that returns an object of related functions.

### Structure pattern

```
domains/<name>/
├── index.ts           # createXxxDomain() factory
├── <name>.types.ts    # Domain-specific TypeScript types
├── commands/          # Write operations (mutations)
│   ├── do-something.ts
│   └── ...
└── queries/           # Read operations
    ├── get-something.ts
    └── ...
```

### Domains

| Domain      | Commands                                                                                   | Queries                                                          |
|-------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------|
| `messages`  | send, edit, unsend, delete, setReaction, sendTyping, markRead, markDelivered, markSeen, markReadAll, upload, forward, shareContact, changeColor, changeEmoji | getMessage, getEmojiUrl, resolvePhotoUrl, getThreadColors |
| `threads`   | createGroup, addUser, removeUser, changeAdmin, changeImage, changeNickname, setTitle, createPoll, createThemeAI, delete, archive, mute, handleRequest | getInfo, getList, getHistory, getPictures, getThemePictures, search |
| `users`     | —                                                                                          | getInfo, getInfoV2, getID, getFriendsList                        |
| `account`   | changeAvatar, changeBio, changeBlocked, handleFriendReq, unfriend, setPostReaction, refreshDtsg, logout, addModule, enableAutoSave | getCurrentUserID |
| `realtime`  | *(listener lifecycle, emit-auth, middleware)*                                               | *(parse-delta)*                                                  |
| `http`      | httpPost, postFormData                                                                     | httpGet                                                          |
| `scheduler` | *(scheduling primitives)*                                                                  | —                                                                |

---

## Application Layer

**`src/app/`** provides the high-level constructs that consumers interact with directly.

| File                    | What it does                                                                |
|-------------------------|-----------------------------------------------------------------------------|
| `attach-legacy-api.ts`  | Attaches all flat methods + domain namespaces onto the `api` object         |
| `create-client.ts`      | `createFcaClient(api)` — wraps flat API into a `FcaClientFacade`            |
| `messenger-bot.ts`      | `MessengerBot` class — EventEmitter + composer middleware engine            |
| `messenger-context.ts`  | `MessengerContext` — per-message context with `reply()` / `replyAsync()`    |

---

## Compatibility Layer

**`src/compat/`** ensures older code keeps working.

| File               | Purpose                                                       |
|--------------------|---------------------------------------------------------------|
| `api-registry.ts`  | `attachClientFacade(ctx)` — adds `ctx.client` lazily          |
| `callbackify.ts`   | Convert promise-returning functions to Node-style callbacks    |
| `legacy-promise.ts`| Wrap callbacks in a Promise for dual-mode support              |

---

## Database Layer

**`src/database/`** is entirely optional. When SQLite + Sequelize are available:

- **Models:** `Thread` (stores JSON thread data + `messageCount`) and `User` (stores user profile cache).
- **`threadData.ts`** / **`userData.ts`** provide a data access layer with freshness-based reads and writes.
- **`helpers.ts`** handles Sequelize initialization and model synchronization.

When the database is absent, all cache features gracefully degrade to in-memory or no-op behavior.

---

## Utilities

**`src/utils/`** contains cross-cutting concerns:

| Subdirectory / File | Purpose                                                     |
|---------------------|-------------------------------------------------------------|
| `format/`           | Transform raw Facebook data into normalized structures (attachments, deltas, messages, threads, presence, IDs, dates) |
| `loginParser/`      | Parse login HTTP responses, handle auto-login, extract tokens |
| `request/`          | HTTP client setup, default headers, proxy configuration      |
| `broadcast.ts`      | Broadcast helper for multi-thread messaging                  |
| `client.ts`         | Client-level utility functions                               |
| `constants.ts`      | Shared constant values                                       |
| `cookies.ts`        | Cookie parsing and manipulation                              |
| `headers.ts`        | HTTP header construction for Facebook API requests           |

---

## Type System

**`src/types/`** contains all publicly exported TypeScript interfaces and type aliases:

| File             | Contents                                                   |
|------------------|------------------------------------------------------------|
| `client.ts`      | `FcaClientFacade`, `FcaClientNamespace`, `LegacyApiLike`   |
| `core.ts`        | `FcaID` and other primitive types                          |
| `core-modules.ts`| Core module interface types                                |
| `events.ts`      | `MqttEvent` union, `MessageEvent`, `ReactionEvent`, `TypingEvent`, etc. |
| `messaging.ts`   | Messaging-related types                                    |
| `threads.ts`     | Thread-related types                                       |
| `scheduler.ts`   | Scheduler types                                            |

`src/global-types.d.ts` declares the global `Loose` type (alias for `any`) used throughout the codebase for dynamic Facebook API payloads.

---

## Realtime Subsystem (Deep Dive)

### Connection lifecycle

1. **`domains/realtime/listener.ts`** orchestrates the full lifecycle:
   - Calls `getSeqID` (GraphQL) to obtain the latest sequence number.
   - Invokes `listenMqtt` which delegates to `transport/realtime/connect-mqtt.ts`.
   - Manages auto-cycle (periodic reconnection) and retry logic with debounced `getSeqID`.

2. **`transport/realtime/connect-mqtt.ts`** handles the wire protocol:
   - Opens a WebSocket to Facebook's MQTT endpoint.
   - Subscribes to topics in a batch (`/t_ms`, `/thread_typing`, `/orca_presence`, etc.).
   - Only after subscriptions complete does it publish the sync queue.
   - On disconnect, the old client is fully cleaned up before creating a new one.

3. **`domains/realtime/parse-delta.ts`** transforms raw MQTT deltas into typed event objects and dispatches them through the callback chain. It also fires `emitThreadInfoEvent` to trigger cache synchronization.

### Topics

Defined in `transport/realtime/topics.ts`. Key topics include thread messages (`/t_ms`), typing indicators (`/thread_typing`), presence (`/orca_presence`), and Lightspeed requests (`/ls_req`, `/ls_resp`).

---

## MessengerBot (Deep Dive)

### Event dispatch

`MessengerBot` listens on the MQTT emitter's `"message"` event and maps each `MqttEvent` to named channels:

- `message` / `messageCreate` for chat messages and replies
- `messageReactionAdd`, `messageDelete`, `typingStart`, `typingStop`, `threadUpdate`, `ready`, `shardReady`
- `raw` / `update` for every delta

The `emitIf` helper only fires `emit()` when there are active listeners, keeping overhead minimal.

### Composer engine

The composer is a Koa-style middleware chain that runs only for `message` and `message_reply` events. Execution order:

1. Global `use()` middlewares in registration order.
2. `command()` handlers check for `{prefix}{name}` at the start of the message.
3. `hears()` handlers match by regex or substring.
4. If any middleware throws, the `catch()` handler receives the error.

Middleware is dispatched via `queueMicrotask` to avoid blocking the MQTT event loop.

---

## Thread Cache & Realtime Sync

**`core/thread-info-realtime-sync.ts`** subscribes to MQTT events of type `"event"` and performs:

| Log message type                  | Action                                                  |
|-----------------------------------|---------------------------------------------------------|
| `log:subscribe`                   | Add participant to cache, fetch fresh `userInfo`         |
| `log:unsubscribe`                 | Remove participant from cache                            |
| Thread metadata changes           | Invalidate the cached `data` (set to `null`)             |
| Unknown/unhandled types           | Invalidate as a safety measure                           |

This keeps the SQLite cache consistent with the actual thread state without requiring periodic full refetches.

---

## Related Documentation

- [README.md](../README.md) — Installation and quick start guide
- [DOCS.md](./DOCS.md) — Full API reference and usage guide
- Version history: [`CHANGELOG.md`](https://github.com/dongp06/fca-unofficial/blob/main/CHANGELOG.md) in the repository (not shipped in the npm tarball).