# bitrix-tools/b24-rest-docs architecture

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

- Interactive diagram: https://gitdiagram.com/bitrix-tools/b24-rest-docs
- Repository: https://github.com/bitrix-tools/b24-rest-docs

## Overview

##### Main Project Type and Purpose
- The repository is for REST API documentation – it is a static documentation site that serves as the source for the online Bitrix24 API docs.
- The documentation is versioned and uses an extended Markdown syntax; it supports localization and multiple content types (API references, tutorials, guides, integration examples, etc.).

##### Identifying the Main Components
a. Source Repository:
– Git Repository containing the Markdown (.md) files, YAML configuration files, image directories (_images), assets (_assets), example code snippets, and supportive directories (tutorials, market, local-integrations, etc.).
b. Documentation Build/Generation Pipeline:
– A static site generation engine that parses the Markdown content and YAML table-of-contents files (e.g., from tools like Diplodoc or a similar generator).
– Build scripts and configuration files (for local builds or CI) that convert the content into HTML.
c. Deployment & Hosting:
– Once built, the static HTML files (with CSS and JavaScript from assets) are deployed to a web server/CDN, making the online version available at the URL (https://apidocs.bitrix24.ru/).
d. Content Delivery / User-Facing Website:
– The final site providing the rendered documentation, searchable API reference, tutorials, guides and other documentation.
e. Contribution/Collaboration Workflow:
– Contributors use standard Git workflows to propose changes (via pull requests) that trigger the build/rebuild process.
– Integration with CI/CD pipelines (if applicable) to automate testing and deployment of documentation updates.

##### Relationships and Data Flows
- Users (developers and contributors) edit the content in the repository.
- A Continuous Integration (CI) system (or local build tools) detects changes in the Git repository and triggers the static site generator.
- The build process reads and processes the Markdown, YAML (TOC) and asset files to produce static HTML pages.
- These generated files are then deployed to a hosting server/CDN.
- End users access the final online documentation via their browsers.

##### Highlighting Architectural Patterns and Design Principles
- “Documentation as Code”: The documentation is developed using version control, Markdown, and code-review processes.
- Static Site Generation: Separation of content management (stored as Markdown) from the presentation layer (generated website).
- Modular File Organization: The file tree is structured by API area (crm, chat-bots, catalogs, etc.), tutorials, market, and integrations, ensuring scalability and easier localization.
- Extensibility: By using configuration files (YAML) and extended Markdown, contributors can easily add new sections or adapt the documentation structure.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Actors
    Dev("Developers/Contributors"):::actor
    End("End Users"):::actor

    %% Source Repository Subgraph
    subgraph "Source Content Repository"
        SRC("Source Content Repository"):::repo
        API("API Documentation Content"):::content
        TUT("Tutorials and Examples"):::content
        AST("Assets (Styles, Scripts, Images)"):::asset
        CFG("Configuration Files"):::config
        LINT("Local Integrations & Market"):::integration
    end

    %% Build and Deployment Components
    BUILD("Build Pipeline & Static Site Generator"):::build
    DEPLOY("Deployment Environment/CDN"):::deployment
    WEB("Hosted Documentation Website"):::website

    %% Relationships / Data Flows
    Dev -->|"edits"| SRC
    SRC -->|"contains"| API
    SRC -->|"contains"| TUT
    SRC -->|"contains"| AST
    SRC -->|"contains"| CFG
    SRC -->|"contains"| LINT
    SRC -->|"triggers"| BUILD
    BUILD -->|"generates"| DEPLOY
    DEPLOY -->|"serves"| WEB
    End -->|"accesses"| WEB

    %% Click Events
    click SRC "https://github.com/bitrix-tools/b24-rest-docs/blob/main/README.md"
    click API "https://github.com/bitrix-tools/b24-rest-docs/tree/main/api-reference"
    click TUT "https://github.com/bitrix-tools/b24-rest-docs/tree/main/tutorials"
    click AST "https://github.com/bitrix-tools/b24-rest-docs/tree/main/_assets"
    click CFG "https://github.com/bitrix-tools/b24-rest-docs/blob/main/toc.yaml"
    click LINT "https://github.com/bitrix-tools/b24-rest-docs/tree/main/local-integrations"
    click BUILD "https://github.com/bitrix-tools/b24-rest-docs/blob/main/.yfm"

    %% Styles
    classDef actor fill:#FDD835,stroke:#BF360C,stroke-width:2px;
    classDef repo fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef content fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef asset fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef config fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef integration fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef build fill:#FFE0B2,stroke:#E64A19,stroke-width:2px;
    classDef deployment fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef website fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
```
