1. Overview

DoliConfiserie turns Dolibarr into a dedicated ERP for artisanal and industrial confectionery manufacturers. It covers the complete business cycle: purchasing, raw materials, recipes, production, quality, storage, sales, traceability and financial analysis.

1.1 Scope

·       Gummy sweets, hard candy, caramels, lollipops, dragees, marshmallows, nougats, fruit pastes, chewing gums, chocolates, seasonal and custom confectionery.

·       Raw material and packaging referentials, supplier management and goods-in control.

·       Versioned recipe engine with formulation, cost and nutritional data.

·       Full MRP/GPAO: planning, manufacturing orders, cooking, process steps, packing, palletising.

·       Food traceability: upstream (supplier), internal (manufacturing) and downstream (customer).

·       Quality management, laboratory, non-conformities/CAPA and HACCP (CCP, PRP, oPRP).

·       Maintenance (CMMS) with MTBF/MTTR, energy monitoring and industrial cost accounting.

·       Explainable statistical AI assistant and a 14-report reporting suite.

·       Industrial REST API.

1.2 Technical characteristics

Item	Value
Technical name	doliconfiserie
Module descriptor	modDoliConfiserie
Module number (numero)	522500
Rights class	doliconfiserie
Version	1.0.0
Editor	DoliResources (www.doliresources.com)
Licence	GNU GPL v3 or later
Minimum Dolibarr	16.0
Minimum PHP	7.1 (PHP 8.x compatible)
Database	MySQL / MariaDB
Dependencies	modSociete (Third parties), modProduct (Products)
Table prefix	llx_dcf_
Language key prefix	Dcf
Languages	fr_FR, en_US, es_ES, it_IT, de_DE

 

2. Architecture

2.1 Directory layout

Path	Contents
core/modules/modDoliConfiserie.class.php	Module descriptor: numero, rights, menu tree, init()/remove()
core/boxes/box_doliconfiserie.php	Home-page summary widget
class/dcf*.class.php	26 business objects, each extending CommonObject
class/api_doliconfiserie.class.php	REST API (class Doliconfiserie extends DolibarrApi)
class/doliconfiseriesampledata.class.php	Demonstration dataset generator and purge
lib/doliconfiserie.lib.php	Shared helpers, vocabularies, schema self-heal
lib/doliconfiserie_objects.php	Generated object registry (single source of truth)
lib/doliconfiserie_menu.php	In-page tab bar and left-menu activation
lib/doliconfiserie_page.php	Page chrome helpers
objectlist.inc.php / objectcard.inc.php	Generic list and card engines driven by the registry
dcf*_list.php / dcf*_card.php	Thin stubs (2 lines) delegating to the generic engines
dashboard.php, ai.php, traceability.php, reporting.php	Bespoke pages
admin/setup.php, admin/about.php	Configuration and about pages
sql/llx_dcf_*.sql, *.key.sql	Table definitions and indexes
langs/<lang>/doliconfiserie.lang	587 keys per language, all Dcf-prefixed
css/doliconfiserie.css.php, js/doliconfiserie.js.php	Confectionery styling and front-end behaviour

2.2 Registry-driven design

Every business object is declared once in the generated registry lib/doliconfiserie_objects.php (class, table, picto, menu label, hub flag, parent link and field definitions). The generic list and card engines read that registry, so a list page is a two-line stub. This keeps the 26 objects consistent and makes the schema, the classes, the pages and the language keys impossible to drift apart.

2.3 Design rules enforced in the code

·       Every language key carries the Dcf prefix. Dolibarr merges all active modules into a single tab_translate and the last load wins, so an unprefixed generic key (Ref, Qty, Status) silently renders another module's wording. Verified: zero collisions against all other installed modules and against Dolibarr core.

·       No local variable may be named $conf, $db, $user or $langs in a page: assigning $conf overwrites the global Conf object and every later getEntity() silently returns nothing, blanking sections at HTTP 200 with no error.

·       A missing cost or sale price is treated as UNKNOWN, never as zero: margin aggregates filter on cost_unit > 0 AND sale_price > 0, otherwise uncosted rows report a fictitious 100% margin.

·       Production yield is averaged over completed orders only: a half-finished order has no meaningful yield.

·       Conformity is always derived from the record's own tolerance band, never defaulted to conform.

·       Icons are restricted to Font Awesome 5 Free names, which is what Dolibarr bundles; FA6-only names render as empty squares.

·       table_element carries no llx_ prefix; SQL files use the literal llx_dcf_ prefix.

·       An ensureSchema() self-heal runs after _load_tables(): Dolibarr only ever CREATEs tables and never ALTERs them, so upgrades would otherwise miss new columns.

 

3. Database

