# Admin Reports & Analytics (`/admin/reports`, `/admin/analytics`)

**Date:** 2026-05-31  
**Status:** Draft  
**Spec:** 59  
**Tier:** SUPER_ADMIN only  
**Depends on:** `admin-dashboard`, `zync-subscription`, `foundation-auth-rbac`  
**Referenced by:** `admin-dashboard`

---

## Overview

Platform-level business intelligence for Zync operators. Spec 8 (`admin-dashboard`) defines the admin nav with `/admin/reports` and `/admin/analytics` routes and stubs `GET /api/admin/reports` + `GET /api/admin/analytics` without speccing their content. This spec fills those in.

Both routes require `SUPER_ADMIN` role. Data sources: Neon PostgreSQL (`tenants`, `zync_subscriptions`, `tenant_audit_log`) + CF Analytics Engine SQL HTTP API.

---

## Reports (`/admin/reports`)

Subscription and revenue metrics. Date range picker (default: current month).

### Revenue Tab

```
┌─────────────────────────────────────────────────────────────┐
│  Period: [June 2026 ▾]                [Export CSV]          │
│                                                             │
│  MRR: ₪48,200    ARR: ₪578,400    Active tenants: 124       │
│                                                             │
│  [Line chart: MRR over last 12 months]                      │
│                                                             │
│  Breakdown by plan:                                         │
│  ┌──────────────┬─────────┬──────────┬────────────────┐    │
│  │ Plan         │ Tenants │  MRR     │  % of MRR      │    │
│  ├──────────────┼─────────┼──────────┼────────────────┤    │
│  │ Freelancer   │   62    │  ₪6,200  │  12.9%         │    │
│  │ Business     │   51    │ ₪30,600  │  63.5%         │    │
│  │ Enterprise   │   11    │ ₪11,400  │  23.6%         │    │
│  └──────────────┴─────────┴──────────┴────────────────┘    │
└─────────────────────────────────────────────────────────────┘
```

Data from `zync_subscriptions` JOIN `tenants`. MRR = sum of plan prices for active subscriptions.

### Signups & Churn Tab

```
┌─────────────────────────────────────────────────────────────┐
│  [Bar chart: new signups per month, stacked by plan]        │
│                                                             │
│  This month:  New signups: 14    Churned: 3    Net: +11     │
│                                                             │
│  Trial → Paid conversion:  38%  (last 90 days)             │
│  Avg trial duration:       8.2 days                        │
│                                                             │
│  Churn by plan:                                             │
│  Freelancer: 2   Business: 1   Enterprise: 0               │
└─────────────────────────────────────────────────────────────┘
```

Churn = `subscription_status` changed to `cancelled` or `past_due` in period.  
Trial conversion = tenants that started trial and converted to paid within 30 days.

### Tenants Tab

Paginated table of all tenants with status, plan, MRR, signup date, last login date.  
Links to `/admin/tenants/:slug` for each row (spec 8).

---

## Analytics (`/admin/analytics`)

Feature adoption and usage telemetry. Date range picker.

### Module Adoption Tab

```
┌─────────────────────────────────────────────────────────────┐
│  Feature adoption across active tenants (last 30 days)      │
│                                                             │
│  Module          Active Tenants  Adoption %  Events         │
│  ─────────────────────────────────────────────────────────  │
│  Invoices               118       95.2%      12,400         │
│  Time Tracking           89       71.8%       8,200         │
│  Expenses                74       59.7%       3,100         │
│  Marketing / CRM         41       33.1%       1,800         │
│  AI Assistant            55       44.4%       2,600         │
│  Contracts               28       22.6%         420         │
└─────────────────────────────────────────────────────────────┘
```

"Active" = tenant had at least 1 API call to that module's Worker in the period.  
Data from `tenant_audit_log` or CF Worker invocation counts (CF Analytics Engine `worker_requests` dataset).

### AI Usage Tab

```
┌─────────────────────────────────────────────────────────────┐
│  AI token consumption this month                            │
│                                                             │
│  Total input tokens:    1,240,000                           │
│  Total output tokens:     380,000                           │
│  Total cost (est.):        ₪720                            │
│                                                             │
│  Top consumers:                                             │
│  Tenant             Input Tokens  Output Tokens  Cost       │
│  ─────────────────────────────────────────────────────────  │
│  Acme Corp              180,000        42,000    ₪98        │
│  Globex LLC              95,000        28,000    ₪55        │
└─────────────────────────────────────────────────────────────┘
```

Data from `ai_usage_log` table (spec 6/AI assistant). Costs estimated at published Anthropic pricing.

### Funnel Health Tab

Platform-wide AE funnel (aggregated across tenants):

```
catalog_view  →  lead_captured  →  proposal_accepted  →  invoice_paid
  48,200            5,420               1,210               680
  100%              11.2%               25.1%*             56.2%*
```

*Conversion rates are relative to previous step.  
Data from CF Analytics Engine SQL HTTP API using `CF_ANALYTICS_READ_TOKEN`.

---

## API Endpoints

```
GET  /api/admin/reports
     query: tab=revenue|signups|tenants, from=YYYY-MM-DD, to=YYYY-MM-DD
     returns: tab-specific aggregated data

GET  /api/admin/analytics
     query: tab=modules|ai|funnel, from=YYYY-MM-DD, to=YYYY-MM-DD
     returns: tab-specific analytics data

GET  /api/admin/reports/export
     query: same + format=csv
     returns: CSV download of active tab's data
```

All require `SUPER_ADMIN` session. No tenant scoping (`tenantQuery` wrapper NOT used — cross-tenant queries).

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| MRR from subscriptions table | Not invoices | `zync_subscriptions` has plan price + status; invoices are per-project charges not system revenue |
| Funnel from AE SQL API | Not Neon | Funnel events written to CF Analytics Engine (write-only binding); reads via SQL HTTP API with `CF_ANALYTICS_READ_TOKEN` per spec 23 |
| AI cost estimation | Estimated, not exact | No Anthropic cost API; estimates from published token pricing; labeled "est." in UI |
| Module adoption from audit_log | Not a dedicated telemetry table | `tenant_audit_log` already captures every write operation per module; no separate instrumentation needed for adoption signal |