# Reports Page Design (`/{portSlug}/reports`) > **Status:** Design doc. All Q-block decisions locked 2026-05-24 via AskUserQuestion in the alpha UAT master doc. Implementation phased into discrete PRs at the end. ## Goals & non-goals **Goals** - Promote PDF report generation from a cramped dashboard dialog (~25 widgets and growing) to a dedicated landing + builder page. - Support saved-template management (rename / archive / share-with-team / duplicate). - Add run history so reps can answer "send me the same report Sarah ran last month." - Scheduled recurring reports (weekly / monthly / quarterly) with per-recipient email delivery. - One-click "Generate & email" alongside "Generate & download." - CSV + PNG/JPEG chart-snapshot outputs alongside the existing PDF. - Per-report metadata overrides: title, subtitle, cover-page branding swap. **Non-goals (v1)** - Excel workbook output (`xlsx`) — defer; PDF + CSV cover the asks. - Public hosted-HTML share-link to a report — defer. - Cover-page intro paragraph + footer/sign-off — defer; title/subtitle is enough. - A separate "Reports admin" page; admin controls live alongside the same `/reports` surface gated by `reports.admin`. --- ## Routing ``` /{portSlug}/reports ├── (default view) Landing: every report kind as a card with "Generate" CTA + the port's saved templates ├── /[kind] Per-report-kind builder (two-panel: sections checklist + live preview) ├── /templates Shared-templates manager (rename / archive / duplicate / share) ├── /runs Run history (re-run / re-email) └── /schedules Active recurring schedules (pause / edit recipients / cadence) ``` The existing dashboard "Export as PDF" button is rewired to navigate to `/{portSlug}/reports/dashboard?range=YYYY-MM-DD..YYYY-MM-DD` with the active date range pre-filled. One-click access preserved; rep lands in the full builder with everything pre-selected and the PDF preview ready. --- ## Data model Three new tables. ### `report_templates_shared` Per-port, port-scoped, optionally shared with the whole team. ```sql CREATE TABLE report_templates_shared ( id text PRIMARY KEY DEFAULT gen_random_uuid()::text, port_id text NOT NULL REFERENCES ports(id) ON DELETE CASCADE, name text NOT NULL, description text, -- The report-kind union ('dashboard' | 'website-analytics' | 'client-summary' | 'interest-summary' | 'berth-spec' | 'occupancy' | …). -- Same vocabulary the existing PDF exporter uses. kind text NOT NULL, -- Widget selection + per-widget option overrides + report metadata. config jsonb NOT NULL, -- 'private' = creator only; 'team' = anyone with reports.export at this port. visibility text NOT NULL DEFAULT 'private', created_by text NOT NULL REFERENCES "user"(id) ON DELETE RESTRICT, archived_at timestamptz, created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now() ); CREATE INDEX report_templates_shared_port_kind_idx ON report_templates_shared(port_id, kind); CREATE INDEX report_templates_shared_port_visibility_idx ON report_templates_shared(port_id, visibility); ``` Notes: - `config.sections: string[]` — widget ids, same shape as today's dialog. - `config.dateRange: { from?: string, to?: string, mode?: 'last_7' | 'last_30' | 'last_90' | 'custom' }` — saved templates default to relative ranges so a "Weekly snapshot" template stays fresh. - `config.metadata: { title?: string, subtitle?: string, brandingPortId?: string }` — `brandingPortId` lets the report use another port's logo/colour on the cover (admin-only). - `config.kindOptions` — per-kind option bag; e.g. for `website-analytics` the country filter, for `client-summary` the client-id. - Partial unique on `(port_id, lower(name)) where archived_at is null` — no two active templates share a name per port. ### `report_runs` Append-only audit log of every generated report. ```sql CREATE TABLE report_runs ( id text PRIMARY KEY DEFAULT gen_random_uuid()::text, port_id text NOT NULL REFERENCES ports(id) ON DELETE CASCADE, -- Nullable: ad-hoc runs (no template) still get logged. template_id text REFERENCES report_templates_shared(id) ON DELETE SET NULL, schedule_id text REFERENCES report_schedules(id) ON DELETE SET NULL, kind text NOT NULL, config jsonb NOT NULL, -- snapshotted at run time so re-runs reproduce identically output_format text NOT NULL, -- 'pdf' | 'csv' | 'png' | 'jpg' -- Storage key of the rendered artefact. Same backend as files (s3 or filesystem). storage_key text, size_bytes integer, status text NOT NULL DEFAULT 'pending', -- 'pending' | 'rendering' | 'complete' | 'failed' error_message text, triggered_by text NOT NULL, -- 'user' | 'schedule' triggered_by_user_id text REFERENCES "user"(id) ON DELETE SET NULL, -- When non-null, this run was emailed to these recipients on completion. emailed_to jsonb, -- Array<{ name?: string, email: string }> emailed_at timestamptz, created_at timestamptz NOT NULL DEFAULT now(), completed_at timestamptz ); CREATE INDEX report_runs_port_created_idx ON report_runs(port_id, created_at DESC); CREATE INDEX report_runs_port_user_idx ON report_runs(port_id, triggered_by_user_id); CREATE INDEX report_runs_port_template_idx ON report_runs(port_id, template_id) WHERE template_id IS NOT NULL; ``` ### `report_schedules` ```sql CREATE TABLE report_schedules ( id text PRIMARY KEY DEFAULT gen_random_uuid()::text, port_id text NOT NULL REFERENCES ports(id) ON DELETE CASCADE, template_id text NOT NULL REFERENCES report_templates_shared(id) ON DELETE CASCADE, -- 'weekly_monday_9' | 'monthly_first_9' | 'quarterly_first_9' to start; cron string optional later. cadence text NOT NULL, recipients jsonb NOT NULL, -- Array<{ name?: string, email: string }> output_format text NOT NULL DEFAULT 'pdf', enabled boolean NOT NULL DEFAULT true, last_run_at timestamptz, next_run_at timestamptz NOT NULL, -- pre-computed for the BullMQ scheduler created_by text NOT NULL REFERENCES "user"(id) ON DELETE RESTRICT, created_at timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now() ); CREATE INDEX report_schedules_port_enabled_next_idx ON report_schedules(port_id, enabled, next_run_at); ``` A schedule lifecycle: 1. Created via the builder ("Schedule recurring" panel) or `/schedules` page. 2. BullMQ cron checks every 15 min for `enabled=true AND next_run_at <= now()`. 3. For each match: create a `report_runs` row (`triggered_by='schedule'`), enqueue the rendering job, then advance `next_run_at` based on cadence. 4. Rendering job completes → email job fires with the storage key. --- ## API surface (`/api/v1/reports/*`) | Verb | Path | Permission | Notes | | ------ | ------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POST | `/api/v1/reports/generate` | `reports.export` | One-shot generate. Body: `{ kind, config, outputFormat?, deliverTo?: { recipients[] } }`. Returns `{ runId, downloadUrl }` (presigned) or fires email job when `deliverTo` set. | | GET | `/api/v1/reports/templates` | `reports.export` | Lists templates visible to the caller (own private + team-shared). | | POST | `/api/v1/reports/templates` | `reports.export` | Create a template (visibility defaults to `private`). | | PATCH | `/api/v1/reports/templates/[id]` | `reports.export`\* | Update name / description / config. `*` Only the creator OR holders of `reports.admin` can edit team-shared templates. | | DELETE | `/api/v1/reports/templates/[id]` | `reports.admin` | Soft-delete (sets `archived_at`). Frontend uses "Archive" copy. | | POST | `/api/v1/reports/templates/[id]/duplicate` | `reports.export` | Returns a copy owned by caller, visibility=`private`. | | GET | `/api/v1/reports/runs` | `reports.export` | Run history. Filter params: `templateId`, `userId`, `kind`, `from`, `to`. | | POST | `/api/v1/reports/runs/[id]/re-run` | `reports.export` | Generates a fresh run with the original snapshotted config + same recipients (when triggered_by=schedule). | | GET | `/api/v1/reports/runs/[id]/download` | `reports.export` | Presigned URL for the run artefact. | | GET | `/api/v1/reports/schedules` | `reports.admin` | List scheduled jobs. | | POST | `/api/v1/reports/schedules` | `reports.admin` | Create a schedule. | | PATCH | `/api/v1/reports/schedules/[id]` | `reports.admin` | Pause / edit / change recipients. | | DELETE | `/api/v1/reports/schedules/[id]` | `reports.admin` | Remove. | | GET | `/api/v1/reports/availability?kind=...&...` | `reports.export` | Lightweight per-widget presence check (drives the empty-state pills in the builder; already speced in B2 audit). | Existing `POST /api/v1/reports/generate` stays — it's the foundation. New endpoints layer on top. --- ## Permissions Two perms (locked decision): - **`reports.export`** — generate + download + manage own private templates. Default ON for `super_admin`, `director`, `sales_manager`, `sales_agent`, `finance_manager`. OFF for `viewer`, `residential_partner`. - **`reports.admin`** — manage BOTH team-shared templates AND schedules. Default ON for `super_admin` only. Seed via `src/lib/db/seed-permissions.ts` in the same PR that adds the schema. --- ## BullMQ queue + cron handler Two new queues: - **`reports-render`** — per-run render job. Consumed by `src/jobs/processors/report-render.ts`. Steps: 1. Resolve the run's config + storage key. 2. Run kind-specific resolver (already wired for `dashboard` and `website-analytics`; new ones get a registry entry). 3. Render to `outputFormat` (PDF via existing `pdfme`+`pdf-lib` path; CSV via shared resolver-to-csv helper; PNG/JPEG via puppeteer-snapshot of each chart). 4. Upload to storage, update `report_runs` row with `storage_key`, `size_bytes`, `status='complete'`. 5. If `triggered_by='schedule'` (schedule has recipients) — enqueue `reports-email` follow-up. - **`reports-email`** — fan-out email delivery. Consumed by `src/jobs/processors/report-email.ts`. Uses existing transactional-email infra (`sendBrandedEmail`) with the run artefact as an attachment OR a 7-day signed link when over the per-port attachment threshold. A cron-style `reports-scheduler` BullMQ recurring job fires every 15 min: 1. `SELECT id FROM report_schedules WHERE enabled = TRUE AND next_run_at <= now() ORDER BY next_run_at`. 2. For each: create the `report_runs` row + enqueue `reports-render` + UPDATE `next_run_at` based on cadence (helpers in `src/lib/services/report-schedule.service.ts`). --- ## UI plan ### 1. Landing — `/{portSlug}/reports` Two-column layout: - **Left rail**: report-kind cards (Dashboard, Website Analytics, Client Summary, Interest Summary, Berth Spec, Occupancy, …). Each card shows last-run timestamp + "Generate" CTA opening that kind's builder. - **Right column**: tabs for "My templates" (private), "Team templates" (shared), "Recent runs" (last 10). Filtered by `reports.export`/`reports.admin` so a `viewer` never sees the page at all. ### 2. Builder — `/{portSlug}/reports/[kind]` Full-page two-panel layout (the locked Q2 shape): ``` ┌────────────────────────────────────┬────────────────────────────────┐ │ Title + subtitle inputs │ │ │ Date range picker │ │ │ ─── Sections (grouped by domain) ──│ Live PDF preview │ │ ☑ Summary │ (re-renders on each │ │ ☐ Pipeline │ toggle, debounced 200ms)│ │ ☑ Berths │ │ │ ☑ Lead sources │ │ │ ☐ Operations │ │ │ ─── Output ─────────────────────── │ │ │ ◉ PDF │ │ │ ◯ CSV │ │ │ ◯ PNG (per chart) │ │ │ ─── Delivery ────────────────────── │ │ │ ◯ Download │ │ │ ◯ Email — recipient list │ │ │ ─── Save / Schedule ─────────────── │ │ │ [ Save as template ] [ Schedule…] │ │ └────────────────────────────────────┴────────────────────────────────┘ ``` Per-section row shows the existing "data availability" pill from the B2 audit (`ok` / `no_data` / `needs_window` / `partial`) plus a drag-handle to reorder (locked Q9 polish). ### 3. Templates manager — `/{portSlug}/reports/templates` Table of every visible template with columns: name · kind · visibility · last-used · created-by. Row actions: Open in builder · Rename · Duplicate · Share with team (gated on `reports.admin` for shared ones) · Archive. ### 4. Run history — `/{portSlug}/reports/runs` Server-paginated table. Columns: when · who · template name · kind · format · status · size · re-run / re-email / download. ### 5. Schedules — `/{portSlug}/reports/schedules` Table of active schedules. Columns: template · cadence · recipients · last run · next run · enabled toggle · edit. --- ## Quick-path dashboard button The existing `` (`src/components/reports/export-dashboard-pdf-button.tsx`) is rewired to navigate to `/{portSlug}/reports/dashboard?range=...` instead of opening the in-dashboard dialog. The dialog logic moves into the builder page wholesale (same checklist + same preview component). One-click access preserved; the bigger surface gives reps room to breathe. --- ## Phased PR plan | PR | Scope | Effort | Ships independently | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------- | | **P1: Schema + perms** | `0084_reports_page.sql` (3 tables + indexes) + seed `reports.export` / `reports.admin` perms + service skeleton (`report-template.service.ts`, `report-run.service.ts`, `report-schedule.service.ts`). No UI changes. | ~4 h | Yes (no behavioural change) | | **P2: Templates API** | CRUD routes for `report_templates_shared` + `report_runs` (read-only at this stage). Mount under `/api/v1/reports/templates` + `/api/v1/reports/runs`. Vitest coverage. | ~4 h | Yes | | **P3: Schedules API + cron** | `/api/v1/reports/schedules` CRUD + BullMQ `reports-scheduler` recurring job + `reports-render` + `reports-email` queues. Renderer reuses the existing PDF path. Vitest + integration tests. | ~8 h | Yes | | **P4: Landing + builder UI** | `/{portSlug}/reports` landing + `/[kind]` builder. Migrate the existing dialog UI into the builder; delete the dialog. Dashboard button rewires to the builder. | ~10 h | Yes (templates/runs UIs still missing — they get a placeholder) | | **P5: Templates + Runs + Schedules pages** | Three sub-route pages, table UIs, row actions, modal forms for "Schedule…". | ~8 h | Yes | | **P6: CSV + PNG outputs** | Add output-format renderers; wire output radio in builder. | ~6 h | Yes | | **P7: Metadata overrides + branding swap** | Title/subtitle inputs + cover-page brand picker (admin-only). | ~3 h | Yes | Total: ~43 h spread across 7 PRs. --- ## Open follow-ups (intentionally deferred past v1) - Excel workbook output. - Public hosted-HTML share-link (write to `/api/public/reports/[id]` with a signed token). - Cover-page intro paragraph + footer/sign-off note. - Custom cron strings (today: enum cadence only — `weekly_monday_9` etc). - Per-user template visibility ('shared with specific users' beyond port-wide team). Capture in `docs/BACKLOG.md` after P5 ships.