The module ships 26 tables. Every table carries the standard Dolibarr envelope: rowid, entity, status, date_creation, tms, fk_user_creat, fk_user_modif and import_key (used to tag and purge the demonstration dataset). Column counts below are read from the live schema.

Table	PHP class	Columns	Hub
llx_dcf_cooking	Dcfcooking	25
llx_dcf_cost	Dcfcost	27
llx_dcf_energy	Dcfenergy	22
llx_dcf_formulation	Dcfformulation	23
llx_dcf_haccp	Dcfhaccp	27
llx_dcf_labtest	Dcflabtest	30
llx_dcf_line	Dcfline	19
llx_dcf_lot	Dcflot	25	Yes
llx_dcf_machine	Dcfmachine	28
llx_dcf_maintenance	Dcfmaintenance	24
llx_dcf_nonconformity	Dcfnonconformity	26
llx_dcf_operation	Dcfoperation	20
llx_dcf_order	Dcforder	29	Yes
llx_dcf_packing	Dcfpacking	24
llx_dcf_packitem	Dcfpackitem	22
llx_dcf_pallet	Dcfpallet	21
llx_dcf_planning	Dcfplanning	22
llx_dcf_process	Dcfprocess	26
llx_dcf_quality	Dcfquality	25	Yes
llx_dcf_rawmaterial	Dcfrawmaterial	26	Yes
llx_dcf_reception	Dcfreception	25	Yes
llx_dcf_recipe	Dcfrecipe	32	Yes
llx_dcf_recipe_line	Dcfrecipeline	18
llx_dcf_shipment	Dcfshipment	25
llx_dcf_storage	Dcfstorage	22
llx_dcf_supplier	Dcfsupplier	21	Yes

3.1 Main entity relationships

·       dcf_supplier 1-N dcf_rawmaterial, dcf_packitem, dcf_reception; dcf_supplier N-1 llx_societe (native third party).

·       dcf_rawmaterial 1-N dcf_reception; each accepted reception issues an internal lot_code that anchors upstream traceability.

·       dcf_recipe 1-N dcf_recipe_line (ingredients), dcf_operation (routing), dcf_formulation (simulations), dcf_planning, dcf_order.

·       dcf_order 1-N dcf_cooking, dcf_process (manufacturing steps), dcf_packing, dcf_quality, dcf_labtest, dcf_nonconformity, dcf_cost.

·       dcf_order 1-1 dcf_lot (finished lot); dcf_lot.parent_lots holds the comma-separated upstream raw lot codes.

·       dcf_packing 1-N dcf_pallet; dcf_lot 1-N dcf_shipment; dcf_shipment N-1 llx_societe (customer).

·       dcf_machine N-1 dcf_line; dcf_machine 1-N dcf_maintenance, dcf_energy, dcf_cooking, dcf_process.

·       dcf_storage N-1 llx_entrepot (native warehouse) for multi-warehouse setups.

 

4. Functional modules

Object	Class	Purpose
dcfsupplier	Dcfsupplier	Raw material / packaging suppliers, certification, rating, claims
dcfrawmaterial	Dcfrawmaterial	Raw materials in 14 families, allergens, origin, stock, shelf life
dcfreception	Dcfreception	Goods-in with control, supplier lot, internal lot code, DLC/DDM
dcfpackitem	Dcfpackitem	Packaging: bags, boxes, cartons, labels, film, jars, pallets
dcfrecipe	Dcfrecipe	Versioned recipes: process, yield, cost, nutrition, allergens
dcfrecipeline	Dcfrecipeline	Recipe ingredient lines with percentage and line cost
dcfformulation	Dcfformulation	Scale-up, variants, cost optimisation, new-product simulation
dcfoperation	Dcfoperation	Operating routes (step, machine, duration, temperature)
dcfmachine	Dcfmachine	Machines in 8 families, OEE, availability, MTBF, MTTR
dcfline	Dcfline	Production lines, capacity, operators, OEE
dcfplanning	Dcfplanning	Production planning, shift, priority, line load
dcforder	Dcforder	Manufacturing orders, 6-state lifecycle, yield, scrap
dcfcooking	Dcfcooking	Cooking cycles: program, temperature, Brix, conformity
dcfprocess	Dcfprocess	Manufacturing steps: mixing, dosing, moulding, cooling, coating, drying
dcfpacking	Dcfpacking	Packing runs, net weight, barcode, DLC
dcfpallet	Dcfpallet	Palletising, cartons, layers, SSCC
dcflot	Dcflot	Traceability lots: raw, intermediate, finished; parent chaining
dcfstorage	Dcfstorage	Storage zones, temperature band, occupancy, stock value
dcfquality	Dcfquality	Quality controls at 4 stages with tolerance band
dcfnonconformity	Dcfnonconformity	Non-conformities and CAPA: root cause, corrective, preventive
dcflabtest	Dcflabtest	Laboratory: texture, colour, humidity, weight, taste, micro, stability
dcfhaccp	Dcfhaccp	HACCP plan: CCP/PRP/oPRP, hazard analysis, criticality, deviations
dcfmaintenance	Dcfmaintenance	Preventive/corrective/predictive interventions, spare parts, downtime
dcfenergy	Dcfenergy	Electricity, gas, water, refrigeration, steam; cost and CO2
dcfcost	Dcfcost	Industrial cost sheets and margin by family
dcfshipment	Dcfshipment	Customer shipments closing the downstream traceability chain

 

