Understanding the Tracking Tables
Lex App quietly maintains a small set of "behind-the-scenes" tables that capture what your application did, when it did it, and who asked for it. You don't have to write code to populate them — they fill themselves up as people click around the app, run calculations, and edit records.
This page explains, in plain language, what each of these tables is for and how to judge whether the value they provide is worth the storage they consume.
flowchart LR
A["A user clicks
Save / Delete"] --> B["Audit Log
(who asked)"]
A --> C["History Table
(what changed)"]
D["A calculation runs"] --> E["Calculation Log
(what happened)"]
B --> F["Audit Log Status
(did it succeed?)"]The Four Tables at a Glance
Table | Answers the Question | Created When |
|---|---|---|
Calculation Log | "What did the calculation do, step by step?" | A calculation runs |
History Tables | "What did this record look like at any point in time?" | A record is created, updated, or deleted |
Audit Log | "Who asked for this change, and what did they send?" | An API operation is performed (create / update / delete) |
Audit Log Status | "Did that request actually succeed?" | Together with each Audit Log entry, then updated as the operation finishes |
1. Calculation Log
What It Is
Every time a calculation runs, Lex App writes a structured, Markdown-formatted log to the Calculation Log table. The log captures whatever the calculation reports about itself — progress messages, headings, tables, DataFrames, JSON snippets, code blocks, and so on — produced through the LexLogger API.
Each entry is automatically linked to:
- The calculation run that produced it
- The record the calculation was operating on
- Its parent calculation (if it was triggered by another calculation)
Intended Use
- Show your work. When a calculation produces a number, the log explains how it got there — which inputs it used, which intermediate values it computed, which branches it took.
- Live progress. While a long calculation is running, end users can open the Calculation Log panel and watch progress unfold in real time.
- Hierarchical visibility. When a parent calculation triggers child calculations, the log tree mirrors that structure, so reviewers can drill from the top-level result into each sub-step.
- Exportable evidence. Any calculation log can be exported as a PDF — useful for compliance files, model validation reviews, or simply emailing a result to a colleague.
Benefits
- Trust in the numbers. Decision-makers can see why a result is what it is, not just the final value.
- Faster debugging. When a result looks wrong, the log usually shows exactly where things went off.
- Self-service auditing. Business users can answer "how was this computed?" without asking a developer.
- Regulator-friendly artefacts. Rich Markdown output (tables, DataFrames) makes the log readable as a standalone document.
When the Value Is Highest
- Calculations are non-trivial (multiple steps, branching logic, aggregations).
- Results feed into reports, financial figures, or external decisions.
- You operate in a regulated environment where "show your work" is a requirement.
When the Value Is Lower
- Calculations are trivial passthroughs or simple arithmetic.
- Results are short-lived and not consumed downstream.
2. History Tables
What They Are
For every tracked model in your application, Lex App maintains a parallel History table (e.g., Employee is shadowed by HistoricalEmployee). On every create, update, and delete, a full snapshot of the record is appended to the history table.
Each historical row contains:
- All field values at that moment (not just the changed ones)
valid_from/valid_to— the time window during which this version was the current onehistory_type— created (+), changed (~), or deleted (-)history_user— who triggered the changehistory_change_reason— an optional free-text note
This page only covers the standard, user-visible history layer. Lex App also has an internal second layer used for advanced bitemporal scenarios; it is not exposed in normal user views and is not relevant to evaluating day-to-day value.
Intended Use
- Time travel. Reconstruct exactly what any record looked like at any past moment.
- Change inspection. Compare two versions of the same record to see what was changed and by whom.
- Recovery. Restore lost or accidentally overwritten values without resorting to backups.
- Activity reports. Answer questions like "how many price changes did we make last quarter?" or "which records did this user touch?".
Benefits
- Total auditability of data. Nothing is ever silently overwritten — every prior version is preserved.
- Built-in undo evidence. Even after a delete, the last-known state of the record is available.
- Zero configuration. History is on by default for every business model; you don't need to opt in or write extra code.
- Trust during migrations. When data is reshaped or imported, you can prove the before/after state.
When the Value Is Highest
- Records change over time and the previous values matter (prices, statuses, ownership, contracts, configurations).
- You face audits, disputes, or regulatory reviews where "show me what this looked like on date X" is a real question.
- Multiple users edit the same data and you need accountability per change.
When the Value Is Lower
- The model holds purely transient data (uploads, scratch tables, computed staging) — these are typically excluded from history anyway via the
untracked_modelsconfiguration, so they incur no overhead.
Cost Considerations
History tables grow with every change. For models edited frequently, the history table can become much larger than the live table over time. This is normal and expected — but it's worth knowing when you size storage and plan retention.
3. Audit Log
What It Is
Every API operation that creates, updates, or deletes a record is recorded in the Audit Log table. Where the History tables capture what the data looked like, the Audit Log captures the request itself — the who, the when, and the exact payload that came in.
It also acts as a bridge between user activity and calculation activity: if a change was made by (or inside) a calculation, the audit entry carries a pointer to that calculation's log tree, so a single audit record is enough to walk back to the full reasoning behind the change.
Each entry stores:
Field | What It Means |
|---|---|
| When the request was received |
| The user who performed the action |
| Which model was targeted (e.g., |
|
|
| The full JSON body that was sent, or the final state of the record after the operation |
| A pointer back to the affected record, so you can jump from the audit entry to the live record |
| If the change was triggered by — or executed inside — a calculation, this is the ID of that calculation's log tree. Click it to open the full Calculation Log and see exactly what the calculation did to produce this change. Empty for plain user edits made directly through the UI or API. |
Intended Use
- Security auditing. Prove who did what, when, and against which record.
- Forensics. When something looks wrong, see the exact payload that was submitted — including fields the user might claim they didn't send.
- Per-record activity feed. Each record's detail page shows its own audit log, so you can review the full request history for a single object.
- Bulk-operation transparency. Bulk updates and deletes produce one audit entry per affected record, so even mass changes remain individually accountable.
- From "what was changed" to "why it was changed". When the
calculation_idis filled in, the audit entry stops being just a record of a request and becomes the entry point into the full calculation story. One click takes you from "this field was set to 1,500 by user X" to the entire Calculation Log tree showing the inputs, the steps, and any nested sub-calculations that led to that number. This is how user-facing accountability and computational transparency are linked together in Lex App.
Benefits
- Accountability that survives the data. Even if a record is later deleted, the audit log preserves who created it, who changed it, and who removed it.
- Faster incident response. A complete record of the request (not just the result) makes it possible to reconstruct what a user actually did.
- Compliance ready. Many frameworks (SOX, GDPR, ISO 27001, internal IT controls) require a "who did what" log. This table is that log.
When the Value Is Highest
- The application is used by many people, especially across roles and permissions.
- You need to satisfy security, compliance, or internal-control requirements.
- Records are valuable enough that disputes about authorship or intent are realistic.
When the Value Is Lower
- The system is used by a single trusted operator with no compliance obligations.
4. Audit Log Status
What It Is
Every Audit Log entry is paired with an Audit Log Status entry that tracks the outcome of the operation. Statuses move through a small lifecycle:
flowchart LR
A["🟡 Pending"] -->|operation succeeds| B["🟢 Success"]
A -->|operation fails| C["🔴 Failure"]- Pending — the audit log was written before the operation executed.
- Success — the operation completed; the payload is updated to reflect the final, persisted state.
- Failure — the operation failed; the full error traceback is stored alongside the status.
Intended Use
- Capture failures, not just successes. Because the audit log is created before the operation runs, even operations that crash, get rejected by validation, or are blocked by permissions are recorded with their reason for failure.
- Distinguish "user tried" from "user did". The status tells you whether a request actually changed the data, or merely attempted to.
- Diagnose recurring errors. Patterns of failed operations (same user, same resource, same error) point to UI bugs, missing permissions, or training gaps.
Benefits
- Complete picture. The Audit Log says what was attempted; the Status says what actually happened.
- Security signal. Repeated
failureentries — for example, many denied delete attempts — can indicate misconfigured permissions or even malicious probing. - Developer feedback. Stored tracebacks let engineers reproduce and fix issues without needing the user to re-trigger them.
When the Value Is Highest
- You care about attempted actions, not only successful ones (security, compliance, abuse detection).
- You support many users and want to spot recurring errors centrally.
When the Value Is Lower
- You only ever review successful changes and treat failures as "someone will retry" — but even then, the status is small and cheap to keep.
How They Work Together
These four tables are designed to overlap intentionally. Each one answers a slightly different question, and together they form a complete picture of the application's behaviour.
Question | Best Answered By |
|---|---|
"How did this calculation arrive at this number?" | Calculation Log |
"What did this record look like last Tuesday?" | History Tables |
"Who edited this record, and what did they send?" | Audit Log |
"Did that edit actually go through, or did it fail?" | Audit Log Status |
"Why did the system reject this user's request?" | Audit Log Status (traceback) |
"Was the previous value of this field correct?" | History Tables + Calculation Log (if the value was computed) |
Evaluating Their Value for Your Use Case
A simple way to decide how much weight to put on each table:
Do you have to defend your numbers to anyone? (Auditors, regulators, customers, leadership.)
- Yes → Calculation Log and History Tables are high-value.
Do multiple people edit the same data?
- Yes → Audit Log is high-value.
Do you need to distinguish attempts from successes?
- Yes → Audit Log Status is high-value.
Is "what did this look like before?" a question that ever comes up?
- Yes → History Tables are high-value.
If the answer to all four is "no", you can safely treat these tables as background insurance — they cost very little and quietly protect you against the day someone asks a question you didn't expect.
Per-Record Views: The Same Tables, Auto-Filtered
Everything described above lives in three large, application-wide tables. Useful for administrators — but overwhelming for an end user who only cares about one record.
To bridge that gap, every record's detail page exposes the same tables, automatically filtered down to that single record. No queries to write, no IDs to copy, no joins to remember. You open a record, click a tab, and you see only the rows that belong to it.
flowchart LR
A["Open record #42"] --> B["History Tab
(HistoricalX rows where id = 42)"]
A --> C["Audit Log Tab
(AuditLog rows where object_id = 42)"]
A --> D["Audit Log Status
(joined onto each Audit Log row)"]What You See on the Record
Tab on the Record | Underlying Table | What's Filtered |
|---|---|---|
History table for this model | Only the versions belonging to this record | |
| Only the API operations whose | |
Status column / badge in the Audit Log tab |
| The status (Pending / Success / Failure) joined onto each audit row above |
The grid tooling (filtering, sorting, As-Of time travel, PDF export) is the same as anywhere else in the app — only the dataset is pre-scoped.
Why It's Implemented This Way
The tracking tables are designed to be complete first, then conveniently sliced. There is exactly one History table per model, one Audit Log table, one Audit Log Status table — they hold every event for every record, forever. The per-record view is just a filter on that single source of truth.
This separation is deliberate, and it's what makes the day-to-day experience trustworthy:
- One source of truth. A finding on a record's tab is the same data an auditor would see in the master table. There is no second copy that could drift, no per-record file that could be edited or lost.
- No extra wiring per model. Adding a new model to the app automatically gives it a working History tab, Audit Log tab, and status indicators. Developers don't need to remember to "turn on tracking" — it's already on.
- Permissions are inherited. If a user can see the record, they can see its activity for that record — and only that record. They can't accidentally browse another team's audit trail.
- Fast where it matters. Indexes on
content_type+object_idmake the per-record filter cheap, even when the master tables grow into millions of rows.
Intended Use for End Users
The per-record view is the version of the tracking system that non-technical users actually use. It is meant for moments like:
- "What happened to this record?" Open the record, look at History — you see every version, in order, without having to know SQL or the table name.
- "Who last touched this record?" Open the Audit Log tab — the most recent row tells you the user, the timestamp, and the exact payload they sent.
- "Did my last save actually go through?" Look at the status of the most recent Audit Log row. Green means it landed, red means it didn't — and the traceback explains why.
- "Has anyone tried to delete this record?" Filter the Audit Log tab by
action = delete. Even rejected attempts show up, with their failure status. - "What did this record look like a month ago?" Use the As-Of control on the History tab to roll the record back in time without changing any data.
Benefits of the Auto-Filtered View
- Zero learning curve. Users already know how to open a record. The tracking story is just another tab on a page they already use.
- Context that travels with the data. Every record carries its own evidence — history, who-did-what, and success/failure — directly attached to it.
- Faster reviews. Instead of exporting a master audit log and filtering in Excel, reviewers click the record and see exactly what they need.
- Self-service compliance. Business users can answer most "prove it" questions on their own, without involving developers or DBAs.
- Operational confidence. Editors can verify their own changes immediately after saving — the Audit Log Status badge confirms the operation, the History tab confirms the new value.
When the Value Is Highest
- Your users are domain experts, not engineers — they need answers about specific records, not bulk reports.
- Records are individually meaningful (a customer, a contract, a quarter, a transaction) and frequently looked at on their own.
- Reviews and approvals happen one record at a time.
When the Value Is Lower
- Work is almost entirely batch-oriented and nobody opens individual records.
- Even then, the per-record view costs nothing extra — it's a free byproduct of the master tables already being there.
Was this helpful?
Your feedback shapes what we write next.
