Reports & Documents

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"
  }
}

Pictures and files in the report text

The text of a report lives in its own .md file next to document.json. Put a picture, an export or a document into the report’s own folder and reference it in the text with an ordinary link — ![chart](chart.png) or [export](report.pdf). A picture is shown right in the report, and anything else the reader downloads on click. That is how a process diagram, a screenshot of a dashboard or a finished export for a colleague lands next to the numbers, with everything needed in one place.

  • pictures (png, jpg, jpeg, gif, webp, avif, svg) appear in place, while everything else — PDFs, spreadsheets, archives — downloads on click;
  • the reference is signed and handed to the reader only temporarily: the address lives 12 hours and is re-issued on every open, so no permanently open link to the file is left behind;
  • only document text can be read through that address — tricks with .. are rejected, so nobody can walk out of the report folder;
  • external links, # anchors, links to other documents and everything written inside a code block stay exactly as written;
  • the viewer loads the rewritten text while the editor loads the original, so the links you wrote are never damaged;
  • if a file is deleted or renamed, the link stops working — move the report folder as a whole, together with its files.

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.

New documents and sidebar actions

The sidebar tells you what has appeared or changed: the name of such a document is highlighted until it is opened. A document counts as new or changed only by its content — if the file was merely copied into place, its date touched or its permissions changed, there is no highlight, while rewritten content is highlighted even when the file date has not moved. Changes made while the server was off are found at the next start-up as well.

  • every sidebar row — a document, a folder and the root Documents row alike — grows a three-dot button on hover, and the same menu opens on a right click;
  • Mark As Read clears the highlight: on a document its own, on a folder the folder and every document inside it, on the root row the whole tree at once;
  • Update Icon opens a search over the icon library and sets the chosen icon for that document; the icon lives in the document metadata, and the root document — the section’s home page — can have its own as well, defaulting to the folder icon;
  • the highlight is shared across all open tabs: mark a document as read in one, and it is gone in every tab.

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 /project/apps/analytics/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 documents and the template library — as you type, from the sidebar;
  • 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.

← Back to the documentation index