# facebook/facebook-python-business-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/facebook/facebook-python-business-sdk
- Repository: https://github.com/facebook/facebook-python-business-sdk

## Overview

##### Project type and purpose
- This is an open-source Python SDK (facebook_business) that wraps Facebook’s Graph and Marketing APIs.
- Its goal is to present a CRUD-style, object-oriented interface to Facebook Business endpoints, hiding HTTP details and batching logic.

##### File structure
- Top-level package: `facebook_business/`
- api.py, session.py, bootstrap.py, specs.py, exceptions.py, utils/
- `adobjects/`: hundreds of autogenerated classes (one per FB object) plus helpers
- `docs_runner/`: tooling to build reference docs
- test suite (`facebook_business/test/` and integration tests)
- Supporting files:
- `examples/`: dozens of sample scripts showing real-world usage
- `config.json.example`, `setup.py`, `requirements.txt`, CI workflows (GitHub Actions)
- Key patterns:
- SDK Codegen → generates `adobjects/` classes from a central specification
- CRUD abstraction (AbstractObject, AbstractCrudObject)
- Batch processing (FacebookAdsApiBatch)
- Pluggable sessions for multiple access tokens

##### Extract insights from README
- Describes initialization (`FacebookAdsApi.init` / `FacebookSession`) and token management
- Emphasizes CRUD methods (`api_get`, `api_update`, `create_xxx`, etc.)
- Explains batch calls, debugging (curl output), code-generation origin
- Lists example usage and test invocation

a. Main components
1. Developer Application
– Imports `facebook_business` package
– Calls into SDK classes
2. Facebook Business SDK
– Session Layer (`session.py`, `FacebookSession`)
– API Layer (`api.py`, `FacebookAdsApi`, `FacebookAdsApiBatch`)
– Model Layer (`adobjects/`):
· Abstract classes (AbstractObject, AbstractCrudObject)
· Generated object classes (AdAccount, Campaign, Page, etc.)
– Utilities (`utils/`, `specs.py`)
– Documentation tooling (`docs_runner/`)
– Configuration (`config.json.example`)
3. External Service
– Facebook Graph API endpoints over HTTPS
b. Relationships & interactions
- Developer code → instantiate `FacebookSession` / call `FacebookAdsApi.init`
- API Layer uses Session Layer to dispatch HTTP requests (supporting single/multiple tokens, proxies)
- Requests: JSON payloads built from Model Layer fields & specs
- Responses: JSON parsed back into Model Layer instances
- Batch calls aggregate multiple CRUD operations into one HTTP payload
- Errors raised through `facebook_business.exceptions`
c. Architectural patterns & principles
- Wrapper/Adapter: maps Python methods to REST endpoints
- Code-generation: ensures high parity with API spec
- Dependency injection: pluggable sessions allow multi-tenant token management
- Separation of concerns:
- Session concerns (auth, retries, proxies)
- API orchestration (batching, debug logging)
- Data modeling (CRUD classes)
d. Key technologies & frameworks
- Python packaging (setup.py, PyPI)
- HTTP client (under the hood via requests or urllib)
- JSON serialization / deserialization
- GitHub Actions for CI
- tox for multi-version testing

## Diagram (Mermaid)

```mermaid
graph TD
    %% Developer Layer
    DevApp["Developer Application"]:::developer
    Examples["Examples"]:::developer
    DevApp --> Examples
    click DevApp "https://github.com/facebook/facebook-python-business-sdk/tree/main/examples/"
    click Examples "https://github.com/facebook/facebook-python-business-sdk/tree/main/examples/"

    %% SDK Core Layer
    subgraph "SDK Core" 
        direction TB
        Bootstrap["Bootstrap / SDK Init"]:::sdk
        Session["Session Layer"]:::sdk
        API["API Layer"]:::sdk
        Utils["Utilities"]:::sdk
        Specs["Code-Generation Specs"]:::sdk
        Exceptions["Exceptions / Error Handling"]:::sdk
        Crash["Crash Reporter"]:::sdk

        Bootstrap --> Session
        Session --> API
        API -->|uses| Session
        API -->|builds requests| Utils
        Specs -->|feeds into| AbstractClasses
        Exceptions -->|raises errors to| DevApp
        Crash -->|reports errors| DevApp

        click Bootstrap "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/bootstrap.py"
        click Session "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/session.py"
        click API "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/api.py"
        click Utils "https://github.com/facebook/facebook-python-business-sdk/tree/main/facebook_business/utils/"
        click Specs "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/specs.py"
        click Exceptions "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/exceptions.py"
        click Crash "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/crashreporter.py"
    end

    %% Model Layer
    subgraph "Model Layer" 
        direction TB
        subgraph "Abstract Base Classes"
            direction TB
            AbstractClasses["AbstractObject / AbstractCrudObject"]:::sdk
        end
        subgraph "Generated Objects"
            direction TB
            Generated["Auto-generated adobjects"]:::sdk
        end
        subgraph "Server-Side Objects"
            direction TB
            ServerSide["Serverside batch & events"]:::sdk
        end

        AbstractClasses --> Generated
        Generated -->|CRUD methods| API
        ServerSide -->|batch operations| API

        click AbstractClasses "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/adobjects/abstractobject.py"
        click AbstractClasses "https://github.com/facebook/facebook-python-business-sdk/blob/main/facebook_business/adobjects/abstractcrudobject.py"
        click Generated "https://github.com/facebook/facebook-python-business-sdk/tree/main/facebook_business/adobjects/"
        click ServerSide "https://github.com/facebook/facebook-python-business-sdk/tree/main/facebook_business/adobjects/serverside/"
    end

    %% SDK Support Tools
    subgraph "SDK Tools & Support"
        direction TB
        Docs["Documentation Tooling"]:::tools
        ConfigExample["Configuration Example"]:::tools
        Docs --> ConfigExample
        Docs --> DevApp
        click Docs "https://github.com/facebook/facebook-python-business-sdk/tree/main/facebook_business/docs_runner/"
        click ConfigExample "https://github.com/facebook/facebook-python-business-sdk/blob/main/config.json.example"
    end

    %% Tests Layer
    Tests["Tests (Unit & Integration)"]:::tests
    click Tests "https://github.com/facebook/facebook-python-business-sdk/tree/main/facebook_business/test/"

    %% External Service
    External["Facebook Graph API"]:::external

    %% Connections
    DevApp -->|"init & auth"| Bootstrap
    DevApp -->|"calls CRUD"| API
    API -->|"HTTP Request"| External
    External -->|"JSON Response"| API
    API -->|"models to objects"| Generated
    API -->|"errors"| Exceptions
    DevApp -->|"runs examples"| Examples
    DevApp -->|"runs tests"| Tests

    %% Styles
    classDef developer fill:#b3e6b3,stroke:#2d7f2d;
    classDef sdk fill:#cce0ff,stroke:#0047b3;
    classDef tools fill:#ffe0b3,stroke:#b37400;
    classDef tests fill:#e6ccff,stroke:#6600cc;
    classDef external fill:#ffcccc,stroke:#b30000;
```