5. Workflows

5.1 Manufacturing order lifecycle

planned → launched → inprogress → (paused) → done, with cancelled available at any point. The lifecycle is stored language-independently in dcf_order.order_status and rendered through the dcfOrderStatuses() vocabulary, so the kanban and the reports never depend on a translated string.

5.2 Production workflow

·       Planning assigns a recipe to a line for a period, with quantity, shift and priority.

·       A manufacturing order is created from the recipe; the operating route provides the step sequence.

·       Raw material lots are consumed; their codes are recorded in dcf_lot.parent_lots of the finished lot.

·       Cooking is recorded (program, target vs reached temperature, Brix, duration); conformity is derived from the deviation to the target.

·       Process steps record input, output and loss quantities per step, with machine, temperature and operator.

·       Quality controls are recorded at in-process and finished-product stages against their tolerance band.

·       Packing consumes a packaging item and produces barcoded units with a DLC; pallets group them with an SSCC.

·       The finished lot is created and linked back to the order; shipments link it to the customer.

5.3 Traceability workflow

One search (by lot, product, customer, supplier, date or manufacturing order) resolves the lot and renders three chains: upstream (parent lots → receptions → raw materials → supplier, origin, allergens), internal (order → recipe version → steps → controls) and downstream (packing → shipment → customer, plus child lots). The same chain is exposed as JSON at GET /lots/{id}/traceability.

5.4 Quality and HACCP workflow

·       A control stores its measured value together with its own limit_min/limit_max; conformity is computed, never assumed.

·       A non-conformity records severity, defect family, impacted quantity, cost, root cause, corrective and preventive action, owner and closure date.

·       HACCP points carry severity and probability; criticality is their product. Deviations increment nb_deviations and surface on the dashboard.

·       Lot status (free, quarantine, blocked, consumed, shipped) gates what can be shipped.

 

6. REST API

Base URL: <dolibarr>/api/index.php/doliconfiserie/ — the URL segment is the lowercased class name (class Doliconfiserie). The Dolibarr API module must be enabled and the calling user must carry an api_key, passed in the DOLAPIKEY header.

Method	Route	Description
GET	rawmaterials	List raw materials (filter: family).
GET	recipes	List recipes (filter: validated).
GET	recipes/{id}/formulation	Formulation engine: scale every ingredient and cost to a target batch size.
GET	orders	List manufacturing orders (filter: status).
POST	orders/{id}/production	Declare production from a shop-floor terminal; recomputes yield and status.
POST	cookings	Record a cooking cycle from a PLC; conformity derived from DCF_COOKING_TEMP_MAX.
POST	controls	Record a quality control; conformity derived from the tolerance band.
GET	lots	List traceability lots (filter: lottype).
GET	lots/{id}/traceability	Full upstream / internal / downstream traceability chain as JSON.
GET	kpi	Production, quality, stock and finance KPIs.

6.1 Security

·       The API class declares @access protected and @class DolibarrApiAccess {@requires user,external}. These are Restler directives, not documentation: without them the class is public, authentication never runs and every route fails.

·       The authenticated caller is DolibarrApiAccess::$user. In the REST context the global $user is a blank User object and would deny every route, including for administrators.

·       Every route is guarded by its rights group. An invalid key returns 401; a missing right returns 403.

·       Sort fields are whitelisted against SHOW COLUMNS because $sortfield lands in the SQL unquoted.

6.2 Example

GET /api/index.php/doliconfiserie/recipes/12/formulation?target=600

Returns the recipe, the applied scale_factor, every ingredient line with qty_scaled and cost_scaled, plus cost_total and cost_unit for the target batch.

 

7. Dolibarr integration

