Skip to content

System - Activity log

Purpose

The Activity Log capability provides auditability and traceability across both operational realms of BizOS: 1. Platform System Activity Log (Control Plane): Centralized technical and platform-level event logging (SMTP and system configuration changes, automated background jobs, schema migrations, transactional email dispatches, and system health status shifts). 2. Tenant Workspace Activity Log (Tenant Realm): Workspace-scoped audit logging that allows tenant administrators to inspect member actions (sign-in, create, update, delete across CRM, Contracts, Tasks, and IAM).

Architecture and Dual-Realm Isolation

BizOS strictly segregates system-level platform activity from customer business activity (ADR-0012):

flowchart TD
    subgraph Realm1["Platform Operations Realm (Control Plane)"]
        SysEvents["System Events<br/>(SMTP, Jobs, Migrations, Health)"] --> SysLogger["System Activity Logger"]
        SysLogger --> SysDB[("Control Plane DB<br/>system_activity_logs")]
        SysDB --> SysAPI["GET /api/admin/system/activity-log"]
        SysAPI --> AdminUI["Admin Portal: /system/activity-log"]
    end

    subgraph Realm2["Tenant Workspace Realm (Tenant Scoped)"]
        BizEvents["Workspace Actions<br/>(Sign-in, Create, Update, Delete)"] --> AuditWriter["IAM Audit Writer"]
        AuditWriter --> TenantDB[("Tenant DB<br/>activity_logs")]
        TenantDB --> TenantAPI["GET /api/activity-log"]
        TenantAPI --> WebUI["Customer Portal: /activity-log"]
    end
Hold "Alt" / "Option" to enable pan & zoom

Part 1: Platform System Activity Log (SYS)

Users and Permissions (Platform)

  • Super Admin (super_admin) & Admin (admin): Full viewing, filtering, and export access for all system categories.
  • Support (support): Read-only view for non-sensitive events (email dispatches, job runs); export forbidden.
  • Tenant Users: Strictly forbidden (403 Forbidden).

Categories and Severity

  • Categories: config (SMTP, system settings), jobs (migrations, crons), email (transactional dispatches, test emails), security (operator auth, MFA, rate limits), health (component health shifts).
  • Severities: info, warning, error, critical.

Platform Requirements

ID Priority Requirement
SYS-01 Must Store immutable platform records: id, occurred_at (UTC timestamp), category, action, severity, actor_id, actor_name, target_type, target_id, ip_address, status, message, and metadata (JSONB).
SYS-02 Must Sensitive fields inside metadata (passwords, tokens, keys) must be sanitized and replaced with ******** before writing.
SYS-03 Must Updating SMTP settings or sending test emails automatically emits a system activity entry with operator attribution.
SYS-04 Must Query endpoint (GET /api/admin/system/activity-log) supports pagination (default 25, max 100 per page, newest first), with filters for category, severity, status, actor, search, and inclusive UTC date range.
SYS-05 Must System activity log entries are append-only. Updates and deletes are rejected by the database.
SYS-06 Should Super Admin and Admin operators can export the filtered log to CSV via GET /api/admin/system/activity-log/export. The export action itself generates a security audit entry.
SYS-07 Should Automated 180-day retention with scheduled cleanup of non-critical informational records older than 180 days while retaining error/critical entries for 1 year.
SYS-08 Must The Admin Portal provides a dedicated System Activity Log view at /system/activity-log with filter chips, date range picker, searchable table, and a slide-over metadata inspector panel.

Part 2: Tenant Workspace Activity Log (ACT)

Users and Permissions (Tenant)

  • Only users with BUSINESS MANAGEMENT access (super_admin, admin, support, tenant_owner) may view the tenant activity log.
  • Plain user receives 403 Forbidden.
  • Unauthenticated requests receive 401 Unauthorized.

Tenant Workspace Requirements

