> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Event and Activity Model

> Event logging, activity tracking, and audit trail architecture

# Event and Activity Model

> **Source:** `equa-server/modules/activity/`, `equa-server/modules/persistence/src/schema.ts`

## Overview

Equa tracks user activity through three complementary mechanisms:

1. **Actions** -- High-level user actions within organizations
2. **Event Logs** -- Detailed event records with JSON payloads
3. **Tasks** -- Workflow status tracking for multi-step operations

## Entities

### Actions

Source: `equa-server/modules/persistence/src/schema.ts` (Actions entity)

| Field          | Type            | Description                   |
| -------------- | --------------- | ----------------------------- |
| `organization` | uuid (nullable) | Organization context          |
| `type`         | uuid            | Action type identifier        |
| `user`         | uuid            | User who performed the action |

Tracked via `equa-server/modules/activity/` and surfaced in the organization dashboard.

### Event Logs

Source: `equa-server/modules/persistence/src/schema.ts` (EventLogs entity)

| Field          | Type            | Description                                   |
| -------------- | --------------- | --------------------------------------------- |
| `id`           | uuid            | Unique event identifier                       |
| `type`         | string          | Event type (e.g., "login", "share\_transfer") |
| `user`         | uuid (nullable) | User who triggered the event                  |
| `organization` | uuid (nullable) | Organization context                          |
| `data`         | json            | Arbitrary event payload                       |

Event logs capture granular platform activity with structured JSON payloads for audit and debugging purposes.

### Tasks

Source: `equa-server/modules/persistence/src/schema.ts` (Tasks entity)

| Field    | Type       | Description         |
| -------- | ---------- | ------------------- |
| `entity` | uuid       | Target entity ID    |
| `type`   | TaskType   | Task type enum      |
| `status` | TaskStatus | Current status enum |

Used for tracking multi-step operations like option exercises (`TasksExerciseOption`).

## Activity Flow

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant API as API Endpoint
    participant Activity as Activity Module
    participant DB as PostgreSQL

    U->>API: Perform action
    API->>Activity: Log action
    Activity->>DB: INSERT into actions
    Activity->>DB: INSERT into event_logs
    API-->>U: Response
```

## Frontend Display

The organization dashboard (`equa-web/src/modules/organization-dashboard/`) displays recent actions for the active organization, providing visibility into team activity.

## Audit Trail Gaps

<Warning>
  The current event logging system does not provide:

  * Immutable log storage (logs can be deleted)
  * Comprehensive coverage of all state changes
  * Structured audit trail with before/after states
  * Log export or compliance reporting

  These gaps are documented in the [Compliance: Audit Trail Design](/compliance/audit-trail-design) specification.
</Warning>