Event & Analytics Engine
The shared observability layer behind every other engine in TotalApp. It quietly records how long each operation took, whether it succeeded, and — for AI-powered steps — which model was used and what it cost, without ever slowing down the operation it's watching.
What Is the Event & Analytics Engine?
Every engine in TotalApp does real work — the Matrix Agent scores a vendor with an AI model, the Integration & Webhook Engine processes an incoming order, the Audit Agent reviews a presentation. Each of those operations has a story worth remembering: how long it took, whether it succeeded, and — if an AI model was involved — which one, and what it cost. Without a shared place to capture that story, every engine would have to invent its own answer to "was this healthy?", and nobody could ever compare usage or cost across the whole platform.
The Event & Analytics Engine is that shared place. It gives every other engine one simple instruction to follow after finishing a piece of work — "tell me what just happened" — and turns the incoming stream of those reports into a per-workspace history and a small set of ready-to-read numbers: how many operations ran, what fraction succeeded, how long they typically took, and how much AI usage cost.
The one rule this engine is built around, above everything else: recording what happened must never slow down the thing that happened. A Matrix Agent analysis that takes 2 seconds must still take 2 seconds whether or not this engine is watching — the recording step happens completely out of the way, after the real work has already finished and already responded to whoever was waiting on it.
In one sentence
Every other engine reports "I just finished this, it took this long, it cost this much" — and this engine quietly turns that stream of reports into a workspace's usage history and cost summary, without ever being in the critical path of the work itself.
How It Works — Record After the Fact, Never Block
Every recorded event follows the same lifecycle, regardless of which engine produced it:
| Stage | What happens |
|---|---|
| 1. Work Finishes | Another engine — say, the Matrix Agent finishing an AI scoring pass — completes its task and has already sent its result back to whoever was waiting for it. Only after that response is on its way does the engine turn to report what just happened. |
| 2. Report It | The engine hands over a short description of the operation — which workspace it belongs to, how long it took, whether it succeeded or failed, and (if applicable) which AI model was used and how many tokens it consumed. This handoff returns immediately; nothing about it waits on disk access or file I/O. |
| 3. Store in the Background | A moment later — genuinely a moment, on the next tick of the server's event loop — the report is written into that workspace's own history log, and if an AI model was involved, its cost is calculated and added to the record. |
Why does the timing matter this much?
If recording an event required waiting for a disk write to finish before the calling engine could continue, every operation in TotalApp would carry a small tax on top of its own work — and that tax would only grow as history accumulates. By making the report-and-forget so that the calling engine never waits for the write to finish, watching everything costs effectively nothing to the thing being watched. Even a slow disk or an unusually large history file can never make a Matrix Agent analysis or a webhook's processing feel slower.
Input — What Every Recorded Event Carries
Regardless of which engine produced it, every event recorded by this engine carries the same core pieces of information, plus optional AI-specific details when a model was involved:
Workspace Identifier
Which TotalApp workspace (tenant) this event belongs to. Every workspace's history and cost totals are kept completely separate from every other workspace's.
Source Engine
Which engine reported the event — the Matrix Agent, the Integration & Webhook Engine, the Audit Agent, or any future engine added to the platform.
Duration & Outcome
How long the operation took, and whether it finished successfully or failed — the two numbers every usage and health question ultimately comes back to.
AI Model & Token Usage (optional)
When the operation involved calling an AI model, which model it was and how many tokens were consumed for the request and the response — the raw numbers behind every cost figure this engine produces.
Reporting an event never fails loudly
If a report is missing an optional detail, or something goes wrong while writing it to history (an unlikely disk issue, for example), the engine absorbs the problem quietly rather than raising it back to whoever reported the event. The operation being watched has already completed and already told its own caller the result — a hiccup in recording that outcome afterward must never turn into a second, unrelated failure.
Output — Usage History and Cost Summaries
The engine exposes two views into what it has recorded — a running history, and a rolled-up summary:
| View | What it shows |
|---|---|
| Recent Activity | A list of individual recorded events, most recent first — which engine, what happened, how long it took, whether it succeeded, and any AI cost involved. Useful for spotting a specific failure or reviewing exactly what ran in the last few minutes. |
| Usage Summary | A rolled-up view for a chosen time window (the last 30 days by default): the total number of operations, what percentage succeeded, the total estimated AI cost in that window, the average time an operation took, and which AI model was used most often. |
An empty history is not an error
A brand-new workspace, or one that simply hasn't used any AI-powered features yet, has no recorded events at all. The usage summary for that workspace reports zero operations and zero cost rather than failing — there is nothing wrong, there is simply nothing to report yet.
How AI Cost Is Estimated
Whenever a recorded event includes an AI model name and its token usage, the engine looks up that model's published price (a small, cents-and-fractions-of-a-cent rate per thousand tokens, tracked separately for the request side and the response side) and calculates an estimated cost for that single operation. Locally-run models cost nothing to estimate, since they run on the workspace's own infrastructure rather than a paid API.
These per-operation estimates accumulate into the total shown in a workspace's usage summary — giving a running answer to "how much has AI usage cost this workspace this month" without needing to cross-reference anything outside TotalApp itself.
An estimate, not an invoice
These figures are calculated from TotalApp's own record of token usage and a published price list — they are a close, useful estimate for understanding usage patterns and spotting cost spikes, not a substitute for an actual billing statement from an AI provider. Treat them as a guide for "is this getting expensive," not as the final word on what was actually billed.
How End Users Actually Use It
Understanding Where AI Cost Comes From
A workspace admin reviewing a usage & cost view can see, at a glance, the total AI spend for the last 30 days, how many operations ran, and what fraction of them succeeded — turning "is our AI usage under control?" from a guess into an answer backed by real numbers.
Diagnosing a Specific Failure
When something goes wrong — a document audit that failed, a vendor score that never came back — the recent activity history shows exactly which operation failed, when, and (where available) why, without needing to dig through server logs.
Comparing Health Across the Platform
Because every engine reports through the same shared history, a single view can answer questions that would otherwise require checking each engine separately — like whether one particular kind of operation is failing more often than the rest, or which AI model is being relied on the most.
Where the Event & Analytics Engine Fits
This engine doesn't do domain work on its own — it listens to every other engine and turns their activity into something reviewable:
| Source Engine | What gets recorded |
|---|---|
| Matrix Agent | Every AI-powered scoring pass — vendor evaluation, lead scoring, compliance checks — is recorded with its outcome, duration, and which AI model produced the result. |
| Integration & Webhook Engine | Every webhook event that finishes background processing — successfully or after exhausting its retries — is recorded, giving visibility into integration health without checking each platform's activity log separately. |
| Audit Agent | Every document review — a presentation or PDF checked against brand or compliance guidelines — is recorded along with which AI model performed the review. |
A shared layer other engines are built to use, not a screen you configure
Unlike engines that have their own dedicated settings or workspace screen, this engine works entirely behind the scenes — other engines are simply written to report to it after they finish. Nothing needs to be turned on or connected for a given engine's activity to start appearing in a workspace's history; if an engine is wired to report events, its usage is already being tracked.