ID Priority Requirement
ACT-01 Must The API lists activity for the current tenant only. The request does not include a tenant id. There is no endpoint that writes, edits, or deletes an entry.
ACT-02 Must The screen is one table, newest first, with columns: time, user (display name and email), action, record type, record id, and details. Record type is a business name such as Customer, Contract, or Task, never a SQL table name.
ACT-03 Must Action labels are Đăng nhập, Tạo, Sửa, and Xóa, each with its own colour.
ACT-04 Must The list filters by user id (exact match), module, action, and an inclusive UTC date range. Module and action are dropdowns. An empty filter does not restrict that field.
ACT-05 Must Each page has 15 rows. The client cannot change the page size. Previous and next move between pages.
ACT-06 Must Refresh reloads the list with the filters and page currently on screen.
ACT-07 Must When an entry has before and after values, activating the row opens a panel that shows those values. Otherwise the details cell shows "-" and activating the row does not open a panel. This capability does not invent before or after values.
ACT-08 Must Callers with BUSINESS MANAGEMENT access (super_admin, admin, support, tenant_owner) may list activity. A caller who is not signed in receives 401. A signed-in user receives 403, and the screen shows no activity rows.

Screens

1. Platform System Activity Log (/system/activity-log in Admin Portal)

  • Counters: Today's counts for Total Events, Warnings, Errors, and Failed Dispatches.
  • Filters: Search text input, Category dropdown, Severity filter chips, Date range picker, Refresh button, Export CSV button.
  • Table: Time (Asia/Ho_Chi_Minh), Severity badge, Category icon, Action, Actor, Target, Status.
  • Slide-over Sheet: Details view displaying event payload, operator IP, user agent, execution duration, and formatted JSON viewer.

2. Tenant Workspace Activity Log (/activity-log in Tenant App)

  • Table: Newest row first. Shown only when signed-in user is admin, tenant_owner, or platform operator.
  • Columns: Thời gian (24-hour clock in Asia/Ho_Chi_Minh), Người dùng (name and email), Hành động (Đăng nhập, Tạo, Sửa, Xóa), Loại bản ghi, ID bản ghi, Chi tiết.
  • Filters: User ID input, Module dropdown (All, iam, crm, contracts, tasks), Action dropdown, Date range (from/to), Refresh button, Previous/Next pagination.
  • Before/After Drawer: Clicking a row with before/after values opens a comparison side sheet.

Business rules

  • Timestamp & Timezone: All log timestamps are persisted in UTC. Presentation formats use Vietnam Time (Asia/Ho_Chi_Minh, UTC+7) as a 24-hour clock.
  • Immutability: Both platform and tenant activity logs are write-only. Database triggers and ORM layers disallow UPDATE operations.
  • Actor Separation: Platform operator actions on tenants are audited in the Admin Portal activity log (AWR-09) and omitted from tenant customer views.
  • Fail-safe Execution: Ingestion logging failures must never crash primary business transactions.
  • Retention: Tenant activity logs are kept for 1 year by default; system logs are kept for 180 days (standard) or 1 year (errors/critical).

Acceptance criteria

Platform System Activity Log

  • SYS-01: Updating SMTP settings writes a config system activity log entry with action smtp_settings_updated and masked credentials.
  • SYS-02: Sending an SMTP test email writes an email system activity log entry containing the recipient address, latency, and success status.
  • SYS-03: GET /api/admin/system/activity-log returns newest entries first and enforces role permissions.
  • SYS-04: Filtering by severity=error returns only entries with error severity.
  • SYS-05: Attempting to call DELETE or PUT against system activity log records fails with 405 Method Not Allowed or 403 Forbidden.
  • SYS-06: Exporting the log produces a valid CSV file with columns matching the table schema.
  • SYS-07: In the Admin Portal, opening /system/activity-log displays the table and clicking a row opens the slide-over details panel.

Tenant Workspace Activity Log

  • ACT-01: The list operation accepts no tenant id, and the activity-log API has no write operation.
  • ACT-02: The table shows time, user name and email, action, a business record type, record id, and details.
  • ACT-03: Đăng nhập, Tạo, Sửa, and Xóa render as four distinct coloured labels.
  • ACT-04: Filtering by one user id, one module, one action, and a from/to date range returns only matching entries. A missing filter does not restrict that field. Dates are inclusive UTC days.
  • ACT-05: The first page contains the 15 newest matching entries, and the next page contains the following entries. The page size stays 15.
  • ACT-06: Refresh requests the list again with the same user, module, action, date range, and page.
  • ACT-07: A row with before and after values opens a panel showing those values. A row without them shows "-" and does not open a panel.
  • ACT-08: A request without a session receives 401. A signed-in user receives 403. A super admin or tenant owner may list activity.

Out of scope

  • Direct database editing or entry deletion from tenant screens.
  • Real-time websocket streaming across cross-tenant clusters (covered by SSE/polling).