# Reports Navigation Hub **Date:** 2026-05-31 **Status:** Draft **Spec:** 103 **Tier:** All tiers (individual reports may be gated) **Depends on:** `reports-analytics`, `admin-reports-analytics`, `profitability-reports`, `time-reports`, `expense-reports-ui`, `revenue-forecasting`, `tenant-audit-log`, `api-usage-quota-ui`, `foundation-auth-rbac` **Referenced by:** `admin-reports-analytics`, `profitability-reports` --- ## Overview Multiple specs define individual report views (revenue, time, expense, profitability). This spec defines the `/reports` landing page: a navigation hub with report categories, quick-access tiles, saved report shortcuts, and a date-range context shared across report navigation. --- ## Reports Hub Layout `/reports`: ``` ┌──────────────────────────────────────────────────────────────┐ │ Reports │ │ │ │ Date range: [This month ▾] [Jun 2026 ▾] — [Jun 2026 ▾] │ │ │ │ ── Financial ──────────────────────────────────────────── │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Revenue │ │ Invoices │ │ Payments │ │ │ │ ₪142,500 │ │ 38 sent │ │ ₪97,300 rec. │ │ │ │ this month │ │ 12 overdue │ │ 4 pending │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ ── Operations ─────────────────────────────────────────── │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Time │ │ Expenses │ │ Profitability│ │ │ │ 482h logged │ │ ₪23,400 │ │ 68% margin │ │ │ │ this month │ │ 12 unbilled │ │ top 5 projs │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ │ │ │ Revenue │ │ │ │ Forecast │ │ │ │ ₪168k proj. │ │ │ └──────────────┘ │ │ │ │ ── CRM & Pipeline ─────────────────────────────────────── │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Leads │ │ Proposals │ │ │ │ 14 new │ │ 8 sent │ │ │ │ 3 converted │ │ ₪340k value │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ ── System ─────────────────────────────────────────────── │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Audit Log │ │ API Usage │ │ │ │ 1,247 events │ │ 38,400 calls │ │ │ │ last 30 days │ │ this month │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ ── Tax & Compliance ────────────────────── [Business+] ── │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ VAT Report │ │ P&L Statement│ │ Cash Flow │ │ │ │ ₪24,531 due │ │ ₪318k net │ │ ₪41k inflow │ │ │ │ this period │ │ YTD │ │ this month │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Advance Tax │ │ Mas 856 │ │ Bituach Leumi│ │ │ │ מקדמות │ │ annual │ │ NII estimate │ │ │ │ ₪8,200 next │ │ withholding │ │ ₪3,140/mo │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └──────────────────────────────────────────────────────────────┘ ``` Each tile is clickable → navigates to the full report. Tile shows a KPI headline for the selected date range. The **Tax & Compliance** section is gated to the **Business+** tier. Tiles are hidden (not just disabled) for tiers below Business. These reports surface Israeli statutory filings and are described in specs 170 (`financial-statements`), 171 (`israeli-tax-reports`), and 175 (`bituach-leumi`). --- ## Date Range Context Global date range selector at top of `/reports`. Preset options: - Today, This week, This month (default), Last month, This quarter, This year, Last 12 months, Custom range Selected range is stored in URL as query params (`?from=2026-06-01&to=2026-06-30`) and passed as default range when navigating to sub-reports. --- ## Report Tiles: KPI Queries Each tile's headline is fetched via a single summary endpoint: ``` GET /api/reports/summary?from=2026-06-01&to=2026-06-30 → { revenue: { total, currency }, invoices: { sent, overdue }, payments: { received, pending_count }, time: { hours_logged }, expenses: { total, unbilled_count }, profitability: { margin_pct }, leads: { new_count, converted_count }, proposals: { sent_count, pipeline_value }, audit: { event_count }, api_usage: { call_count } } Requires: authenticated (scoped by role: MEMBERs see own stats, ADMINs see org-wide) ``` Single aggregate query response powers all tiles. No N+1. --- ## Report Navigation Map | Tile | Route | Spec | |------|-------|------| | Revenue | `/reports/revenue` | spec 24 (`reports-analytics`) — revenue ledger | | Invoices | `/reports/invoices` | spec 24 (`reports-analytics`) — invoice report | | Payments | `/reports/payments` | spec 24 (`reports-analytics`) — payment report | | Time | `/reports/time` | spec 56 (`time-reports`) | | Expenses | `/expenses/reports` | spec 57 (`expense-reports-ui`) | | Profitability | `/reports/profitability` | spec 92 (`profitability-reports`) | | Revenue Forecast | `/reports/revenue-forecast` | spec 116 (`revenue-forecasting`) | | Leads | `/reports/leads` | spec 22 (`marketing-leads-pipeline`) pipeline analytics | | Proposals | `/reports/proposals` | spec 23 (`marketing-catalogs-campaigns`) | | AR Aging | `/reports/ar-aging` | spec 140 (`ar-aging-report`) | | Bad Debt | `/reports/bad-debt` | spec 168 (`bad-debt-writeoff`) | | Audit Log | `/reports/audit` | spec 50 (`tenant-audit-log`) | | API Usage | `/settings/api` | spec 94 (`api-usage-quota-ui`) | | VAT Report (Business+) | `/reports/vat` | spec 171 (`israeli-tax-reports`) | | P&L Statement (Business+) | `/reports/pnl` | spec 170 (`financial-statements`) | | Cash Flow (Business+) | `/reports/cashflow` | spec 170 (`financial-statements`) | | Advance Tax / מקדמות (Business+) | `/reports/advance-tax` | spec 171 (`israeli-tax-reports`) | | Mas 856 (Business+) | `/reports/withholding` | spec 171 (`israeli-tax-reports`) | | Bituach Leumi (Business+) | `/reports/bituach-leumi` | spec 175 (`bituach-leumi`) | | Uniform Format / מבנה אחיד (Business+) | `/reports/uniform-format` | spec 180 (`uniform-format-export`) | The seven **Tax & Compliance** routes (vat, pnl, cashflow, advance-tax, withholding, bituach-leumi, uniform-format) are tier-gated to **Business+**; the route guard returns 403 (and the nav hides the tiles) for lower tiers. --- ## Saved Report Shortcuts Users can pin a report configuration (date range + filters) as a shortcut: ``` ┌──────────────────────────────────────────────────────────────┐ │ Saved reports [+ Save current]│ │ ★ Monthly revenue (Jun) Revenue [Open] [✕] │ │ ★ Unbilled expenses Expenses [Open] [✕] │ └──────────────────────────────────────────────────────────────┘ ``` ```sql CREATE TABLE report_shortcuts ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), tenant_id UUID NOT NULL REFERENCES tenants(id), user_id UUID NOT NULL REFERENCES users(id), name TEXT NOT NULL, report_type TEXT NOT NULL, -- 'revenue' | 'invoices' | etc. params JSONB NOT NULL, -- { from, to, filters... } created_at TIMESTAMPTZ DEFAULT now() ); ``` `GET /api/reports/shortcuts` → list shortcuts for current user. `POST /api/reports/shortcuts` → save shortcut. `DELETE /api/reports/shortcuts/:id` → remove. --- ## API ``` GET /api/reports/summary → KPI summary for all report types in date range query: { from, to } Requires: authenticated GET /api/reports/shortcuts → list saved shortcuts for current user Requires: authenticated POST /api/reports/shortcuts → save shortcut body: { name, report_type, params } Requires: authenticated DELETE /api/reports/shortcuts/:id → delete shortcut Requires: authenticated (own shortcuts only) ``` --- ## Architecture Decisions | Decision | Choice | Reason | |----------|--------|--------| | Single `/summary` endpoint | Not per-tile fetch | Hub loads in one request; avoids 10 parallel queries on page load; backend aggregates efficiently with one DB round-trip | | Date range in URL | Not localStorage | Shareable link, bookmarkable, consistent state on refresh | | `report_shortcuts` per-user | Not tenant-wide | Report saved views are personal; sharing would require more complex ACL; per-user is YAGNI | | MEMBER sees own stats only | Not hidden from MEMBER | MEMBER can still track their own productivity (time, expenses); financial totals (org revenue) restricted to ADMIN/OWNER |