Audit Logging

Overview

Every meaningful user and system action across all Leadmetrics portals and API routers is durably recorded in a MongoDB audit_logs collection. The log is permanent — never deleted or truncated. Entries are also published to a Redis pub/sub channel so super-admin UIs can stream them in real time.

Related: observability.md (tracing, Loki, Grafana) | database-mongo.md

Implementation

Package location

packages/nosqldb/src/audit.ts — exported from @leadmetrics/nosqldb

Function signature

import { writeAuditLog } from "@leadmetrics/nosqldb";
 
writeAuditLog({
  actorId:      string;          // user ID or system identifier
  actorName:    string;          // display name
  actorRole:    string;          // "super_admin" | "user" | "dm_user" | etc.
  tenantId?:    string | null;   // omit for platform-level events
  tenantName?:  string | null;
  action:       string;          // dot-notation: "resource.verb"
  resourceType: string;          // "tenant" | "blog_post" | "social_post" | etc.
  resourceId:   string;          // primary key of the affected resource
  resourceName?: string | null;  // human-readable label
  metadata?:    Record<string, unknown>;  // event-specific fields
  ipAddress?:   string | null;
});

writeAuditLog is fire-and-forget — it never throws or blocks the calling route handler. Audit failures are silently swallowed so they never affect request outcomes.

MongoDB schema

Collection: audit_logs

Compound indexes: (actorId, createdAt), (tenantId, createdAt), (action, createdAt), (resourceType, resourceId, createdAt).

Real-time streaming

After writing to MongoDB, the document is published to the Redis channel audit:events. The /admin/v1/audit-logs/stream SSE endpoint subscribes to this channel, allowing the manage portal to show a live feed of platform events.

Writing Audit Logs — Patterns

Admin routes (import from ../../lib/auth)

requireSuperAdmin from lib/auth returns { sub: string; role: string } | null.

const actorId = await requireSuperAdmin(req, reply);
if (!actorId) return;
 
const actor = await db.user.findUnique({ where: { id: actorId.sub }, select: { name: true, role: true } });
writeAuditLog({
  actorId:      actorId.sub,
  actorName:    actor?.name ?? "Super Admin",
  actorRole:    actor?.role ?? "super_admin",
  action:       "tenant.updated",
  resourceType: "tenant",
  resourceId:   tenantId,
  ipAddress:    req.ip,
});

Admin routes (import from ./_shared)

requireSuperAdmin from ./_shared returns userId: string | null (plain string). Use userId directly (not .sub).

DM routes

const actor = await requireDMAccess(req, reply);
if (!actor) return;
 
writeAuditLog({
  actorId:      actor.sub,
  actorName:    "User",
  actorRole:    actor.role ?? "user",
  tenantId:     tenantId,
  action:       "blog_post.dm_approved",
  resourceType: "blog_post",
  resourceId:   postId,
});

Tenant-facing routes

const actor = await requireTenantUser(req, reply);
if (!actor) return;
 
writeAuditLog({
  actorId:      actor.sub,
  actorName:    "User",
  actorRole:    actor.role ?? "user",
  tenantId:     actor.tenantId,
  action:       "context.approved",
  resourceType: "tenant_context",
  resourceId:   contextId,
});

Action Inventory

All actions follow resource_type.verb naming. 141 unique events across 40+ router files.

Auth & Identity

Admin — Users

Admin — Tenants

Admin — Agents & Skills

Admin — Billing

Admin — Platform Settings

Admin — Backlink Directories

Admin — Content

Tenant-Facing — Pipeline Approvals

Tenant-Facing — Content

Tenant-Facing — Assets & Knowledge

Tenant-Facing — Channels & Integrations

Tenant-Facing — CRM & Leads

Tenant-Facing — Campaigns

Tenant-Facing — Billing & Credits

Tenant-Facing — Preferences

Tenant-Facing — AI Chat

Tenant-Facing — AI Visibility

Tenant-Facing — Backlinks

DM Portal — Pipeline Reviews

DM Portal — Plan Management

DM Portal — Activities & Campaigns

DM Portal — Content Management

DM Portal — Search Terms

DM Portal — Contacts & Media

DM Portal — AI Visibility

DM Portal — Misc

Mobile App

Intentionally Not Logged

The following events are deliberately excluded:

Coverage by Domain

Gotcha: Two requireSuperAdmin Implementations

There are two different implementations of requireSuperAdmin in the admin routers:

Files that import from lib/auth: admin/deliverable-settings.ts, admin/design-defaults.ts, admin/important-days.ts. All other admin routers import from ./_shared and receive a plain string.

When writing audit logs in a lib/auth file, use actorId.sub (not actorId).