1. Executive Summary

Fiva is a premium theme-module that replaces the entire Dolibarr interface with a light, modern SaaS dashboard, without altering a single file of the Dolibarr core. It ships two complete professional demos, Fiva Analytics and Fiva eCommerce, that an administrator switches between from the configuration screen, with no re-installation, no file editing and no manual cache clearing.

Both demos share one visual shell — white sidebar, white top bar, near-white page background, white cards with soft shadows and hairline borders — and differ in what the dashboard measures and how it is laid out. Every figure displayed comes from the live Dolibarr database through the native ORM and the module system; nothing is hard-coded and no sample data is required.

Delivered package at a glance

 

 

2. Theme Overview

Fiva is not a CSS skin. A stylesheet alone can only recolour the markup Dolibarr already emits; it cannot create a categorised sidebar, a global search bar or a KPI dashboard. Fiva is therefore a complete theme-module that:

·       Injects its stylesheet and script on every page through the standard module_parts css/js declaration, so no template is patched.

·       Supplies its own menu manager registered via MAIN_MENU_STANDARD_FORCED, which rebuilds the navigation from the native menu tree — every module, permission and translation keeps working.

·       Renders its own dashboard at custom/fiva/index.php, reached through a main hook so the Dolibarr home page opens on it.

·       Dresses each page through authorised hooks (main, all, toprightmenu, searchform).

The consequence matters commercially: a Dolibarr upgrade does not overwrite anything Fiva owns, and disabling the module restores the previous interface instantly.

 

3. Design Objectives

·       Clarity before decoration. A working day is spent in this interface. Contrast, spacing and type scale are tuned for long sessions rather than for a screenshot.

·       Honest figures. A dashboard that overstates performance is worse than no dashboard. Comparisons are made like for like, and a metric whose base is too thin reports "not available" instead of a spectacular but meaningless percentage.

·       Graceful degradation. A widget whose source module is disabled explains what to enable; it never shows a silent zero, and it never runs a query against a table that does not exist.

·       Configurability without forking. Palette, sidebar, top bar, layout, cards, typography and dark mode are settings, not code changes.

·       Commercial redistributability. Every asset shipped is original: the logo mark, the welcome illustration and all iconography come from the theme itself or from the Font Awesome 5 Free set already bundled with Dolibarr.

 

4. UI/UX Philosophy

The interface follows three rules that are visible on every screen.

Information carries its own context

A number without a period, a comparison base or a unit is not information. Each KPI card therefore states its label, its value, its variation and the period the variation refers to. Where a variation cannot be computed honestly, the card says so.

Colour is never the only signal

Upward and downward variations differ by arrow glyph as well as by colour, so the meaning survives both colour-blindness and a monochrome print-out.

The shell stays still

Switching demo repaints the dashboard, not the navigation. The sidebar, the top bar and the page chrome remain identical, so the user never has to relearn where things are.

 

5. Fiva Analytics Demo

Fiva Analytics answers a commercial-performance question: how efficiently does the pipeline convert, what does it earn, and where does the business come from.

Composition

·       Four conversion KPI cards — conversion rate, conversion value, converted orders and subscribers gained, each on its own colour disc.

·       Website Analytics — a grouped monthly bar chart comparing turnover, gross margin and order value over the elapsed months of the current year, with week / month / year period selectors.

·       Email Send — a donut of e-mail delivery status, fed by the Emailing module.

·       Acquisition sources — share bars built on the native input-reason dimension.

·       Key ratios — four gauges: conversion, gross margin, collection rate and share of orders billed.

·       Top customers, overdue invoices and recent activity — three live lists, each row linking to the corresponding Dolibarr record.

 

6. Fiva eCommerce Demo

Fiva eCommerce answers a trading question: what was sold, what it earned, what is still owed and what is running out of stock.

Composition

·       Welcome banner — greeting, date, a link into the dashboard and an original layered-landscape SVG drawn by the theme (no third-party artwork).

·       Four horizontal KPI cards — subscribers gained, revenue generated, quarterly sales and orders received.

·       Revenue Summary — an area chart of the current year against the previous one, topped by net revenue, gross margin and outstanding figures.

·       Product and user tiles — new products, active users and products on sale.

·       Billing pipeline — invoices by status with count and amount, each bar linking to the matching filtered list.

·       Best sellers, recent orders and low stock — three live panels.

A note on the Browser Statistics panel

The reference mock-up shows browser-usage statistics. Dolibarr stores no user-agent data, so that panel would have to be fabricated. It is replaced by the billing pipeline — a real, well-populated distribution — and the panel names the dimension it displays. Inventing browser figures would have produced a prettier screenshot and a dishonest product.

 

