Technical Specification for 1С-Bitrix Website Development

Imagine you're launching an online store on 1С-Bitrix. A catalog of 15,000 products, integration with 1С, a B2B cabinet for dealers. The developer asks: 'how do we filter by stock?' – and it turns out that nowhere is it specified that prices should be individual for each dealer group. Result: reworking the filter and personal account adds 40% to the budget. According to our statistics, 80% of performance issues arise from unclear infoblock descriptions, and revisions during development cost 3-5 times more than fixing the specification. That's why we create a technical specification that captures all requirements before development starts. Order a technical specification – we'll prepare a document that saves you up to 50% of the budget and eliminates misunderstandings between you and the developer.

What sections must be in a Technical Specification for Bitrix?

A TS for a Bitrix project differs from a TS for a generic website. In addition to standard sections (goals, audience, functional requirements), specific sections are needed.

Edition and Licensing

Specify the Bitrix edition (Start, Standard, Small Business, Business, Enterprise) and justification. For an online store, the minimum is Small Business (catalog module, SKUs, one price list). If you need an extended catalog with multiple price types, discount rules (sale.discount), stock aggregation across warehouses – Business or Enterprise.

Infoblock Structure

List all infoblocks with property types. This is where a decision is made that later cannot be changed painlessly: property type 'String' vs 'Directory' (HL-block). For each infoblock, a table:

Integrations

Exchange with 1С is described separately: synchronization direction (two-way or only export from 1С), frequency, what is synchronized (stock, prices, images, properties). The mistake is to write simply 'integration with 1С'. Specify: which 1С configuration, standard exchange via CommerceML or custom integration via API, field mapping.

Performance

SLA for page response time: catalog section ≤ N seconds with M concurrent users. This is the only way to formalize performance requirements – without this section, speed complaints cannot be raised.

How to avoid mistakes when designing a TS?

A structured TS reduces rework by 3-5 times compared to verbal agreements. Formal TS is more effective: rework occurs in only 10% of projects vs 70% with verbal agreements, saving 30–50% of the budget. We recommend including user scenarios and technical requirements that are often missed.

Designing User Scenarios

A TS without scenarios describes the system but not how people work. For a Bitrix project, important scenarios:

• Checkout: number of steps, authorization, delivery/payment methods, cart behavior for unauthenticated users.
• Personal account: order history from b_sale_order, statuses, ability to reorder.
• Administrative scenario: how a manager adds a product, edits price, processes an order.

Each scenario is described sequentially with references to Bitrix components or marked as 'custom development'.

Typical Omissions in a TS

• User roles and permissions: Bitrix uses groups and permission system for infoblocks, sections, components. For a B2B cabinet or dealer section, the access matrix must be in the TS.
• SEO technical requirements: SEF URLs, meta tags, robots.txt, sitemap.xml – configured via the seo module. Without explicit requirements, defaults are used.
• Multilingual: for multiple languages, specify the structure of language sites in one kernel, content mapping, locale for dates and currencies.

Why does the budget grow without a TS?

Case: a wholesale supplier wanted 'a catalog with filter and personal account for dealers'. A 2-page TS written within the client's team. After launch, it turned out:

• Dealers needed individual prices (three price types per group), but the developer implemented a single price list.
• The filter did not account for stock – products with zero stock appeared in results.
• The personal account only showed orders placed via the site, but dealers expected history from 1С.

Rework took 3 months with an original development budget of 6 weeks. If requirements had been formalized in a TS before work started, the scope and cost would have been estimated correctly. A formal TS is 3-5 times more effective than verbal agreements: rework occurs in only 10% of projects instead of 70%.

How we create a TS: step-by-step process

1. Client interview: identify business processes, users, integrations.
2. Analysis of existing systems (1С, CRM, warehouse).
3. Design infoblock structure and properties.
4. Describe user scenarios for all roles.
5. Formulate functional requirements linked to Bitrix components and modules.
6. Define non-functional requirements: performance, security, scalability.
7. Prototype key screens (wireframes).
8. Review and finalize the document.

Volume of a TS for a typical online store: 40–80 pages. Preparation time: from 2 weeks for a small project to 6–8 weeks for a complex multi-functional portal with several integrations.

What's included in the work

A properly prepared technical specification guarantees a transparent budget and predictable results. Our 10+ years of experience in Bitrix development ensures the quality of documentation. Additional information can be found in relevant articles on Wikipedia and Wikipedia (1С-Bitrix).

Get a consultation and order a technical specification – we'll help prepare a ТЗ for your project and avoid typical mistakes.

Documentation for 1C-Bitrix Projects

The developer quit. The new one opens init.php with 2000 lines. It reveals 47 event handlers via AddEventHandler, a chain of agents in b_agent, and a custom module without a single comment. Figuring it out takes a month. Documentation turns that month into three days. We create it for 1C-Bitrix projects: from architectural diagrams to step-by-step instructions for the content manager.

Documentation cuts new developer onboarding time by 60% — from three weeks to one. Without it, every second project faces downtime when updating the core or when 1C exchange fails. Over 10 years of Bitrix development and 50+ documented projects back our standard. Get a consultation: we estimate the scope of work within one day.

Why is documentation critical?

Specific situations we see in every second project:

• Core update — the developer runs bitrix/tools/upgrade.php. The update overwrites modified files in /bitrix/components/bitrix/. Nobody knows which components were changed. The site breaks. Rollback from backup takes 4 hours.
• Exchange with 1C — the agent CCatalogImport::PreGenerateXML fails with an error. The setup is non-standard. Who changed the property mapping? Without documentation — half a day of reverse engineering.
• New contractor — the team gets a project with 12 highload blocks without description, custom tables b_custom_order_log and b_product_sync_history. Their purpose and connections to information blocks are undocumented. This delays onboarding by two weeks.
• Team growth — each new developer spends three weeks chasing “the one who knows” instead of opening the documentation and working.