Native area	Integration
Third parties (Societe)	Suppliers (dcf_supplier.fk_soc) and shipment customers (dcf_shipment.fk_soc, dcf_lot.fk_soc)
Products	Raw materials, recipes, orders, lots and cost sheets may reference a product (fk_product)
Warehouses (Entrepot)	Storage zones may map to a native warehouse (dcf_storage.fk_entrepot)
Stocks	Raw material and packaging stock levels with reorder points
Users	Order and line managers (fk_manager), record authorship
Permissions	10 rights groups x 3 levels + reporting + admin = 32 rights
Accounting / analytics	Through native third parties and products
Projects, Agenda, ECM	Available on cards through the standard Dolibarr mechanisms
Multi-company	Every table carries entity; all queries filter with getEntity()
Barcodes / lots	dcf_packing.barcode, dcf_pallet.sscc, full lot model
REST API	Dedicated API class exposed under /api/index.php/doliconfiserie/
Boxes	Home-page widget box_doliconfiserie

 

8. Configuration and demonstration data

8.1 Configuration constants

Constant	Default	Purpose
DCF_SUGAR_PRICE	0.85	Default sugar price per kg
DCF_DEFAULT_CURRENCY	EUR	Default currency
DCF_DLC_ALERT_DAYS	30	Days before expiry that a lot is flagged
DCF_DLC_AUTO_BLOCK	1	Automatically block expired lots
DCF_COOKING_TEMP_MAX	160	Maximum cooking temperature (conformity threshold)
DCF_HUMIDITY_MAX	18	Maximum allowed humidity (percent)
DCF_GERMS_MAX	10000	Maximum total flora (CFU per gram)

8.2 Demonstration dataset

The generator (DoliConfiserieSampleData) installs a realistic, FK-coherent dataset on first activation and can be reloaded or removed from the configuration page.

·       Every row is tagged import_key = 'DCFDEMO'; the purge removes only those rows plus the native third parties it created, and cascades to user-created children of demo parents so nothing is left orphaned on a dead foreign key.

·       A DATASET_VERSION guard replaces a boolean flag, so an improved dataset is re-seeded on upgrade instead of being skipped forever.

·       Business content is stored as literal strings, never $langs->trans() output: the generator also runs during CLI activation, before the language file is loaded, where trans() would persist the raw key.

·       Measured values are drawn inside their own tolerance band with an explicit ~3% reject rate, producing a ~99% conformity rate. Jittering around a nominal instead yields a ~68% rate, i.e. a plant that would be shut down.

·       The first manufacturing orders are forced to start today so the headline 'production today' KPI is never zero on a freshly seeded instance.

·       Content: 10 suppliers, 28 raw materials, 48 receptions, 10 packaging items, 12 recipes with 78 ingredient lines, 66 routing steps, 8 formulations, 13 machines, 4 lines, 6 storage zones, 16 plannings, 60 manufacturing orders, 48 cooking cycles, 384 process steps, 48 packings, 24 pallets, 72 lots, 90 quality controls, 12 non-conformities, 42 laboratory analyses, 8 HACCP points, 22 maintenance interventions, 60 energy readings, 24 cost sheets and 13 shipments.

 

9. Validation performed

The module was installed and exercised on a live Dolibarr 17.0.3 instance carrying more than 110 other custom modules. The following was asserted, not assumed:

Check	Result
Module number band free (build trees, installed modules, rights_def), re-checked at activation	Band 5225 free, owned solely by doliconfiserie
init() return value	1
Rights inserted vs declared	32 / 32 (a PK collision inserts N-of-M silently)
Menu entries	41
MAIN_MODULE_DOLICONFISERIE constant	Present
Tables created	26
Language key collisions vs other custom modules	0 of 587 (27,390 foreign keys compared)
Language key collisions vs Dolibarr core	0 of 587 (12,566 core keys compared)
Font Awesome icons resolvable in bundled FA5	All (an FA6-only control name correctly reported absent)
Pages returning HTTP 200, no fatal, non-empty title	32 / 32
Lists rendering real rows	All, zero 'no record found'
Dashboard	31 KPI cards, 10 charts, 0 empty placeholders
AI assistant	28 insights across 6 cards
Traceability	44 chain steps rendered
Reports rendering rows	14 / 14
Exports free of HTML entities (CSV, Excel, Word, PDF)	4 / 4, accents intact
Demo purge then reinstall	234 rows -> 0 -> 234; 3,805 other-module records untouched
Stored encoding (HEX byte test, not accent-insensitive LIKE)	Real UTF-8, no mojibake, no entities, no raw keys
REST API authentication	Invalid key -> 401; valid key -> 200
REST API write persistence	POST /orders/{id}/production persisted and recomputed yield
REST API conformity derivation	In-band -> conform; out-of-band -> nonconform

 

10. Support

DoliConfiserie is developed and maintained by DoliResources.

·       Editor: DoliResources

·       Website: www.doliresources.com

·       Copyright © 2026 DoliResources

·       Licence: GNU General Public License v3 or later