Documenting the project on 1C-Bitrix

Project Documentation for 1C-Bitrix

A Bitrix project without documentation is a fortress that the next developer will spend weeks storming. Especially painful: non-standard components with overloaded parameters, modules with undocumented dependencies, custom DB tables without a schema, agents with non-obvious schedules. Documenting a Bitrix project is not about writing texts — it's engineering work to extract and structure knowledge from the codebase.

What to Document First

Not everything is equally important. Priorities:

Critical (without this you can't work with the project):

• Iblock structure: IDs, property types, relationships
• Custom DB tables: schema, purpose, relations
• Non-standard components and their parameters
• Integrations: what connects to what, which tokens are used
• Deployment and configuration processes

Important (needed for further development):

• Business logic of custom modules
• Algorithms for non-trivial calculations (prices, discounts)
• Extension points: events, handlers

Useful (nice to have):

• Description of standard Bitrix functionality that was configured
• Reasons for non-standard decisions ("why it was done this way")

Documenting Iblocks

Iblocks are the heart of a Bitrix project. A common problem: iblock ID 17 — what is it? Solution: auto-generate documentation from DB metadata.

// Script to generate iblock documentation
$iblocks = \Bitrix\Iblock\IblockTable::getList([
    'select' => ['ID', 'NAME', 'CODE', 'IBLOCK_TYPE_ID', 'DESCRIPTION'],
    'order' => ['IBLOCK_TYPE_ID' => 'ASC', 'NAME' => 'ASC'],
])->fetchAll();

foreach ($iblocks as $iblock) {
    $props = \Bitrix\Iblock\PropertyTable::getList([
        'filter' => ['IBLOCK_ID' => $iblock['ID']],
        'select' => ['ID', 'NAME', 'CODE', 'PROPERTY_TYPE', 'USER_TYPE', 'LINK_IBLOCK_ID'],
        'order' => ['SORT' => 'ASC'],
    ])->fetchAll();

    // Generate a Markdown page for the iblock
    echo "## {$iblock['NAME']} (ID: {$iblock['ID']}, CODE: {$iblock['CODE']})\n";
    // ...
}

Result: Markdown files with property tables that can be kept in a git repository and updated by script.

Example document for an iblock:

## Product Catalog (ID: 5, CODE: catalog)

**Type:** catalog | **Site:** s1

### Properties

| Code | Name | Type | Notes |
|---|---|---|---|
| VENDOR_CODE | SKU | S (string) | Required, unique |
| BRAND | Brand | E (element link) | → Iblock ID 8 (Brands) |
| WEIGHT | Weight (g) | N (number) | For shipping calculation |
| IMAGES | Additional photos | F (file) | Multiple |

Documenting Custom DB

For custom tables — ERD diagram + text description. Minimum:

## Table `booking_slots`

**Purpose:** Time slots for service bookings. Created by the `local.booking` module.

| Field | Type | Description |
|---|---|---|
| ID | INT AUTO_INCREMENT | PK |
| SPECIALIST_ID | INT | FK → b_user.ID |
| SERVICE_ID | INT | FK → b_iblock_element.ID (IB 12) |
| DATE_FROM | DATETIME | Slot start |
| DATE_TO | DATETIME | Slot end |
| STATUS | ENUM('free','booked','blocked') | Current status |
| BOOKING_ID | INT NULL | FK → bookings.ID when STATUS=booked |

**Indexes:** `(SPECIALIST_ID, DATE_FROM)`, `(STATUS)`
**Created:** On module install in `local/modules/local.booking/install/db/mysql/install.sql`

Documenting Components

For custom components — a component.ru.php file with parameter descriptions (Bitrix standard), plus a separate Markdown with usage examples:

## Component `local:catalog.filter.extended`

**Path:** `/local/components/local/catalog.filter.extended/`
**Purpose:** Extended catalog filter with range support and multiple selection.

### Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| IBLOCK_ID | int | — | Catalog iblock ID (required) |
| PRICE_TYPES | array | [1] | Price type IDs for filter |
| USE_RANGE | bool | true | Enable price range filter |
| AJAX_MODE | bool | true | Update without page reload |

### Usage Example
```php
<?$APPLICATION->IncludeComponent('local:catalog.filter.extended', '', [
    'IBLOCK_ID' => 5,
    'PRICE_TYPES' => [1, 2],
    'USE_RANGE' => true,
]);?>

Known Limitations

• Does not work with trade offers (SKU) — only main products

### Documenting Integrations

An integration map is a required document for projects with external systems:

```markdown
## Integration Map

### Bitrix24 CRM ↔ Website
- **Type:** REST API + webhooks
- **Direction:** bidirectional
- **What is synced:** leads from forms → B24, order statuses B24 → website
- **Tokens:** in `/bitrix/.settings_extra.php`, variable `B24_WEBHOOK_URL`
- **Schedule:** every 15 minutes (agent `\Integration\B24Agent::sync()`)
- **Logs:** `/local/logs/b24_integration.log`

### 1C:Enterprise ↔ Website
- **Type:** CommerceML 2.0 (standard Bitrix exchange)
- **Direction:** products and stock from 1C, orders to 1C
- **Schedule:** every 2 hours (configured in `/bitrix/admin/1c_exchange.php`)
- **Issues:** with > 10,000 products the exchange takes > 30 min, split-by-file configured

Tools and Formats

Markdown + Git — the primary format. Documentation lives alongside the code in /docs/ of the repository, updated together with changes.

Confluence/Notion — for documentation accessible to managers and clients without git access.

PHPDoc in code — required for custom modules and components. The Bitrix standard requires PHPDoc on class methods.

Diagrams — PlantUML or Mermaid for ERD and interaction diagrams, can be rendered directly in Markdown documents.

Keeping Documentation Up to Date

Documentation without an update process becomes stale quickly. Mandatory rules:

• Changing an iblock → update the iblock Markdown file in the same PR
• Adding a custom table → add its description to /docs/database/
• Adding an integration → update the integration map
• Deploy → run the auto-generation script for current schemas

Documentation Work Stages

Total: 2–4 weeks for a mid-sized project.