> For the complete documentation index, see [llms.txt](https://docs.automatos.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.automatos.app/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
# Analytics Architecture
Relevant source files
The following files were used as context for generating this wiki page:
* [docs/PRDS/52-UNIFIED-ANALYTICS.md](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/docs/PRDS/52-UNIFIED-ANALYTICS.md)
* [frontend/app/analytics/page.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/app/analytics/page.tsx)
* [frontend/components/analytics/analytics-admin.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-admin.tsx)
* [frontend/components/analytics/analytics-agents.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-agents.tsx)
* [frontend/components/analytics/analytics-costs.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-costs.tsx)
* [frontend/components/analytics/analytics-documents.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-documents.tsx)
* [frontend/components/analytics/analytics-memory.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-memory.tsx)
* [frontend/components/analytics/analytics-openrouter-credits.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-openrouter-credits.tsx)
* [frontend/components/analytics/analytics-overview.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-overview.tsx)
* [frontend/components/analytics/analytics-page.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-page.tsx)
* [frontend/components/analytics/analytics-pandas-chart.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-pandas-chart.tsx)
* [frontend/components/analytics/analytics-plan-usage.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-plan-usage.tsx)
* [frontend/components/analytics/analytics-recommendations.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-recommendations.tsx)
* [frontend/components/analytics/analytics-workflows.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/analytics/analytics-workflows.tsx)
* [frontend/components/dashboard/widgets/system-health-widget.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/dashboard/widgets/system-health-widget.tsx)
* [frontend/components/knowledge/QueryTemplatesGrid.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/knowledge/QueryTemplatesGrid.tsx)
* [frontend/components/system/rag-configuration.tsx](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/components/system/rag-configuration.tsx)
* [frontend/hooks/use-unified-analytics.ts](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/frontend/hooks/use-unified-analytics.ts)
* [orchestrator/api/llm\_analytics.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/orchestrator/api/llm_analytics.py)
* [orchestrator/core/llm/openrouter\_analytics.py](https://github.com/AutomatosAI/automatos-ai/blob/main/docs/analytics-monitoring/orchestrator/core/llm/openrouter_analytics.py)
## Purpose and Scope
This document describes the architecture of the unified analytics system in Automatos AI. It covers the frontend-to-backend integration, data aggregation patterns, multi-tenancy implementation, and the structure of analytics domains. The analytics system provides workspace users with actionable insights about agents, workflows, documents, and costs, while giving admins platform-wide visibility across all workspaces.
The core implementation relies on **React Query** for frontend state management, **FastAPI** for data aggregation, and a dual-source strategy that prefers the `llm_usage` table while falling back to agent-specific statistics.
***
## System Overview
The analytics system follows a three-tier architecture with React Query-based frontend hooks, FastAPI backend endpoints, and PostgreSQL/Redis data storage. All queries are workspace-scoped to enforce multi-tenancy.
### High-Level Architecture Diagram
```mermaid
graph TB
subgraph "Frontend Layer [frontend/app/analytics/page.tsx]"
AnalyticsPage["AnalyticsPage [frontend/components/analytics/analytics-page.tsx]"]
Tabs["FilterTabs Component"]
OverviewTab["AnalyticsOverview [frontend/components/analytics/analytics-overview.tsx]"]
AgentsTab["AnalyticsAgents [frontend/components/analytics/analytics-agents.tsx]"]
WorkflowsTab["AnalyticsWorkflows [frontend/components/analytics/analytics-workflows.tsx]"]
DocsTab["AnalyticsDocuments [frontend/components/analytics/analytics-documents.tsx]"]
AdminTab["AnalyticsAdmin [frontend/components/analytics/analytics-admin.tsx]"]
Hooks["use-unified-analytics.ts [frontend/hooks/use-unified-analytics.ts]"]
AnalyticsPage --> Tabs
Tabs --> OverviewTab & AgentsTab & WorkflowsTab & DocsTab & AdminTab
OverviewTab & AgentsTab & WorkflowsTab & DocsTab & AdminTab --> Hooks
end
subgraph "React Query Layer"
QueryClient["QueryClient"]
wsScope["wsScope() function [frontend/hooks/use-unified-analytics.ts:12]"]
QueryKeys["unifiedAnalyticsKeys [frontend/hooks/use-unified-analytics.ts:18]"]
Hooks --> QueryClient
Hooks --> wsScope
Hooks --> QueryKeys
end
subgraph "Backend API Layer [orchestrator/api/]"
LLMRouter["/api/analytics/llm [orchestrator/api/llm_analytics.py]"]
AdminRouter["/api/admin/analytics [orchestrator/api/llm_analytics.py]"]
OR_Service["OpenRouterAnalyticsService [orchestrator/core/llm/openrouter_analytics.py]"]
AgentAPI["apiClient.getAgents()"]
WorkflowAPI["apiClient.getWorkflowStatsDashboard()"]
DocsAPI["apiClient.getAnalyticsOverview()"]
end
subgraph "Data Layer"
LLMUsageTable["LLMUsage table [core.models.core]"]
AgentTable["Agent table [core.models.core]"]
WorkflowTable["WorkflowTemplate table [core.models.core]"]
Postgres[("PostgreSQL + pgvector")]
end
QueryClient --> LLMRouter & AdminRouter & AgentAPI & WorkflowAPI & DocsAPI
LLMRouter --> OR_Service
LLMRouter & AdminRouter --> LLMUsageTable & AgentTable & WorkflowTable
AgentAPI --> AgentTable
DocsAPI --> Postgres
wsScope -.->|"Injects workspace_id"| QueryKeys
```
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:1-43](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [orchestrator/api/llm\_analytics.py:28-29](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [orchestrator/core/llm/openrouter\_analytics.py:27-28](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
***
## Frontend Architecture
### React Query Integration
The frontend uses React Query hooks defined in `use-unified-analytics.ts` to fetch data. These hooks handle automatic caching and background refetching.
#### Workspace Scoping Mechanism
The `wsScope()` function [frontend/hooks/use-unified-analytics.ts:12-14](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md) ensures workspace isolation in the cache by checking for an admin override or defaulting to the current user's workspace via `getAdminWorkspaceOverride()`.
```mermaid
graph LR
AdminOverride["getAdminWorkspaceOverride() [frontend/lib/api-client]"]
wsScope["wsScope() function [frontend/hooks/use-unified-analytics.ts]"]
QueryKey["Query Key Array"]
ReactQuery["React Query Cache"]
AdminOverride -->|"Returns workspace_id or null"| wsScope
wsScope -->|"Returns workspace_id or 'own'"| QueryKey
QueryKey -->|"['unified-analytics', scope, ...]"| ReactQuery
Insight1["Admin switches workspace → scope changes"]
Insight2["Cache entries isolated by scope"]
Insight3["Prevents data bleeding between workspaces"]
wsScope -.-> Insight1
QueryKey -.-> Insight2
ReactQuery -.-> Insight3
```
Every query key in `unifiedAnalyticsKeys` [frontend/hooks/use-unified-analytics.ts:18-43](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md) includes `wsScope()` as a dynamic component. This ensures that when an admin switches workspaces, the cache for the previous workspace is ignored.
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:10-43](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-admin.tsx:168-170](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
### Component Hierarchy
The `AnalyticsPage` manages a tabbed layout. Each tab utilizes specialized hooks for data retrieval.
| Component | Primary Hook | Purpose |
| -------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AnalyticsOverview` | `useAnalyticsOverview` | Aggregated summary of agents, missions, and costs [frontend/hooks/use-unified-analytics.ts:46](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). |
| `AnalyticsAgents` | `useAgentAnalytics` | Performance metrics and memory stats per agent [frontend/hooks/use-unified-analytics.ts:120](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). |
| `AnalyticsWorkflows` | `useWorkflowAnalytics` | Success rates and execution trends for recipes [frontend/hooks/use-unified-analytics.ts:184](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). |
| `AnalyticsDocuments` | `useDocumentAnalyticsUnified` | RAG performance and never-accessed document alerts [frontend/hooks/use-unified-analytics.ts:246](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). |
| `AnalyticsAdmin` | `useAdminDashboard` | Platform-wide metrics for system administrators [frontend/hooks/use-unified-analytics.ts:586](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). |
| `AnalyticsPlanUsage` | `usePlanUsage` | Tracks workspace consumption against quotas [frontend/hooks/use-unified-analytics.ts:397](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). |
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:45-600](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-workflows.tsx:145-150](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
***
## Analytics Domains
### 1. Overview & Recommendations
The overview surfaces high-level KPIs and AI-powered recommendations. The `useRecommendations` hook [frontend/hooks/use-unified-analytics.ts:384](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md) fetches optimization suggestions. The `AnalyticsRecommendations` component handles dismissal logic via local state `dismissed` [frontend/components/analytics/analytics-recommendations.tsx:74](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:384-395](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-recommendations.tsx:19-76](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
### 2. Agent & Memory Performance
The Agents tab combines agent metadata with memory statistics. The `useAgentAnalytics` hook [frontend/hooks/use-unified-analytics.ts:123-143](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md) performs a `Promise.all` fetch across `getAgents()`, `getSystemAgentStatistics()`, and `/api/v1/memory/stats/agents`. It builds a lookup map `memoryMap` by `agent_id` to merge memory stats into the agent list [frontend/hooks/use-unified-analytics.ts:140-141](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:130-134](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-agents.tsx:47-101](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
### 3. Workflow & Mission Analytics
Missions (Workflows) are tracked via execution trends and success rates. The `AnalyticsWorkflows` component [frontend/components/analytics/analytics-workflows.tsx:36](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md) renders an "Execution Trend" bar chart using `recharts` [frontend/components/analytics/analytics-workflows.tsx:164-179](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). It also includes detailed recipe performance metrics [frontend/components/analytics/analytics-workflows.tsx:95-107](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:187-200](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-workflows.tsx:153-180](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
### 4. LLM & Cost Analytics
This domain tracks token consumption and financial spend.
* **Dual-Source Strategy**: Prefers `llm_usage` table data, falling back to agent `model_usage_stats` [frontend/hooks/use-unified-analytics.ts:71-73](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
* **OpenRouter Sync**: `OpenRouterAnalyticsService` fetches external activity and upserts it into the local `LLMUsage` table [orchestrator/core/llm/openrouter\_analytics.py:44-75](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
* **Model Comparison**: `useModelComparison` allows benchmarking different models over specific periods [frontend/hooks/use-unified-analytics.ts:39](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
**Sources:**
* [orchestrator/api/llm\_analytics.py:141-191](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [orchestrator/core/llm/openrouter\_analytics.py:77-148](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-costs.tsx:144-187](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
### 5. Admin & Multi-Tenancy Monitoring
Super admins have access to the `AnalyticsAdmin` component [frontend/components/analytics/analytics-admin.tsx:164](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md), which provides platform-wide spend and workspace-level reporting. It uses `useAdminDashboard` [frontend/hooks/use-unified-analytics.ts:586](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md) to aggregate metrics across the entire platform.
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:586-605](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-admin.tsx:183-194](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
***
## Performance & Reliability
### Safe Request Pattern
To prevent a single failing API endpoint from breaking the entire dashboard, the analytics hooks utilize a `safeRequest` wrapper [frontend/hooks/use-unified-analytics.ts:53-57](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md). This pattern resolves to a fallback value (e.g., `null` or `[]`) on failure, allowing the UI to render partial data.
### Data Refreshing & Polling
* **Stale Time**: Overview data is configured with a `staleTime` of 60,000ms [frontend/hooks/use-unified-analytics.ts:104](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
* **Polling**: The `AnalyticsPage` provides a manual `handleRefresh` function that calls `queryClient.invalidateQueries` and `refetchQueries` for the `unified-analytics` key [frontend/components/analytics/analytics-page.tsx:43-46](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md).
**Sources:**
* [frontend/hooks/use-unified-analytics.ts:53-66](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/hooks/use-unified-analytics.ts:104](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
* [frontend/components/analytics/analytics-page.tsx:43-46](/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md)
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.automatos.app/automatos-ai-docs/design-docs/analytics-monitoring/analytics-architecture.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.