7. Dashboard Architecture

One data layer serves both demos. Every query runs once, against the live database, scoped by getEntity() so multi-entity installations stay isolated. The active preset then decides which presentation is painted. Switching demo never changes a figure — only its layout.

Like-for-like comparison

The current period is almost always partial: on the 21st of a month, 21 days have elapsed while the previous month is complete. Comparing the two produces a mechanical collapse that is pure artefact. Fiva truncates the previous window to the same elapsed duration. Measured on the validation instance, the quarterly tile reported -82.4 % before this rule and -16.2 % after it; the second figure is the true one.

Unknown is not zero

·       A ratio whose population is empty reports "not available", not 0 %. A 0 % win rate on an instance where nothing has been decided yet reads as "we lose every deal".

·       Gross margin is computed only over invoice lines whose buying price is known. Treating a missing cost as zero would silently report a margin near 100 %.

·       A year-on-year comparison is shown only when the previous year holds a comparable base over the same elapsed window. On the validation instance the previous year held 22 invoices against 283, which would have printed "+1 893.9 %" — arithmetically exact and completely misleading. Fiva prints "not available" and states why.

 

8. KPI Cards

The signature card places a flat colour disc holding a white glyph beside a stacked label, value and variation, with a contextual caption underneath. The whole card is a link to the pre-filtered list that produced the number, so a KPI can always be audited in one click — and the list total matches the tile, because the link carries the same period and status filters as the query.

Available card styles

 

Each card may carry a title, value, period, variation, percentage, icon, badge, sparkline and a link to the detail. The variation colour follows the SIGN of the figure, never the palette: a green minus sign is a visual lie.

 

9. Sidebar Features

The sidebar is rebuilt from the native Dolibarr menu tree, which means it inherits every active module, every permission, every entity restriction and every translation automatically. It is never a static list.

·       Brand block, user avatar, name and role

·       Module search field

·       Categorised navigation with expandable sub-menus and active-state tracking

·       Live counter badges on the entries that carry pending work

·       Bookmarks (favourites) and recently visited records

·       Customise call-to-action linking to the theme configuration

Available modes

 

 

10. Topbar Features

The top bar keeps Dolibarr's native login block — search, entity selector, help, user menu — and restyles it, so multi-company switching and every third-party injection keep working. Fiva adds its own quick-action segment: pending actions, today's events and a direct link to the theme configuration, each with a live counter badge.

Variants: Light, Dark, Coloured, Gradient, Transparent, Fixed, Static, Floating and Compact. Icon and text colour are bound to the active surface rather than hard-coded, so every variant stays readable.

 

11. Global Search

A dedicated search page queries the objects a user actually looks for and returns typed results — type, icon, reference, label, status and a direct link — with the searched term highlighted. Results are filtered by the current user's read permissions and by entity, so search can never expose a record the user cannot open.

 

12. Analytics Features

·       Conversion rate orders raised per proposal, both sides drawn from the same population.

·       Conversion value average invoiced amount, stated with the invoice count it averages over.

·       Converted orders order count for the selected period, with a like-for-like variation.

·       Subscribers gained new customers and prospects created in the period.

·       Gross margin computed only where the buying price is known.

·       Collection rate paid share of everything invoiced.

·       Acquisition sources share by native input reason.

·       Top customers, overdue invoices, recent activity live, clickable lists.

 

13. eCommerce Features

·       Revenue generated turnover for the period, on the configured HT or TTC basis.

·       Quarterly sales current calendar quarter against the same elapsed window of the previous one.

·       Orders received order count with variation.

·       Net revenue, gross margin and outstanding the three figures that head the revenue chart.

·       Billing pipeline invoice count and amount per status, each a filtered link.

·       Best sellers drawn from invoice lines. Order lines frequently carry no product link at all on a real instance, which would leave the panel empty.

·       Low stock products below their alert threshold, with the threshold shown.

·       New products, active users, products on sale counter tiles.

 

14. Widgets

Below the Fiva panels, the dashboard embeds Dolibarr's native widget zone. Users add, hide and reorder those widgets by drag and drop, and Dolibarr persists the layout per user through its own box system — so the personalisation survives logout and is not a parallel mechanism the theme would have to maintain.

On a user's first visit the zone is seeded with a sensible default set (database statistics, open account balances, stock alerts, and the monthly invoice, order and proposal charts). The whole zone can be hidden from the configuration screen.

Fiva's own panels are shown or hidden according to the active demo and to module availability: only what the active demo needs is queried and rendered.

 

