Database

LesliAudit uses collection code 05 and engine code 01. Its migrations live under db/migrate/v1.0 and are loaded into the host application's migration set.

Choosing the Correct Record

The similarly named tables do not contain interchangeable data:

User requests versus user journals

UserRequest is an aggregate counter. Repeated matching requests increase request_count; the row is intended for totals and grouped reports. It does not preserve the time of every individual request and must not be used to prove that a business operation occurred.

UserJournal is an individual request event. Its tenant-scoped event_uid identifies the captured event, date stores its reporting and retention day, and created_at records the exact time it was stored. When enable_journals is true, normalized request, user, and session dimensions are available for operational history and working-hours reports.

In short:

• query user_requests to answer how many matching requests a user made;
• query retained user_journals to answer when individual requests were captured;
• query user_logs to answer which explicit auditable operations the user performed.

Neither request table replaces UserLog. A controller request can finish without representing a business change, while one business operation may also emit multiple outcome events.

The accounts table uses create_table_lesli_shared_account_10(:lesli_audit) and adds a unique index over account_id, so each core account has exactly one audit account. Request and device tables use a dedicated date column for their aggregation bucket and normal Rails timestamps for record lifecycle metadata.

The engine owns its foreign-key lifecycle rules. Core account soft deletion keeps every physical row intact. Hard deletion cascades from the core account to its Audit account and then to all tenant audit data. A hard-deleted user cascades aggregate request rows and nullifies actor references on journals and activity events, preserving their immutable identity snapshots.

LesliAudit installs the audit association on Lesli::Account through LesliAudit::AccountAssociations. Every Audit-owned record then belongs to LesliAudit::Account, while user-owned records also reference Lesli::User. Destroying an Audit account is a deliberate hard purge and deletes its dependent Audit records.

The initial schema enforces required tenant and dimension columns, nonnegative 64-bit counters, and tenant-first unique indexes. Logger upserts identify these constraints by index name so column order can continue to support account-scoped access. Session identifiers remain nullable opaque references and do not create a database dependency on LesliShield.

Journal rows use a tenant-scoped unique event_uid. Request counters and journals are written synchronously by LesliAudit::LoggerInterface; no background analytics job or processing lifecycle is required.

Device dimensions follow a separate path. log_devices parses and aggregates the user agent only after a successful login; ordinary request logging never increments AccountDevice.

Account and user activity logs require an operation, use text for their human-readable description, and index account plus creation time for tenant history queries. User histories additionally index user plus creation time. actor_uid is an immutable identity snapshot: the user_id foreign key may be set to null when a user is hard-deleted, while the event and actor snapshot are retained. Persisted activity rows are append-only at the model layer; status changes such as attempted, failed, and succeeded are separate rows.

Run schema operations through the host application:

bin/rails lesli:db:prepare
bin/rails db:migrate:status

Run configured retention cleanup manually with:

bin/rails lesli_audit:retention:cleanup

The retention operation is available to host schedulers through LesliAudit::RetentionCleanupJob. Cleanup uses the date indexes for journals and analytics and the created_at indexes for activity histories, deleting in bounded batches. Activity histories are skipped while audit_retention_days is nil.

Audit data can grow quickly. New queries should remain account-scoped and be supported by indexes matching their filters and grouping columns.

The retention and reliability rules differ between aggregated analytics, short-lived journals, and durable activity events. See Architecture and Data Policy before changing a table or adding a new event source.

See Database Architecture and Migration Versioning for shared rules.