AgentAnalyticsController

Kind: Controller

Source: atloria-monorepo/apps/api/src/events/agent-analytics.controller.ts

Agent-native analytics — "who/what AI is reading your docs". Authed, org-scoped read model over the agent_read events the public agent surfaces record. Guard/scope pattern mirrors ManualsInsightsController.

AgentAnalyticsController exposes authenticated, organization-scoped analytics for understanding which AI agents are reading documentation. It queries the read model built from agent_read events recorded by public agent-facing surfaces, following the same guard and scoping conventions as ManualsInsightsController.

Diagram

mermaid
graph LR
  A[Public agent surfaces] -->|records agent_read events| B[Events / Read Model]
  B --> C[AgentAnalyticsController]
  D[Authenticated user] -->|org-scoped request| C
  C --> E[Organization analytics response]

Usage

ts
// The authenticated session determines the active organization scope.
// Do not pass or trust an organization ID supplied by the client.

const response = await fetch("/agent-analytics", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});

if (!response.ok) {
  throw new Error("Unable to load agent analytics");
}

const analytics = await response.json();

console.log("AI documentation reads:", analytics);

AI Coding Instructions

• Apply the same authentication guards and organization-scoping pattern used by ManualsInsightsController.
• Treat agent_read events and their derived read model as the source of truth; avoid querying public-agent request paths directly for analytics.
• Derive the organization from the authenticated request context rather than accepting a client-provided organization identifier.
• Keep this controller read-only and delegate aggregation/query logic to the appropriate analytics or event read-model service.
• Ensure analytics responses cannot expose event data belonging to another organization.

Relationships

• MODULE_DECLARES → traffic
• MODULE_DECLARES → actions
• DEPENDS_ON → AgentAnalyticsService

Referenced By

• EventsModule (MODULE_DECLARES)