15. Charts and Data Visualization

All charts are inline SVG generated server-side. No charting library is loaded, no external request is made, and the rendering is identical whether or not JavaScript is enabled.

 

Two rules that keep charts truthful

·       One axis, one unit. An order count in the tens plotted beside turnover in the millions is flattened to an invisible hairline and compares nothing. Series shown together are expressed in the same unit.

·       Never plot an absent history as zero. When the previous year holds no comparable data, its series is omitted and the legend explains the omission, instead of drawing a flat line at zero that reads as a collapse.

 

16. Tables and Lists

Dolibarr's native lists are restyled rather than replaced, so sorting, filtering, pagination, multi-selection, column selection, import and export all keep working exactly as administrators and integrations expect.

Three densities are available — compact, normal and comfortable. Wide tables scroll inside their own container so the page itself never scrolls sideways.

 

17. Forms

Every native form control is restyled: text, numeric and currency fields, dates and times, select lists, autocomplete, checkboxes, radio buttons, switches, text areas, file upload and drag-and-drop, error and success messages, required-field marks and action buttons. Full compatibility with native Dolibarr forms is preserved: no markup is replaced, so custom-field and third-party form extensions continue to render.

 

18. Login Pages

Each demo carries its own login layout: an analytics-flavoured split screen for Fiva Analytics and a landscape hero for Fiva eCommerce, both on a light background with the theme's accents and an original illustration.

Both provide username, password, remember-me, password recovery, language selection, error messages, two-factor input where the instance enables it, a responsive layout and a dark variant. Authentication itself is untouched: the pages post to Dolibarr's native login mechanism, and no credential is ever handled by the theme.

 

19. Responsive Design

The layout adapts from large desktop screens down to portrait phones. The sidebar becomes a sliding drawer, the top bar simplifies, cards stack, charts rescale, tables scroll within their own container and touch targets grow.

Horizontal overflow is measured, not assumed: at both 900 px and 420 px the rendered document width equals the viewport width exactly, so no page scrolls sideways.

 

20. Dark Mode

Dark mode is a genuine second palette, not an inverted filter. It applies to the sidebar, top bar, page background, cards, tables, forms, charts, dropdowns, modals, notifications and the login pages.

It can be toggled from the top bar, enabled by default from the configuration screen, or set to follow the operating-system preference. The manual toggle is remembered in the browser's local storage, so it is per browser rather than per user account — stated here because the distinction matters when several people share a workstation.

 

21. Theme Configuration

A single configuration screen groups 43 settings in six sections. Every default is read from the same preset engine the stylesheet uses, so a reset can never restore a palette that differs from the one actually shipped.

 

Import and export

The whole configuration exports to a JSON profile and imports back. The importer validates every key against the settings catalogue with the same type rules the form applies: an unknown key, an out-of-list value or an over-long string is rejected and counted, never written. An uploaded profile is treated as data, never as instructions.

 

22. User Preferences

Settings can be saved at three scopes, selected before saving:

 

Reads resolve user first, then entity or global, then the shipped default. A personal choice therefore overrides the company setting for that person only, and survives logging out and back in. Switching off a boolean at user scope is written explicitly rather than left unset, so an individual "off" is never overruled by a company "on".

 

23. Accessibility

Contrast was measured, not estimated. An audit walks the rendered pages in a real browser, resolves each element's effective foreground against its actual background and computes the WCAG 2.1 ratio. The first run reported 49 insufficient pairs; all were corrected and the audit now reports none across the two dashboards, the configuration screen and a native list.

·       Vivid brand tints are kept for FILLS, where a graphical component needs 3:1, while text uses a deeper ink shade derived from the same colour — so the brand is intact and the text is legible.

·       Variation direction is carried by an arrow glyph as well as by colour.

·       Keyboard navigation and visible focus states are preserved from the native controls.

·       ARIA labels are emitted on icon-only links; decorative artwork is marked aria-hidden.

·       prefers-reduced-motion suppresses transitions and animations.

·       Touch targets meet the recommended minimum size on small screens.

 

24. Performance Optimization

·       Conditional loading. Only the active demo's resources are computed and served; the two demos are never loaded together.

·       No external dependency. No CDN, no charting library, no icon download. Charts are server-rendered SVG and icons come from the Font Awesome set Dolibarr already bundles.

·       Cache-busting on change. Saving the configuration bumps Dolibarr's interface revision, so a new palette is served on the next normal reload rather than after a forced refresh.