The Bitrix Documentation Guide notes that well-documented projects experience 50% fewer critical incidents. Structured documentation reduces debugging time by 40% compared to ad-hoc notes. It also saves clients an average of $8,000 per year on developer onboarding and cuts downtime-related costs by $3,000 per incident.

How to structure documentation for developers?

Follow these steps to create comprehensive documentation:

1. Audit the project — inspect init.php, b_agent, AddEventHandler calls, custom components, and modified core files.
2. Map data structures — document all information blocks, highload blocks, custom tables, and their relationships.
3. Document custom code — components, modules, events, agents, and integrations.
4. Write user manuals — step-by-step guides for content managers and administrators.
5. Produce operational regulations — deployment, backups, core update, and incident response.

Technical documentation

For developers and DevOps — the internal structure of the project:

Architecture:

• Used Bitrix modules (sale, catalog, iblock, main, custom)
• Request path: HTTP → nginx → urlrewrite.php → component → template → response
• Server infrastructure: configuration, topology, load balancing

Data structure — most critical part:

• Information blocks: types (IBlock::TYPE_ID), sections, properties (PROPERTY_CODE), connections between information blocks via a property of type “Link to elements”
• Highload blocks: table b_hlblock_entity, purpose of each block, field structure, user fields (UF_*), indexes
• Custom tables in the database — why created, DDL, connections with b_iblock_element, b_sale_order and other standard tables
• Trade catalog: price types (b_catalog_group), warehouses (b_catalog_store), basket rules (b_sale_discount)

Custom developments:

• Components in /local/components/ — purpose, class.php, input parameters (.parameters.php), templates, dependencies
• Modules in /local/modules/ — API, events, installation scripts
• Event handlers — list of all AddEventHandler/registerEventHandler with description: which event, what it does, criticality
• Agents (b_agent) — schedule, functionality, which ones cannot be stopped (1C exchange, newsletters, cart cleanup)
• Modified core files — complete list. When updating bitrix/ these files will be overwritten

Integrations:

• Exchange with 1C: settings of the catalog module → “Exchange with 1C”, CommerceML format, CCatalogImport schedule, property mapping, pitfalls (encodings, timeouts, import.xml size)
• Payment systems: handlers in sale.handlers, operation modes (test/live), callback URLs
• Delivery services: profiles in sale.delivery, calculation algorithms, API keys
• CRM, marketplaces, external APIs: endpoints, authentication mechanisms, synchronization frequency

User instructions

For content managers and administrators:

Content manager guide:

• Catalog management: creating information block elements, filling properties, working with sections. Which fields are required, which affect display on the site
• Images: allowed sizes (is auto-resize configured?), formats, upload process for DETAIL_PICTURE and PROPERTY_GALLERY
• Promotions and discounts — how to set a basket rule in “Marketing” → “Basket rules” without breaking pricing. Test via a test order

Administrator guide:

• Users: groups (b_group), access rights to modules and information blocks
• Order processing: statuses (b_sale_status), payment, returns
• Backup via “Settings” → “Backup” — with the caveat that for large projects the standard backup may not suffice

Format:

• Step by step with numbering
• Screenshots with annotations — arrows, highlights, captions
• FAQ from real questions collected during training
• Video instructions for non-trivial operations (on request)

API documentation

For projects with custom REST API — we describe all endpoints: method, URL, purpose, parameters (required/optional), response format. Authentication: token retrieval mechanism, TTL, refresh. Rate limiting: limits, HTTP codes on exceed. Examples — working cURL commands, not theoretical. Tools: Swagger/OpenAPI (according to REST API standard) and Postman Collection for testing.

Architectural diagrams

One diagram replaces 10 pages of text. Formats: Draw.io, Mermaid (versioned in Git), PlantUML.

• Infrastructure — servers, networks, load balancer, DB (master-slave), Redis, CDN. Physical and logical topology
• Components — Bitrix modules, custom components in /local/, external services, connections
• ER diagram — tables b_iblock_element, b_sale_order, highload blocks, custom tables. Fields, connections, indexes. Especially critical for custom tables not in Bitrix documentation
• Data flows — how information moves between Bitrix, 1C, marketplaces, CRM, payment systems
• Site map — what is an information block, what is a static page, what is a custom section on a component

Operational regulations

Deployment:

• Step-by-step instructions for staging and production
• Post-deployment checklist: check main page, catalog, checkout, 1C exchange
• Rollback procedure — which symlink to switch, which DB backup to restore

Backups:

• Schedule: database, upload/, configurations
• Where stored and for how long
• Restoration procedure — tested, not theoretical
• Test restoration once a month

Core update:

• Staging → testing → production. Strictly in that order
• Check compatibility of custom components and modified core files
• bitrix/updates/ — what was updated

Incidents:

• Classification: site unavailable / 500 errors / 1C exchange broken / slowdown
• Contact persons and areas of responsibility
• Action templates for each type

What is included in the work

We prepare a complete documentation package:

• Technical documentation describing architecture, data structure, custom developments, and integrations
• User instructions for content managers and administrators
• API documentation in Swagger/OpenAPI format with Postman collection
• Architectural diagrams (infrastructure, ER diagrams, data flows)
• Operational regulations (deployment, backups, core update, incidents)
• Placement in Confluence, GitBook, Notion, or Wiki with access restrictions
• Accuracy guarantee — we update documentation with every significant change

Timelines

Order documentation turnkey. Contact us for a free assessment of your documentation needs — we will evaluate your project in one day. Outdated documentation is worse than none: it creates false confidence. We update with every significant change to keep information accurate.