# bitrix-tools/crest architecture

> Architecture diagram of the GitHub repository bitrix-tools/crest, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bitrix-tools/crest
- Repository: https://github.com/bitrix-tools/crest

## Overview

##### Project Type and Purpose
- This is an open-source PHP SDK (PHPSDK) for interacting with the Bitrix24 REST API. It provides a small library (CRest) plus example scripts (index.php, install.php, checkserver.php) and a configuration file (settings.php). It can be used as:
- A webhook client (inbound webhook)
- A local or public OAuth2-based application

##### Main Components
A. Client (Browser or CLI)
- Triggers HTTP requests to your server endpoints (index.php, install.php, checkserver.php).
B. Web Server / PHP Runtime
- Hosts the PHP scripts. Must have cURL extension and valid SSL certificate.
C. PHP Scripts (src folder & root)
- src/crest.php: Defines the CRest class (core SDK).
- index.php: Example usage entrypoint to call CRest::call().
- install.php: Performs OAuth2 install flows for local or public apps.
- checkserver.php: Verifies server cURL and SSL readiness.
- settings.php: Configuration (webhook URL, OAuth client_id/secret, encoding constant, and persistence methods).
D. Persistence Layer
- Default: text file via CRest::getSettingData/setSettingData.
- Customizable by inheriting CRest and overriding those methods to use DB or other storage.
E. External Service
- Bitrix24 REST API endpoints (over HTTPS).

##### Relationships & Data Flows
1. Browser → HTTP GET/POST → index.php / install.php / checkserver.php
2. PHP script loads settings.php and crest.php (CRest class)
3. CRest::call(...) constructs an HTTP request via PHP cURL
4. cURL → HTTPS request → Bitrix24 REST API
5. Bitrix24 responds → cURL → CRest parses JSON → returns to PHP script
6. PHP script echoes JSON result to browser
7. For OAuth2 flows:
a. install.php redirects user to Bitrix24 OAuth2 consent URL
b. Bitrix24 redirects back with code → install.php exchanges code for tokens
c. CRest::setSettingData persists access/refresh tokens

##### Architectural Patterns & Design Principles
- Single-responsibility: separate scripts for example usage (index), installation (install), health check (checkserver).
- Pluggable persistence: settings.php holds constants; CRest allows overriding getSettingData/setSettingData for custom token storage.
- External integration: CRest acts as an adapter/facade over the Bitrix24 REST API using cURL.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client Browser/CLI"]:::client

    %% Web Server / PHP Runtime Boundary
    subgraph "Web Server / PHP Runtime"
        direction TB
        index["index.php"]:::script
        install["install.php"]:::script
        checkserver["checkserver.php"]:::script
        crest["CRest Class"]:::library
        settings["settings.php"]:::persistence
        curl["PHP cURL Extension"]:::extension
    end

    %% External Service
    external["Bitrix24 REST API"]:::external

    %% Flows
    Client -->|"HTTP GET/POST"| index
    Client -->|"HTTP GET/POST"| install
    Client -->|"HTTP GET/POST"| checkserver

    index -->|"loads settings & CRest"| settings
    index -->|"loads settings & CRest"| crest
    install -->|"loads settings & CRest"| settings
    install -->|"loads settings & CRest"| crest
    checkserver -->|"loads settings & CRest"| settings
    checkserver -->|"loads settings & CRest"| crest

    crest -->|"cURL call"| curl
    curl -->|"HTTPS request"| external
    external -->|"JSON response"| curl
    curl -->|"returns JSON"| crest
    crest -->|"returns result"| index
    crest -->|"returns result"| install
    crest -->|"returns result"| checkserver

    %% OAuth Flow
    install -->|"redirect user to OAuth consent"| external
    external -->|"redirect back with code"| install
    install -->|"exchange code for tokens via CRest"| crest
    crest -->|"cURL token request"| curl
    curl -->|"token response"| crest
    crest -->|"persist tokens"| settings

    %% Persistence Interaction
    crest -->|"getSettingData/setSettingData"| settings

    %% Click Events
    click crest "https://github.com/bitrix-tools/crest/blob/master/src/crest.php"
    click index "https://github.com/bitrix-tools/crest/blob/master/src/index.php"
    click install "https://github.com/bitrix-tools/crest/blob/master/src/install.php"
    click checkserver "https://github.com/bitrix-tools/crest/blob/master/src/checkserver.php"
    click settings "https://github.com/bitrix-tools/crest/blob/master/src/settings.php"
    click README["README.md"] "README.md"
    click LICENSE["LICENSE"] "LICENSE"

    %% Style Definitions
    classDef client fill:#D0E8F2,stroke:#036,stroke-width:2px;
    classDef script fill:#E2F0D9,stroke:#216,stroke-width:2px;
    classDef library fill:#FDE4CF,stroke:#F0833A,stroke-width:2px;
    classDef persistence fill:#FFF2B2,stroke:#E5B700,stroke-width:2px;
    classDef extension fill:#E0E0E0,stroke:#888,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#F8D7DA,stroke:#C82333,stroke-width:2px,stroke-dasharray: 2 2;
```