·       Correct caching during preview. While a demo preview is active the stylesheet is served no-store. Without it a browser holding demo A's stylesheet would repaint demo B's markup with it — correct HTML under the wrong chrome.

·       Guarded queries. A widget whose module is disabled runs no query at all; table existence is verified before any bespoke query.

 

25. Security Considerations

·       Permissions. Navigation, search and every dashboard link are built from the user's own rights; nothing exposes a record the user cannot open.

·       Entity isolation. Every query is scoped with getEntity(), so multi-company installations never leak across entities.

·       CSRF. Forms emit and post Dolibarr's native token; write actions are rejected without it.

·       Escaping. All dynamic output passes through Dolibarr's escaping helpers.

·       Input validation. Query parameters are filtered through GETPOST with explicit types; the demo selector and every select value are validated against a whitelist.

·       Import validation. Imported configuration profiles are validated key by key and value by value; anything unrecognised is rejected.

·       No secrets, no core modification. The theme stores no credential and writes to no Dolibarr core file.

 

26. Dolibarr Integration

Fiva detects which modules are enabled and offers only the widgets those modules can feed. Supported sources include third parties, contacts, prospects, products, services, stock, proposals, orders, invoices, payments, accounting, banks, margins, projects, tasks, agenda, users, emailing, point of sale, contracts, tickets, documents, purchasing and suppliers.

When a module is not active, the corresponding widget is hidden or shows an explicit explanation naming the module to enable, no query is executed, no PHP or JavaScript error is raised, and the surrounding layout stays balanced.

 

27. Dolibarr Compatibility

The module declares a minimum of Dolibarr 16 and PHP 7.0, and uses only documented theme, hook and module mechanisms, which are stable across the 16 to 21 range and beyond. It was developed and validated on Dolibarr 17.0.3 with PHP 8.

It works with native modules, with compliant third-party modules, in multi-entity installations, with user permissions, with dynamic menus, in left-to-right and right-to-left languages, and with native authentication. No Dolibarr core file is modified.

Compatibility with Dolibarr 20 and 21 is expected from the mechanisms used but was not executed on those versions during this validation — see Limitations.

 

28. Browser Compatibility

The interface relies on CSS custom properties, flexbox, grid and inline SVG, all supported by current versions of Chrome, Firefox, Edge and Safari.

Rendering was verified on Chromium (the engine behind Chrome and Edge) at desktop, tablet and mobile viewports on macOS. Firefox, Safari, Android and iOS were not exercised in this validation cycle; the manual verification procedure for them is given in the Technical Validation Report.

 

29. Technical Architecture

 

The preset engine is a plain library: it never bootstraps Dolibarr and never prints, so the stylesheet, the script, the dashboard, the menu manager and the configuration screen can all include it. Because the CSS defaults and the configuration defaults are literally the same array, the two cannot drift apart.

 

30. Folder Structure

The package contains 20 files, all under a single fiva/ folder, with no parent directory, no temporary file, no cache and no hidden system file.

fiva/

├── index.php                      Dashboard (data layer + both demos)

├── search.php                     Global search

├── README.md                      Overview and quick start

├── CHANGELOG.md                   Version history

├── admin/

│   └── setup.php                  Configuration screen

├── class/

│   ├── actions_fiva.class.php     Hook handlers

│   └── fiva_demo.class.php        Optional demo dataset helper

├── core/

│   ├── fiva_presets.php           Preset and design-token engine

│   ├── modules/

│   │   └── modFiva.class.php      Module descriptor

│   └── menus/standard/

│       ├── fiva_menu.php          Menu manager

│       └── fiva.lib.php           Sidebar and top bar rendering

├── css/fiva.css.php               Dynamic stylesheet

├── js/fiva.js.php                 Dynamic script

└── langs/                         7 language files

 

31. Installation Guide

Prerequisites

·       Dolibarr 16 or later (validated on 17.0.3)

·       PHP 7.0 or later (validated on PHP 8)

·       An administrator account

·       Unzipped module deployment enabled, or filesystem access to htdocs/custom/

Steps

1.     Sign in to Dolibarr as an administrator.

2.     Open Home > Setup > Modules/Applications, then the "Deploy/install external app" tab.

3.     Upload module_fiva-1.0.zip. Alternatively, unzip it so that the fiva folder sits directly inside htdocs/custom/.

4.     Find Fiva in the module list (Interfaces family) and switch it on.

5.     Open the module's configuration screen from the cog icon.

6.     Choose the demo — Fiva Analytics or Fiva eCommerce — and the save scope, then save.

7.     Reload any page: the interface is applied immediately.

