A document is a report or a dashboard: a grid of blocks with charts, tables, metrics and text. Documents form a folder tree, are stored as plain JSON files and update on screen in real time.
Document structure
Every document is described by a document.json file: the title, an array of blocks, variables, access permissions and metadata.
{
"title": "Document title",
"blocks": [],
"variables": {},
"permissions": { "access": "admin-only" },
"settings": {
"rangeSelector": false,
"timeframeSelector": false
},
"metadata": {
"created": "ISO8601",
"modified": "ISO8601",
"version": 1,
"tags": ["tag1"],
"icon": "filename.svg"
}
}Block help
A block is a name, a content type, a width in grid columns (1 to 24) and a height. You can attach a short explanation to a block: in view mode, a help icon appears next to the agent button, and clicking it shows a tooltip on how to read this chart and what to look at. In templates every block carries such an explanation, and metric tiles always do: the report explains itself, so you don’t have to retell it to colleagues in words.
Nesting and navigation
- documents form a folder tree — nesting is unlimited;
- you navigate the tree through breadcrumbs;
- document paths can contain variables — one template spawns a family of reports (details in Variables & Templates);
- moving and deleting documents is done right in the interface.
Report filters and parameters
You can give the report reader levers — not file editing, but ordinary controls in the header:
- Filters — one or several, for example region and channel. The list of values is set manually or taken from your own data, and you can pick one value or several at once;
- What-if fields — a number with a slider, a toggle, a date or a date range. Move the budget, the discount or the deadline — the linked blocks recalculate in place, without reloading the page;
- values are remembered per report, and a reset button brings back the original settings;
- only the blocks whose queries use the value are recalculated — the rest stay as they were and don’t load the database for nothing.
Drill-down, linked blocks and tabs
A report answers a clarifying question without taking the reader to another page:
- Click-to-drill — a click on a bar, point, sector, cell or map region sets a filter value: the report recalculates for that value, and a chip with the selected value appears in the header. The cross removes the selection — and everything comes back. This is how “sales dropped” unfolds into “dropped in this channel on these products”;
- Linked blocks — charts and tables of one report can be linked: hovering over a week, point or row highlights the same value in the neighboring blocks. No queries run — it is highlighting only, the report is not redrawn;
- Tabs per audience — one report can show different things to different readers: for example, a “Summary for the executive” tab with the key numbers and an “Analyst calculations” tab with the details. Shared blocks are visible on all tabs, and the data loads once — switching is instant;
- Alert state — a block can be linked to an alert rule, and the report shows whether the rule is calm or firing (details in the Alerts section).
Reports from templates
A ready-made report from the template library sits right in the template’s folder — no nested report subfolders. Next to it come demo data, preparation scripts and two text blocks at the end of the report: “Quick start” — how to read the report and what to click, and “Explanation” — a detailed description. Read them in order: “Quick start” first, “Explanation” very last.
The agent adapts a template to your data and installs the finished report into the “Documents” section — from there on it lives as an ordinary document.
Storage: JSON files
Documents are stored in /data/documents/ as JSON files. Which means: versioning in Git, manual editing in any editor, moving between instances by simply copying the folder.
Instant reload
- a file watcher on inotify tracks changes in document files;
- the document list updates on the fly — new and changed reports appear immediately;
- AI edits and manual JSON edits are visible on screen without a reload;
- block updates are broadcast to clients over SignalR/WebSocket.
Access permissions
admin-only— the document is visible to the administrator only;authenticated— to all signed-in users;public— public reports can be shown without sign-in: handy for external dashboards.
Metadata, search, import and export
- metadata: version, tags, icon, creation and modification dates;
- search across all documents — from the home screen;
- export a report: a ready PDF to send, or a ZIP archive of the whole document folder — to move to another instance;
- import from an archive: when moving someone else’s report, its data source names can be replaced with your own right away;
- “Best documents” and “Recent documents” on the home screen.