# Activity Monitoring

Sovrium records every meaningful action across the application — record create/update/delete, authentication events, and administrative operations — into a system-wide activity log. The log is queryable through an authenticated API with filtering and pagination, giving operators and auditors a single place to answer "who did what, when".

This is the operator-facing read surface over the platform's canonical audit-log event store. Each entry is immutable and outlives the rows it references where required for compliance (an `account.deletion.purged` event survives the erasure of the user who triggered it — see [GDPR & Privacy](/en/docs/gdpr-privacy)).

## What Gets Tracked

| Category                   | Examples                                                            |
| -------------------------- | ------------------------------------------------------------------- |
| **Record CRUD**            | `create`, `update`, `delete`, `restore` on any table record.        |
| **Authentication events**  | Sign-in, sign-up, password reset, session revocation.               |
| **Administrative actions** | User creation, role changes, bans, schema publishes, force-deletes. |
| **System events**          | Migrations, account-deletion scheduling and purge.                  |

Each entry carries the action, the affected table and record id (when applicable), a timestamp, and the acting user (id, name, email). The actor reference is FK-linked with `ON DELETE SET NULL` so an audit entry remains a valid compliance record even after the actor's account is erased.

## Querying the Activity Log

The activity API is admin-gated. Unauthenticated requests return `401`; non-admin sessions return `403`.

```
GET /api/activity?page=1&pageSize=20&table=orders&action=update
```

```json
{
  "activities": [
    {
      "id": "act_123",
      "action": "update",
      "tableName": "orders",
      "recordId": 456,
      "createdAt": "2025-01-15T10:30:00Z",
      "user": { "id": "1", "name": "Alice", "email": "alice@example.com" }
    }
  ],
  "pagination": { "total": 150, "page": 1, "pageSize": 20, "totalPages": 8 }
}
```

| Endpoint                        | Description                                     |
| ------------------------------- | ----------------------------------------------- |
| `GET /api/activity`             | Paginated, filterable list of activity entries. |
| `GET /api/activity/:activityId` | Full detail for a single activity entry.        |

### Query Parameters

| Parameter  | Type   | Description                                                    |
| ---------- | ------ | -------------------------------------------------------------- |
| `page`     | number | Page number (default: `1`).                                    |
| `pageSize` | number | Entries per page.                                              |
| `table`    | string | Filter to a single table by name.                              |
| `action`   | string | Filter by action (`create`, `update`, `delete`, `restore`, …). |

:::callout
**Activity log vs record history.** The activity log is a cross-table, system-wide stream answering "what happened across the app". For the field-level before/after change set of a single record, use [Record History](/en/docs/record-history) — it captures the diff of each individual edit. The two complement each other: activity for breadth, history for depth.
:::

## Retention

Activity entries are retained according to the platform retention policy. Soft-deleted source rows themselves age out per the `ECO_RETENTION_PURGE_DAYS` horizon (see [Ecoconception](/en/docs/ecoconception)), but audit entries required for compliance — notably erasure records — are preserved independently of the rows they describe.

## Compliance Use

The same shape returned to admins is returned to auditors, so SOC2 / GDPR review documentation reflects exactly what operators see. Combined with the immutable canonical event store, the activity log provides the "audit trail of erasure" required when honoring a [right-to-be-forgotten](/en/docs/gdpr-privacy) request: the deletion is itself logged, with the actor reference null-ified once the account is purged.

## Related Pages

- [Record History](/en/docs/record-history) — field-level before/after diffs per record.
- [Soft Delete](/en/docs/records-soft-delete) — recoverable deletes and the `deleted_at` tombstone.
- [Admin Dashboard](/en/docs/admin-dashboard) — operator read API over the rest of the platform.
- [GDPR & Privacy](/en/docs/gdpr-privacy) — erasure records and the audit trail of deletion.
- [User Management](/en/docs/user-management) — the admin actions that produce activity entries.