Activating the module writes only its own configuration entries. Switching it off removes them and restores the previous interface.

 

32. Upgrade Guide

8.     Back up the database and the htdocs/custom/fiva folder.

9.     Export the current configuration to a JSON profile from the configuration screen.

10.   Replace the contents of htdocs/custom/fiva with the new version, or redeploy the new package over it.

11.   Open the configuration screen once. The theme bumps the interface revision so browsers load the new stylesheet on a normal reload.

12.   Verify the demo, palette and layout, and re-import the profile if anything was reset.

Settings are stored as configuration entries independent of the files, so an upgrade preserves them.

 

33. Customization Guide

·       Without touching code — palette, colours, font, sizes, radius, shadow, density, layout, sidebar and header variants, menu contents and dashboard options are all settings. A custom palette accepts explicit primary and accent colours.

·       Through a JSON profile — export a tuned configuration and import it onto other instances or entities.

·       By extending the preset engine — adding a demo means adding one entry to core/fiva_presets.php and one branch in index.php. Because the entry drives the palette, the layout, the login page and the configuration defaults at once, a new demo cannot diverge from its own tokens.

·       Through the design tokens — every surface, text level, border and chart colour is a CSS custom property, so a bespoke stylesheet can override individual tokens without redefining components.

 

34. Translation System

All user-facing strings go through Dolibarr's translation system. Keys are prefixed with Fiva so they cannot collide with another module's keys — a real hazard on installations carrying many modules, where a generic key resolves to whichever module loaded last.

 

Adding a language means copying langs/en_US/fiva.lang into a new locale folder and translating the values. Missing keys fall back to English rather than showing a raw key. A build-time audit verifies that every key used in the code exists in the reference file; it currently reports none missing.

 

35. Screenshots Description

34 screenshots are delivered, 17 per demo, captured at 1600 x 990 with a 2x device pixel ratio on a live Dolibarr instance holding real business data.

 

Each capture was asserted before being kept: never the login form, never an access-denied or record-not-found page, the expected demo actually applied (verified by reading the live palette and rail geometry from the DOM), and no horizontal overflow. No screenshot contains sensitive data.

 

36. Advantages

·       Two complete professional demos in one package, switchable without re-installation.

·       No Dolibarr core file modified — upgrades stay safe.

·       Figures come from the live database and are auditable in one click.

·       Honest metrics: like-for-like comparisons, and an explicit "not available" rather than a misleading percentage.

·       Graceful behaviour when modules are missing, with actionable explanations.

·       43 settings covering palette, layout, typography and dashboard behaviour.

·       Three-scope preferences: global, per entity, per user.

·       Measured WCAG 2.1 AA contrast across the audited pages.

·       No external dependency, no CDN, no tracking.

·       Configuration portable between instances as a validated JSON profile.

 

37. Limitations

Stated plainly, so that nothing in this document implies a test that was not run.

·       Browsers. Rendering was verified on Chromium at desktop, tablet and mobile viewports on macOS. Firefox, Safari, Android and iOS were not exercised.

·       Dolibarr versions. Validated on 17.0.3. Compatibility with versions 20 and 21 follows from the documented mechanisms used but was not executed on them.

·       Dutch and Portuguese. Those two files carry 406 of 601 keys. Untranslated keys fall back to English; they do not show raw keys.

·       Browser statistics. Dolibarr records no user-agent data, so that mock-up panel is replaced by the billing pipeline rather than fabricated.

·       Emailing and acquisition widgets. They require the Emailing module and the native input-reason field respectively. Without them the panels explain what to enable instead of displaying figures.

·       Dark-mode persistence. The manual toggle is stored per browser in local storage, not per user account.

·       Abandoned-cart widgets. Dolibarr has no native equivalent; they would require a compatible e-commerce connector.

 

38. Future Enhancements

·       Complete the Dutch and Portuguese translations to full parity.

·       Extend validation to Firefox, Safari, Android and iOS, and to Dolibarr 20 and 21.

·       Per-user dashboard layouts for the Fiva panels, alongside the native widget zone.

·       Additional demos built on the existing preset engine.

·       Optional connectors for e-commerce platforms to feed cart and channel widgets.

·       Scheduled PDF export of a dashboard.

 

39. Support and Maintenance

Fiva is published and maintained by DoliResources.

 

Maintenance covers corrective fixes, compatibility updates for supported Dolibarr versions, and the enhancements listed in the previous section. When reporting an issue, please state the Dolibarr version, the PHP version, the active demo, the browser, and attach the exported JSON configuration profile: it reproduces the exact visual state in one step.