# Project Analytics

**Date:** 2026-05-31  
**Status:** Draft  
**Spec:** 150  
**Tier:** All tiers (basic); Business+ (profitability details)  
**Depends on:** `projects-module`, `time-management`, `invoices-core`, `expenses-module`, `foundation-auth-rbac`  
**Referenced by:** `projects-module`, `profitability-reports`

---

## Overview

Spec 10 (`projects-module`) defines the project detail view with Overview, Tasks, Time, and Files tabs. The Overview tab shows status and basic billing info but no analytics (time burn, budget vs actual, revenue trend, team utilization). Spec 92 (`profitability-reports`) aggregates across projects at the `/reports/profitability` level. This spec defines the **Analytics tab** on individual project detail — the per-project financial and operational picture.

---

## Route

`/projects/:id` → **[Analytics]** tab (new tab added to project detail).

---

## Analytics Tab Layout

### All tiers: Operational view

```
┌──────────────────────────────────────────────────────────────┐
│  Project: Website Redesign          [Overview] [Tasks] [Time] [Analytics] [Files] │
│                                                              │
│  ──── Time Summary ─────────────────────────────────────── │
│                                                              │
│  Total logged:   127h                                        │
│  This week:      12h                                         │
│  Last week:      18h                                         │
│                                                              │
│  By team member:                                             │
│  Alex Cohen      58h  ████████████░░░░  46%                  │
│  Yossi Levi      42h  ████████░░░░░░░░  33%                  │
│  Dana Mizrachi   27h  █████░░░░░░░░░░░  21%                  │
│                                                              │
│  ──── Task Completion ──────────────────────────────────── │
│                                                              │
│  42 total   38 done (90%)   4 open                           │
│  ████████████████████████████████░░░░░░░  90%              │
│                                                              │
│  ──── Weekly Time Trend (last 8 weeks) ─────────────────── │
│                                                              │
│  Week    H  16                                               │
│  Apr 14  ██ 14                                               │
│  Apr 21  ████ 18                                             │
│  Apr 28  ███ 12                                              │
│  May 5   ████ 16                                             │
│  May 12  █████ 20                                            │
│  May 19  ████ 18                                             │
│  May 26  ███ 12h (in progress)                               │
└────────────────────────────────────────────────────────────┘
```

### Business+: Financial overlay

```
│  ──── Revenue & Profitability ──────────────────────────── │
│                                                             │
│  Invoiced:       ₪28,400     (6 invoices)                   │
│  Collected:      ₪24,200     (85%)                          │
│  Outstanding:    ₪4,200      (1 invoice)                    │
│                                                             │
│  Expenses:       ₪2,100      (8 expenses)                   │
│  Team cost:      ₪19,050     (127h × ₪150/h avg)           │
│                                                             │
│  ──────────────────────────────────────────────────────   │
│  Gross margin:   ₪7,250      (26%)                          │
│  (Revenue − expenses − team cost)                           │
│                                                             │
│  ⚠ Business+ only — upgrade to see profitability details    │
│  (shown if not Business+)                                   │
└──────────────────────────────────────────────────────────────┘
```

---

## Hourly Budget Integration

If the project has a `budget_hours` set (spec 139), the Time Summary section shows the budget bar:

```
Budget: 127h of 80h ████████████████████ 159% ⚠ Over budget
```

This replaces the plain "Total logged" line when a budget exists.

---

## API

```
GET /api/projects/:id/analytics
    → project analytics data
      query: { weeks?: number (default 8) }
      Returns: {
        time: {
          total_hours,
          this_week_hours,
          last_week_hours,
          by_member: [{ user_id, name, hours, pct }],
          weekly_trend: [{ week_start, hours }]
        },
        tasks: { total, done, open },
        budget?: { budget_hours, logged_hours, over_budget }  -- if set
        financials?: {                                         -- Business+ only
          invoiced_total,
          collected_total,
          outstanding_total,
          invoice_count,
          expenses_total,
          expense_count,
          team_cost,
          gross_margin,
          gross_margin_pct
        }
      }
      Requires: projects:read (financials: invoices:read)
```

Team cost = `SUM(time_entries.duration_seconds / 3600 * COALESCE(contractor_assignments.rate_override, contractors.hourly_rate, projects.billing_config->>'rate_per_hour'))` — uses the effective rate for each entry.

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| Analytics as separate tab | Not inline on Overview | Overview is operational (current status, quick actions); Analytics is historical (trends, financials) — mixing them clutters both |
| Gross margin Business+ | Not all tiers | Revenue and cost data are financially sensitive; Basic tier users have operational analytics without P&L exposure |
| Weekly trend (8 weeks default) | Not monthly | Weekly granularity reveals sprint patterns and slippage; monthly obscures spikes that matter for project management |
| Team cost from time entry rate | Not separate salary data | Project-level cost uses the billable rate (contractor_assignments or billing_config), which is what the project is measured against |