add reports module with controller, service, and repository

apps/edr-freight-api/src/app.module.ts

@@ -89,6 +89,7 @@ import { CargoesModule } from "./modules/cargoes/cargoes.module";
 import { RoutesModule } from "./modules/routes/routes.module";
 import { WarehousesModule } from "./modules/warehouses/warehouses.module";
 import { OverviewModule } from "./modules/overview/overview.module";
+import { ReportsModule } from "./modules/reports/reports.module";
 import { UserTradeAccessModule } from "./modules/user-trade-access/user-trade-access.module";
 import { VehiclesModule } from "./modules/vehicles/vehicles.module";
 import { DriversModule } from "./modules/drivers/drivers.module";
@@ -207,6 +208,7 @@ import { LoginAudienceMiddleware } from "./modules/auth/login-audience.middlewar
     RoutesModule,
     WarehousesModule,
     OverviewModule,
+    ReportsModule,
     UserTradeAccessModule,
     VehiclesModule,
     DriversModule,

apps/edr-freight-api/src/modules/overview/dto/overview-response.dto.ts

@@ -1,6 +1,7 @@
 import { ApiProperty } from '@nestjs/swagger';
 
 export class OverviewBookingKpisDto {
+  @ApiProperty() total!: number;
   @ApiProperty() totalActive!: number;
   @ApiProperty() needsAction!: number;
   @ApiProperty() urgent!: number;
@@ -9,6 +10,7 @@ export class OverviewBookingKpisDto {
 }
 
 export class OverviewContractKpisDto {
+  @ApiProperty() total!: number;
   @ApiProperty() totalActive!: number;
   @ApiProperty() needsAction!: number;
   @ApiProperty() inApproval!: number;

apps/edr-freight-api/src/modules/overview/overview.repository.ts

@@ -39,6 +39,7 @@ const EXCLUDE_GENERAL_CONTRACT_BOOKINGS =
   "(booking.contract_kind IS NULL OR booking.contract_kind <> 'GENERAL')";
 
 export type OverviewBookingKpisRow = {
+  total: number;
   totalActive: number;
   needsAction: number;
   urgent: number;
@@ -58,6 +59,7 @@ export type OverviewRecentBookingRow = {
 };
 
 export type OverviewContractKpisRow = {
+  total: number;
   totalActive: number;
   needsAction: number;
   inApproval: number;
@@ -108,7 +110,8 @@ export class OverviewRepository {
     const scope = directionScopeSql("booking.trade_direction", dirs);
     const row = await this.bookingRepository
       .createQueryBuilder("booking")
-      .select(
+      .select("COUNT(*)::int", "total")
+      .addSelect(
         `COUNT(*) FILTER (WHERE booking.status NOT IN (:...closedStatuses) AND booking.status != 'DRAFT')::int`,
         "totalActive",
       )
@@ -140,6 +143,7 @@ export class OverviewRepository {
       .getRawOne<Record<string, string>>();
 
     return {
+      total: Number(row?.total ?? 0),
       totalActive: Number(row?.totalActive ?? 0),
       needsAction: Number(row?.needsAction ?? 0),
       urgent: Number(row?.urgent ?? 0),
@@ -845,7 +849,8 @@ export class OverviewRepository {
     const scope = directionScopeSql("contract.trade_direction", dirs);
     const row = await this.contractRepository
       .createQueryBuilder("contract")
-      .select(
+      .select("COUNT(*)::int", "total")
+      .addSelect(
         `COUNT(*) FILTER (WHERE contract.status NOT IN (:...closedStatuses) AND contract.status != 'DRAFT')::int`,
         "totalActive",
       )
@@ -876,6 +881,7 @@ export class OverviewRepository {
       .getRawOne<Record<string, string>>();
 
     return {
+      total: Number(row?.total ?? 0),
       totalActive: Number(row?.totalActive ?? 0),
       needsAction: Number(row?.needsAction ?? 0),
       inApproval: Number(row?.inApproval ?? 0),

apps/edr-freight-api/src/modules/reports/dto/report-query.dto.ts

@@ -0,0 +1,54 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsOptional, IsString } from 'class-validator';
+
+export class ReportQueryDto {
+  @ApiPropertyOptional({ description: 'Inclusive start date (YYYY-MM-DD). Default: 30 days ago.' })
+  @IsOptional()
+  @IsString()
+  dateFrom?: string;
+
+  @ApiPropertyOptional({ description: 'Inclusive end date (YYYY-MM-DD). Default: today.' })
+  @IsOptional()
+  @IsString()
+  dateTo?: string;
+
+  @ApiPropertyOptional({ enum: ['day', 'week', 'month'], default: 'day' })
+  @IsOptional()
+  @IsIn(['day', 'week', 'month'])
+  granularity?: 'day' | 'week' | 'month';
+
+  @ApiPropertyOptional({ description: 'Comma-separated company UUIDs' })
+  @IsOptional()
+  @IsString()
+  companyIds?: string;
+
+  @ApiPropertyOptional({ description: 'Comma-separated route UUIDs' })
+  @IsOptional()
+  @IsString()
+  routeIds?: string;
+
+  @ApiPropertyOptional({ description: 'Comma-separated yard UUIDs (matches origin or destination)' })
+  @IsOptional()
+  @IsString()
+  yardIds?: string;
+
+  @ApiPropertyOptional({ description: 'Comma-separated cargo type UUIDs' })
+  @IsOptional()
+  @IsString()
+  cargoTypeIds?: string;
+
+  @ApiPropertyOptional({ description: 'Comma-separated status values (report-specific)' })
+  @IsOptional()
+  @IsString()
+  statuses?: string;
+
+  @ApiPropertyOptional({ description: 'Trade direction filter' })
+  @IsOptional()
+  @IsString()
+  direction?: string;
+
+  @ApiPropertyOptional({ enum: ['CONTAINER', 'BULK'] })
+  @IsOptional()
+  @IsIn(['CONTAINER', 'BULK'])
+  freightType?: string;
+}

apps/edr-freight-api/src/modules/reports/dto/report-result.dto.ts

@@ -0,0 +1,24 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class ReportKpiDto {
+  @ApiProperty()
+  label!: string;
+
+  @ApiProperty()
+  value!: number;
+
+  @ApiPropertyOptional()
+  unit?: string;
+}
+
+export class ReportResultDto {
+  @ApiProperty({ type: [ReportKpiDto] })
+  kpis!: ReportKpiDto[];
+
+  @ApiProperty({
+    type: 'array',
+    items: { type: 'object', additionalProperties: true },
+    description: 'Report rows; columns vary per report key',
+  })
+  rows!: Record<string, unknown>[];
+}

apps/edr-freight-api/src/modules/reports/report-queries.ts

@@ -0,0 +1,450 @@
+import { DataSource } from 'typeorm';
+
+export interface ReportFilters {
+  /** ISO timestamp, inclusive lower bound. */
+  dateFrom: string;
+  /** ISO timestamp, exclusive upper bound. */
+  dateTo: string;
+  granularity: 'day' | 'week' | 'month';
+  companyIds: string[] | null;
+  routeIds: string[] | null;
+  yardIds: string[] | null;
+  cargoTypeIds: string[] | null;
+  statuses: string[] | null;
+  /** Trade-scope-resolved directions. null = unrestricted, [] = show nothing. */
+  directions: string[] | null;
+  freightType: string | null;
+}
+
+export interface ReportKpi {
+  label: string;
+  value: number;
+  unit?: string;
+}
+
+export interface ReportResult {
+  kpis: ReportKpi[];
+  rows: Record<string, unknown>[];
+}
+
+type ReportQuery = (ds: DataSource, f: ReportFilters) => Promise<ReportResult>;
+
+// For PER_ITEM bulk bookings cargo_total_weight_vgm holds an item COUNT, and
+// the real tonnage lives in bulk_total_weight_tons — hence the COALESCE order.
+const TONS = 'COALESCE(b.bulk_total_weight_tons, b.cargo_total_weight_vgm)';
+// adjusted_total_amount silently overrides total_amount when set.
+const REVENUE = 'COALESCE(b.adjusted_total_amount, b.total_amount)';
+// GENERAL contract_kind rows are umbrella contracts, not shipments; counting
+// them double-counts every child booking (same guard as overview.repository).
+const NOT_UMBRELLA = "(b.contract_kind IS NULL OR b.contract_kind <> 'GENERAL')";
+const DEAD_STATUSES = "'DRAFT','CANCELLED','REJECTED','EXPIRED'";
+
+const num = (v: unknown): number => (v === null || v === undefined ? 0 : Number(v));
+const sum = (rows: Record<string, unknown>[], col: string): number =>
+  rows.reduce((acc, r) => acc + num(r[col]), 0);
+
+/**
+ * Shared WHERE for booking-based reports (alias `b`).
+ * Params occupy $1..$8 in this fixed order; report SQL continues at $9.
+ */
+function bookingWhere(f: ReportFilters): { where: string; params: unknown[] } {
+  return {
+    where: `
+      b.deleted_at IS NULL
+      AND ${NOT_UMBRELLA}
+      AND b.created_at >= $1::timestamptz AND b.created_at < $2::timestamptz
+      AND ($3::uuid[] IS NULL OR b.company_id = ANY($3))
+      AND ($4::uuid[] IS NULL OR b.cargo_type_id = ANY($4))
+      AND ($5::text[] IS NULL OR b.trade_direction = ANY($5))
+      AND ($6::text IS NULL OR b.freight_type = $6)
+      AND (CASE WHEN $7::text[] IS NULL
+            THEN b.status NOT IN (${DEAD_STATUSES})
+            ELSE b.status = ANY($7) END)
+      AND ($8::uuid[] IS NULL OR b.origin_yard_id = ANY($8) OR b.destination_yard_id = ANY($8))`,
+    params: [
+      f.dateFrom,
+      f.dateTo,
+      f.companyIds,
+      f.cargoTypeIds,
+      f.directions,
+      f.freightType,
+      f.statuses,
+      f.yardIds,
+    ],
+  };
+}
+
+/**
+ * Direction scope for rows that reference a booking through a varchar id
+ * column (invoices.source_id, payments.ref_id). Rows not pointing at a
+ * booking stay visible — they carry no direction to scope by.
+ * (Positional-param port of trade-scope.util's bookingRefScopeSql.)
+ */
+const refDirScope = (refColumn: string, param: string): string => `
+  (${param}::text[] IS NULL OR NOT EXISTS (
+    SELECT 1 FROM freight.bookings sb
+    WHERE sb.id::text = ${refColumn} AND NOT (sb.trade_direction = ANY(${param}))))`;
+
+const bookingsTrend: ReportQuery = async (ds, f) => {
+  const { where, params } = bookingWhere(f);
+  const rows = await ds.query(
+    `SELECT to_char(date_trunc($9, b.created_at), 'YYYY-MM-DD') AS period,
+            COUNT(*)::int AS bookings,
+            ROUND(COALESCE(SUM(${TONS}), 0))::float8 AS tons,
+            ROUND(COALESCE(SUM(${REVENUE}), 0))::float8 AS revenue
+     FROM freight.bookings b
+     WHERE ${where}
+     GROUP BY 1 ORDER BY 1`,
+    [...params, f.granularity],
+  );
+  return {
+    kpis: [
+      { label: 'Bookings', value: sum(rows, 'bookings') },
+      { label: 'Tonnage', value: sum(rows, 'tons'), unit: 't' },
+      { label: 'Revenue', value: sum(rows, 'revenue'), unit: 'ETB' },
+    ],
+    rows,
+  };
+};
+
+const revenueByCustomer: ReportQuery = async (ds, f) => {
+  const { where, params } = bookingWhere(f);
+  const rows = await ds.query(
+    `SELECT c.name AS customer,
+            COUNT(*)::int AS bookings,
+            ROUND(COALESCE(SUM(${TONS}), 0))::float8 AS tons,
+            ROUND(COALESCE(SUM(${REVENUE}), 0))::float8 AS revenue
+     FROM freight.bookings b
+     JOIN freight.companies c ON c.id = b.company_id
+     WHERE ${where}
+     GROUP BY c.name ORDER BY revenue DESC LIMIT 100`,
+    params,
+  );
+  const total = sum(rows, 'revenue');
+  return {
+    kpis: [
+      { label: 'Customers', value: rows.length },
+      { label: 'Revenue', value: total, unit: 'ETB' },
+      {
+        label: 'Top customer share',
+        value: total > 0 ? Math.round((num(rows[0]?.revenue) / total) * 100) : 0,
+        unit: '%',
+      },
+    ],
+    rows,
+  };
+};
+
+const revenueByLane: ReportQuery = async (ds, f) => {
+  const { where, params } = bookingWhere(f);
+  const rows = await ds.query(
+    `SELECT o.label AS origin, d.label AS destination,
+            COUNT(*)::int AS bookings,
+            ROUND(COALESCE(SUM(${TONS}), 0))::float8 AS tons,
+            ROUND(COALESCE(SUM(${REVENUE}), 0))::float8 AS revenue
+     FROM freight.bookings b
+     JOIN freight.yards o ON o.id = b.origin_yard_id
+     JOIN freight.yards d ON d.id = b.destination_yard_id
+     WHERE ${where}
+     GROUP BY 1, 2 ORDER BY revenue DESC LIMIT 100`,
+    params,
+  );
+  return {
+    kpis: [
+      { label: 'Lanes', value: rows.length },
+      { label: 'Tonnage', value: sum(rows, 'tons'), unit: 't' },
+      { label: 'Revenue', value: sum(rows, 'revenue'), unit: 'ETB' },
+    ],
+    rows,
+  };
+};
+
+const contractUtilization: ReportQuery = async (ds, f) => {
+  const rows = await ds.query(
+    `SELECT ct.reference, c.name AS customer, ct.status, ct.contract_kind AS kind,
+            to_char(ct.contract_valid_from, 'YYYY-MM-DD') AS valid_from,
+            to_char(ct.contract_valid_until, 'YYYY-MM-DD') AS valid_until,
+            cap.committed::float8 AS committed,
+            booked.tons::float8 AS booked_tons,
+            booked.cnt AS bookings,
+            CASE WHEN cap.committed > 0
+                 THEN ROUND(booked.tons / cap.committed * 100)::float8 END AS utilization_pct
+     FROM freight.contracts ct
+     LEFT JOIN freight.companies c ON c.id = ct.company_id
+     LEFT JOIN LATERAL (
+       SELECT COALESCE(SUM(s.quantity_cap), 0) AS committed
+       FROM freight.contract_cargo_scope s
+       WHERE s.contract_id = ct.id AND s.deleted_at IS NULL) cap ON true
+     LEFT JOIN LATERAL (
+       SELECT COALESCE(SUM(${TONS}), 0) AS tons, COUNT(*)::int AS cnt
+       FROM freight.bookings b
+       WHERE b.contract_id = ct.id AND b.deleted_at IS NULL
+         AND b.status NOT IN (${DEAD_STATUSES})) booked ON true
+     WHERE ct.deleted_at IS NULL
+       AND ct.status NOT IN ('DRAFT')
+       AND ct.contract_valid_from < $2::timestamptz
+       AND (ct.contract_valid_until IS NULL OR ct.contract_valid_until >= $1::timestamptz)
+       AND ($3::uuid[] IS NULL OR ct.company_id = ANY($3))
+       AND ($4::text[] IS NULL OR ct.trade_direction = ANY($4))
+       AND ($5::text[] IS NULL OR ct.status = ANY($5))
+     ORDER BY utilization_pct DESC NULLS LAST LIMIT 200`,
+    [f.dateFrom, f.dateTo, f.companyIds, f.directions, f.statuses],
+  );
+  const capped = rows.filter((r: Record<string, unknown>) => num(r.committed) > 0);
+  return {
+    kpis: [
+      { label: 'Contracts', value: rows.length },
+      {
+        label: 'Avg utilization',
+        value: capped.length
+          ? Math.round(sum(capped, 'utilization_pct') / capped.length)
+          : 0,
+        unit: '%',
+      },
+      { label: 'Booked tonnage', value: sum(rows, 'booked_tons'), unit: 't' },
+    ],
+    rows,
+  };
+};
+
+// ponytail: 60-min departure grace is a constant; make it a query param if ops
+// ever wants a configurable threshold.
+const trainOnTime: ReportQuery = async (ds, f) => {
+  const rows = await ds.query(
+    `SELECT o.label AS origin, d.label AS destination,
+            COUNT(*)::int AS trips,
+            COUNT(*) FILTER (WHERE ts.actual_departure_at IS NOT NULL)::int AS departed,
+            ROUND(AVG(EXTRACT(EPOCH FROM (ts.actual_departure_at - ts.scheduled_departure_date)) / 60)
+              FILTER (WHERE ts.actual_departure_at IS NOT NULL))::float8 AS avg_dep_delay_min,
+            ROUND(AVG(EXTRACT(EPOCH FROM (ts.actual_arrival_at - ts.scheduled_arrival_date)) / 60)
+              FILTER (WHERE ts.actual_arrival_at IS NOT NULL
+                        AND ts.scheduled_arrival_date IS NOT NULL))::float8 AS avg_arr_delay_min,
+            ROUND(100.0 * COUNT(*) FILTER (WHERE ts.actual_departure_at
+                                             <= ts.scheduled_departure_date + interval '60 minutes')
+              / NULLIF(COUNT(*) FILTER (WHERE ts.actual_departure_at IS NOT NULL), 0))::float8 AS on_time_pct
+     FROM freight.train_schedules ts
+     JOIN freight.yards o ON o.id = ts.origin_station_id
+     JOIN freight.yards d ON d.id = ts.destination_station_id
+     WHERE ts.deleted_at IS NULL
+       AND ts.status IN ('DISPATCHED', 'ARRIVED')
+       AND ts.scheduled_departure_date >= $1::timestamptz
+       AND ts.scheduled_departure_date < $2::timestamptz
+       AND ($3::uuid[] IS NULL OR ts.route_id = ANY($3))
+       AND ($4::text[] IS NULL OR ts.direction = ANY($4))
+       AND ($5::uuid[] IS NULL OR ts.origin_station_id = ANY($5) OR ts.destination_station_id = ANY($5))
+     GROUP BY 1, 2 ORDER BY trips DESC`,
+    [f.dateFrom, f.dateTo, f.routeIds, f.directions, f.yardIds],
+  );
+  const departed = sum(rows, 'departed');
+  const weighted = rows.reduce(
+    (acc: number, r: Record<string, unknown>) =>
+      acc + (num(r.on_time_pct) * num(r.departed)) / 100,
+    0,
+  );
+  return {
+    kpis: [
+      { label: 'Trips', value: sum(rows, 'trips') },
+      {
+        label: 'On-time departures',
+        value: departed > 0 ? Math.round((weighted / departed) * 100) : 0,
+        unit: '%',
+      },
+      {
+        label: 'Avg departure delay',
+        value: rows.length ? Math.round(sum(rows, 'avg_dep_delay_min') / rows.length) : 0,
+        unit: 'min',
+      },
+    ],
+    rows,
+  };
+};
+
+const scheduleFillRate: ReportQuery = async (ds, f) => {
+  const rows = await ds.query(
+    `SELECT ts.train_number, ts.reference,
+            to_char(ts.scheduled_departure_date, 'YYYY-MM-DD') AS departure,
+            o.label AS origin, d.label AS destination, ts.direction, ts.status,
+            ts.max_wagons, tset.wagon_count,
+            ROUND(w.cap_tons)::float8 AS capacity_tons,
+            ROUND(w.booked_tons)::float8 AS booked_tons,
+            CASE WHEN w.cap_tons > 0
+                 THEN ROUND(w.booked_tons / w.cap_tons * 100)::float8 END AS fill_pct
+     FROM freight.train_schedules ts
+     JOIN freight.yards o ON o.id = ts.origin_station_id
+     JOIN freight.yards d ON d.id = ts.destination_station_id
+     LEFT JOIN freight.train_sets tset ON tset.id = ts.train_set_id
+     LEFT JOIN LATERAL (
+       SELECT COALESCE(SUM(tw.capacity_tons), 0) AS cap_tons,
+              COALESCE(SUM(tw.assigned_weight_tons), 0) AS booked_tons
+       FROM freight.train_set_wagons tw
+       WHERE tw.train_set_id = ts.train_set_id AND tw.deleted_at IS NULL) w ON true
+     WHERE ts.deleted_at IS NULL
+       AND ts.status <> 'CANCELLED'
+       AND ts.scheduled_departure_date >= $1::timestamptz
+       AND ts.scheduled_departure_date < $2::timestamptz
+       AND ($3::uuid[] IS NULL OR ts.route_id = ANY($3))
+       AND ($4::text[] IS NULL OR ts.direction = ANY($4))
+       AND ($5::uuid[] IS NULL OR ts.origin_station_id = ANY($5) OR ts.destination_station_id = ANY($5))
+     ORDER BY ts.scheduled_departure_date DESC LIMIT 200`,
+    [f.dateFrom, f.dateTo, f.routeIds, f.directions, f.yardIds],
+  );
+  const withCap = rows.filter((r: Record<string, unknown>) => num(r.capacity_tons) > 0);
+  const capTons = sum(withCap, 'capacity_tons');
+  return {
+    kpis: [
+      { label: 'Schedules', value: rows.length },
+      {
+        label: 'Avg fill rate',
+        value: capTons > 0 ? Math.round((sum(withCap, 'booked_tons') / capTons) * 100) : 0,
+        unit: '%',
+      },
+      { label: 'Booked tonnage', value: sum(rows, 'booked_tons'), unit: 't' },
+    ],
+    rows,
+  };
+};
+
+const tripsPerRoute: ReportQuery = async (ds, f) => {
+  const rows = await ds.query(
+    `SELECT o.label AS origin, d.label AS destination, ts.direction,
+            COUNT(*)::int AS trips,
+            ROUND(COALESCE(SUM(w.booked_tons), 0))::float8 AS tons_hauled,
+            ROUND(COALESCE(AVG(w.booked_tons), 0))::float8 AS avg_tons_per_trip
+     FROM freight.train_schedules ts
+     JOIN freight.yards o ON o.id = ts.origin_station_id
+     JOIN freight.yards d ON d.id = ts.destination_station_id
+     LEFT JOIN LATERAL (
+       SELECT COALESCE(SUM(tw.assigned_weight_tons), 0) AS booked_tons
+       FROM freight.train_set_wagons tw
+       WHERE tw.train_set_id = ts.train_set_id AND tw.deleted_at IS NULL) w ON true
+     WHERE ts.deleted_at IS NULL
+       AND ts.status IN ('DISPATCHED', 'ARRIVED')
+       AND ts.scheduled_departure_date >= $1::timestamptz
+       AND ts.scheduled_departure_date < $2::timestamptz
+       AND ($3::uuid[] IS NULL OR ts.route_id = ANY($3))
+       AND ($4::text[] IS NULL OR ts.direction = ANY($4))
+       AND ($5::uuid[] IS NULL OR ts.origin_station_id = ANY($5) OR ts.destination_station_id = ANY($5))
+     GROUP BY 1, 2, 3 ORDER BY trips DESC`,
+    [f.dateFrom, f.dateTo, f.routeIds, f.directions, f.yardIds],
+  );
+  return {
+    kpis: [
+      { label: 'Trips', value: sum(rows, 'trips') },
+      { label: 'Routes served', value: rows.length },
+      { label: 'Tonnage hauled', value: sum(rows, 'tons_hauled'), unit: 't' },
+    ],
+    rows,
+  };
+};
+
+const invoicedVsCollected: ReportQuery = async (ds, f) => {
+  const rows = await ds.query(
+    `SELECT to_char(date_trunc($5, COALESCE(i.issued_at, i.created_at)), 'YYYY-MM-DD') AS period,
+            COUNT(*)::int AS invoices,
+            ROUND(SUM(i.total_amount))::float8 AS invoiced,
+            ROUND(SUM(i.paid_amount))::float8 AS collected,
+            ROUND(SUM(i.balance_amount))::float8 AS outstanding
+     FROM freight.invoices i
+     WHERE i.deleted_at IS NULL
+       AND i.status NOT IN ('DRAFT', 'CANCELLED')
+       AND COALESCE(i.issued_at, i.created_at) >= $1::timestamptz
+       AND COALESCE(i.issued_at, i.created_at) < $2::timestamptz
+       AND ($3::uuid[] IS NULL OR i.company_id = ANY($3))
+       AND ${refDirScope('i.source_id', '$4')}
+     GROUP BY 1 ORDER BY 1`,
+    [f.dateFrom, f.dateTo, f.companyIds, f.directions, f.granularity],
+  );
+  const invoiced = sum(rows, 'invoiced');
+  const collected = sum(rows, 'collected');
+  return {
+    kpis: [
+      { label: 'Invoiced', value: invoiced, unit: 'ETB' },
+      { label: 'Collected', value: collected, unit: 'ETB' },
+      {
+        label: 'Collection rate',
+        value: invoiced > 0 ? Math.round((collected / invoiced) * 100) : 0,
+        unit: '%',
+      },
+      { label: 'Outstanding', value: sum(rows, 'outstanding'), unit: 'ETB' },
+    ],
+    rows,
+  };
+};
+
+// Aging is an as-of snapshot: dateTo is the as-of moment, dateFrom is ignored.
+const agingReceivables: ReportQuery = async (ds, f) => {
+  const rows = await ds.query(
+    `SELECT c.name AS customer,
+            COUNT(*)::int AS invoices,
+            ROUND(SUM(i.balance_amount))::float8 AS outstanding,
+            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at >= $1::timestamptz), 0))::float8 AS current,
+            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < $1::timestamptz
+              AND i.due_at >= $1::timestamptz - interval '30 days'), 0))::float8 AS overdue_0_30,
+            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < $1::timestamptz - interval '30 days'
+              AND i.due_at >= $1::timestamptz - interval '60 days'), 0))::float8 AS overdue_31_60,
+            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < $1::timestamptz - interval '60 days'
+              AND i.due_at >= $1::timestamptz - interval '90 days'), 0))::float8 AS overdue_61_90,
+            ROUND(COALESCE(SUM(i.balance_amount) FILTER (WHERE i.due_at < $1::timestamptz - interval '90 days'), 0))::float8 AS overdue_90_plus
+     FROM freight.invoices i
+     JOIN freight.companies c ON c.id = i.company_id
+     WHERE i.deleted_at IS NULL
+       AND i.status IN ('ISSUED', 'PENDING', 'PARTIALLY_PAID', 'OVERDUE')
+       AND i.balance_amount > 0
+       AND i.created_at < $1::timestamptz
+       AND ($2::uuid[] IS NULL OR i.company_id = ANY($2))
+       AND ${refDirScope('i.source_id', '$3')}
+     GROUP BY 1 ORDER BY outstanding DESC LIMIT 200`,
+    [f.dateTo, f.companyIds, f.directions],
+  );
+  const outstanding = sum(rows, 'outstanding');
+  return {
+    kpis: [
+      { label: 'Outstanding', value: outstanding, unit: 'ETB' },
+      { label: 'Overdue', value: outstanding - sum(rows, 'current'), unit: 'ETB' },
+      { label: 'Customers with balance', value: rows.length },
+    ],
+    rows,
+  };
+};
+
+const revenueByPaymentMethod: ReportQuery = async (ds, f) => {
+  // payments.status values are lowercase-hyphenated ('success'), unlike every
+  // other status enum in the schema. No deleted_at on this table.
+  const rows = await ds.query(
+    `SELECT p.method::text AS method,
+            COUNT(*)::int AS payments,
+            ROUND(SUM(p.amount))::float8 AS amount
+     FROM freight.payments p
+     WHERE p.status = 'success'
+       AND p.created_at >= $1::timestamptz AND p.created_at < $2::timestamptz
+       AND ${refDirScope('p.ref_id', '$3')}
+     GROUP BY 1 ORDER BY amount DESC`,
+    [f.dateFrom, f.dateTo, f.directions],
+  );
+  const total = sum(rows, 'amount');
+  return {
+    kpis: [
+      { label: 'Collected', value: total, unit: 'ETB' },
+      { label: 'Payments', value: sum(rows, 'payments') },
+      {
+        label: 'Top method share',
+        value: total > 0 ? Math.round((num(rows[0]?.amount) / total) * 100) : 0,
+        unit: '%',
+      },
+    ],
+    rows,
+  };
+};
+
+export const REPORT_QUERIES: Record<string, ReportQuery> = {
+  'bookings-trend': bookingsTrend,
+  'revenue-by-customer': revenueByCustomer,
+  'revenue-by-lane': revenueByLane,
+  'contract-utilization': contractUtilization,
+  'train-on-time': trainOnTime,
+  'schedule-fill-rate': scheduleFillRate,
+  'trips-per-route': tripsPerRoute,
+  'invoiced-vs-collected': invoicedVsCollected,
+  'aging-receivables': agingReceivables,
+  'revenue-by-payment-method': revenueByPaymentMethod,
+};

apps/edr-freight-api/src/modules/reports/reports.controller.ts

@@ -0,0 +1,33 @@
+import { Controller, Get, Param, Query } from '@nestjs/common';
+import { ApiBearerAuth, ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { CurrentUser } from '@edr/api-common';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+
+import { BookingView } from '../../common/booking-guards';
+import { UserTradeAccessService } from '../user-trade-access/user-trade-access.service';
+import { ReportQueryDto } from './dto/report-query.dto';
+import { ReportResultDto } from './dto/report-result.dto';
+import { ReportsService } from './reports.service';
+
+@ApiTags('Reports')
+@ApiBearerAuth()
+@Controller('reports')
+export class ReportsController {
+  constructor(
+    private readonly reportsService: ReportsService,
+    private readonly userTradeAccessService: UserTradeAccessService,
+  ) {}
+
+  @Get(':key')
+  @BookingView()
+  @ApiOperation({ summary: 'Run a canned report by key with optional filters' })
+  @ApiOkResponse({ type: ReportResultDto })
+  async run(
+    @Param('key') key: string,
+    @Query() query: ReportQueryDto,
+    @CurrentUser() user: TCurrentUser,
+  ): Promise<ReportResultDto> {
+    const allowed = await this.userTradeAccessService.resolveAllowedDirections(user);
+    return this.reportsService.run(key, query, allowed);
+  }
+}

apps/edr-freight-api/src/modules/reports/reports.module.ts

@@ -0,0 +1,13 @@
+import { Module } from '@nestjs/common';
+
+import { UserTradeAccessModule } from '../user-trade-access/user-trade-access.module';
+import { ReportsController } from './reports.controller';
+import { ReportsRepository } from './reports.repository';
+import { ReportsService } from './reports.service';
+
+@Module({
+  imports: [UserTradeAccessModule],
+  controllers: [ReportsController],
+  providers: [ReportsService, ReportsRepository],
+})
+export class ReportsModule {}

apps/edr-freight-api/src/modules/reports/reports.repository.ts

@@ -0,0 +1,14 @@
+import { Injectable } from '@nestjs/common';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { DataSource } from 'typeorm';
+
+import { REPORT_QUERIES, ReportFilters, ReportResult } from './report-queries';
+
+@Injectable()
+export class ReportsRepository {
+  constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
+
+  run(key: keyof typeof REPORT_QUERIES, filters: ReportFilters): Promise<ReportResult> {
+    return REPORT_QUERIES[key](this.dataSource, filters);
+  }
+}

apps/edr-freight-api/src/modules/reports/reports.service.ts

@@ -0,0 +1,45 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+
+import { scopedDirections } from '../user-trade-access/trade-scope.util';
+import { ReportQueryDto } from './dto/report-query.dto';
+import { REPORT_QUERIES, ReportFilters, ReportResult } from './report-queries';
+import { ReportsRepository } from './reports.repository';
+import type { Freight } from '@edr/types';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const list = (csv?: string): string[] | null => {
+  const items = csv?.split(',').map((s) => s.trim()).filter(Boolean) ?? [];
+  return items.length ? items : null;
+};
+
+@Injectable()
+export class ReportsService {
+  constructor(private readonly repository: ReportsRepository) {}
+
+  run(
+    key: string,
+    dto: ReportQueryDto,
+    allowedDirections: Freight.ScheduleTradeDirection[] | null,
+  ): Promise<ReportResult> {
+    if (!(key in REPORT_QUERIES)) {
+      throw new NotFoundException(`Unknown report: ${key}`);
+    }
+    const to = dto.dateTo ? new Date(dto.dateTo) : new Date();
+    const from = dto.dateFrom ? new Date(dto.dateFrom) : new Date(to.getTime() - 30 * DAY_MS);
+    const filters: ReportFilters = {
+      dateFrom: from.toISOString(),
+      // dateTo is inclusive in the API; queries treat the bound as exclusive.
+      dateTo: new Date(to.getTime() + DAY_MS).toISOString(),
+      granularity: dto.granularity ?? 'day',
+      companyIds: list(dto.companyIds),
+      routeIds: list(dto.routeIds),
+      yardIds: list(dto.yardIds),
+      cargoTypeIds: list(dto.cargoTypeIds),
+      statuses: list(dto.statuses),
+      directions: scopedDirections(allowedDirections, dto.direction),
+      freightType: dto.freightType ?? null,
+    };
+    return this.repository.run(key, filters);
+  }
+}

apps/edr-freight-web/backoffice/src/App.tsx

@@ -2,6 +2,7 @@ import {
   ArrowLeftRight,
   Boxes,
   Building2,
+  BarChart3,
   Container,
   FileSignature,
   FileText,
@@ -71,6 +72,8 @@ import InvoiceDetailPage from "./pages/invoices/InvoiceDetailPage";
 import InvoicesPage from "./pages/invoices/InvoicesPage";
 import MyProfilePage from "./pages/dashboard/MyProfilePage";
 import OverviewPage from "./pages/dashboard/OverviewPage";
+import ReportsHubPage from "./pages/reports/ReportsHubPage";
+import ReportPage from "./pages/reports/ReportPage";
 import AiBookingMockTestPage from "./pages/ai/AiBookingMockTestPage";
 import PaymentsPage from "./pages/payments/PaymentsPage";
 //import EmployeesPage from "./pages/dashboard/user-management/EmployeesPage";
@@ -154,6 +157,12 @@ const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[] => [
         icon: <LayoutDashboard />,
         permission: FREIGHT_PERMS.overview.view,
       },
+      {
+        label: "Reports",
+        href: "/dashboard/reports",
+        icon: <BarChart3 />,
+        permission: FREIGHT_PERMS.bookings.view,
+      },
       {
         label: "Customers",
         href: "/dashboard/customers",
@@ -823,6 +832,8 @@ const App = () => {
       />
       <Route path="/dashboard" element={<DashboardShell />}>
         <Route path="overview" element={<OverviewPage />} />
+        <Route path="reports" element={<ReportsHubPage />} />
+        <Route path="reports/:reportKey" element={<ReportPage />} />
         {/* Dev/testing page for the mock AI booking assistant. */}
         <Route
           path="ai-booking-mock-test"

apps/edr-freight-web/backoffice/src/components/overview/OverviewQuickLinks.tsx

@@ -1,90 +0,0 @@
-import { useNavigate } from "react-router-dom";
-import { ArrowRight, FileText, Train, Users } from "lucide-react";
-import { Card, Group, SimpleGrid, Stack, Text, ThemeIcon } from "@mantine/core";
-
-import { useAuth } from "@/auth/useAuth";
-import { FREIGHT_PERMS, hasPermission } from "@/lib/permissions";
-
-const links = [
-  {
-    title: "Booking requests",
-    description: "Review and action incoming freight bookings",
-    href: "/dashboard/booking-requests",
-    icon: FileText,
-    permission: [FREIGHT_PERMS.bookings.view],
-  },
-  {
-    title: "Train scheduling v2",
-    description: "Full allocation workflow — assign, pin wagons, finalize",
-    href: "/dashboard/operations/train-scheduling-v2",
-    icon: Train,
-    permission: [FREIGHT_PERMS.trainScheduling.view],
-  },
-  {
-    title: "Trains",
-    description: "Manage train master data and fleet status",
-    href: "/dashboard/trains",
-    icon: Train,
-    permission: [FREIGHT_PERMS.fleet.view, FREIGHT_PERMS.trains.view],
-  },
-  {
-    title: "User management",
-    description: "Employees, roles, and permissions",
-    href: "/user-management",
-    icon: Users,
-    permission: [
-      FREIGHT_PERMS.admin,
-      FREIGHT_PERMS.staff.roles.view,
-      FREIGHT_PERMS.staff.employeeRegistration.view,
-      FREIGHT_PERMS.staff.roleAssignment.view,
-    ],
-  },
-];
-
-export function OverviewQuickLinks() {
-  const navigate = useNavigate();
-  const { user } = useAuth();
-
-  const visible = links.filter((link) =>
-    link.permission.some((key) => hasPermission(user, key)),
-  );
-  if (!visible.length) return null;
-
-  return (
-    <Stack gap="md" h="100%">
-      <Text fw={600}>Quick links</Text>
-      <SimpleGrid cols={{ base: 1, sm: 2 }} spacing="sm">
-        {visible.map((link) => {
-          const Icon = link.icon;
-          return (
-            <Card
-              key={link.href}
-              p="md"
-              radius="lg"
-              withBorder
-              style={{ cursor: "pointer" }}
-              onClick={() => navigate(link.href)}
-            >
-              <Group justify="space-between" align="flex-start" wrap="nowrap">
-                <Group align="flex-start" gap="sm" wrap="nowrap">
-                  <ThemeIcon variant="light" color="edr-green" size="lg" radius="md">
-                    <Icon size={18} />
-                  </ThemeIcon>
-                  <Stack gap={2}>
-                    <Text fw={600} size="sm">
-                      {link.title}
-                    </Text>
-                    <Text size="xs" c="dimmed">
-                      {link.description}
-                    </Text>
-                  </Stack>
-                </Group>
-                <ArrowRight size={16} color="var(--mantine-color-gray-5)" />
-              </Group>
-            </Card>
-          );
-        })}
-      </SimpleGrid>
-    </Stack>
-  );
-}

apps/edr-freight-web/backoffice/src/components/overview/OverviewTabContent.tsx

@@ -14,6 +14,7 @@ import { OverviewBillingTabPanel } from "./tabs/OverviewBillingTabPanel";
 import { OverviewBookingsTabPanel } from "./tabs/OverviewBookingsTabPanel";
 import { OverviewContractsTabPanel } from "./tabs/OverviewContractsTabPanel";
 import { OverviewCustomersTabPanel } from "./tabs/OverviewCustomersTabPanel";
+import { OverviewFleetTabPanel } from "./tabs/OverviewFleetTabPanel";
 import { OverviewOperationsTabPanel } from "./tabs/OverviewOperationsTabPanel";
 import { OverviewStaffTabPanel } from "./tabs/OverviewStaffTabPanel";
 
@@ -36,7 +37,12 @@ export function OverviewTabContent({ tab, range }: OverviewTabContentProps) {
   const bookings = useOverviewBookingsTab(range, tab === "bookings");
   const contracts = useOverviewContractsTab(range, tab === "contracts");
   const billing = useOverviewBillingTab(range, tab === "billing");
-  const operations = useOverviewOperationsTab(range, tab === "operations");
+  // Fleet reuses the operations dataset — same query key, so switching between
+  // the two tabs costs one fetch.
+  const operations = useOverviewOperationsTab(
+    range,
+    tab === "operations" || tab === "fleet",
+  );
   const customers = useOverviewCustomersTab(range, tab === "customers");
   const staff = useOverviewStaffTab(range, tab === "staff");
 
@@ -47,7 +53,7 @@ export function OverviewTabContent({ tab, range }: OverviewTabContentProps) {
         ? contracts
         : tab === "billing"
           ? billing
-          : tab === "operations"
+          : tab === "operations" || tab === "fleet"
             ? operations
             : tab === "customers"
               ? customers
@@ -99,6 +105,9 @@ export function OverviewTabContent({ tab, range }: OverviewTabContentProps) {
       {tab === "operations" && operations.data && (
         <OverviewOperationsTabPanel data={operations.data} />
       )}
+      {tab === "fleet" && operations.data && (
+        <OverviewFleetTabPanel data={operations.data} />
+      )}
       {tab === "customers" && customers.data && (
         <OverviewCustomersTabPanel data={customers.data} />
       )}

apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewBookingsTabPanel.tsx

@@ -24,6 +24,13 @@ export function OverviewBookingsTabPanel({ data }: OverviewBookingsTabPanelProps
     <Stack gap="lg">
       <OverviewKpiStrip
         items={[
+          {
+            label: "Total bookings",
+            value: data.kpis.total,
+            icon: FileText,
+            accent: "gold",
+            hint: "All time",
+          },
           {
             label: "Active bookings",
             value: data.kpis.totalActive,

apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewContractsTabPanel.tsx

@@ -41,6 +41,13 @@ export function OverviewContractsTabPanel({
     <Stack gap="lg">
       <OverviewKpiStrip
         items={[
+          {
+            label: "Total contracts",
+            value: data.kpis.total,
+            icon: FileSignature,
+            accent: "gold",
+            hint: "All time",
+          },
           {
             label: "Active contracts",
             value: data.kpis.totalActive,

apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewFleetTabPanel.tsx

@@ -0,0 +1,115 @@
+import { Train, Truck, Wrench } from "lucide-react";
+import { Grid, Stack } from "@mantine/core";
+
+import type { IOverviewOperationsTab, IOverviewStatusCount } from "@/types/overview";
+import { OverviewDonutChart } from "../OverviewDonutChart";
+import { OverviewHorizontalBarChart } from "../OverviewHorizontalBarChart";
+import { OverviewKpiStrip } from "../OverviewKpiStrip";
+
+function formatStatusLabel(status: string) {
+  return status
+    .replace(/_/g, " ")
+    .toLowerCase()
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function sumCounts(items: IOverviewStatusCount[]) {
+  return items.reduce((sum, item) => sum + item.count, 0);
+}
+
+function countByStatus(items: IOverviewStatusCount[], status: string) {
+  return items.find((item) => item.status === status)?.count ?? 0;
+}
+
+function toDonutData(items: IOverviewStatusCount[]) {
+  return items.map((item) => ({
+    name: formatStatusLabel(item.status),
+    value: item.count,
+  }));
+}
+
+interface OverviewFleetTabPanelProps {
+  data: IOverviewOperationsTab;
+}
+
+export function OverviewFleetTabPanel({ data }: OverviewFleetTabPanelProps) {
+  return (
+    <Stack gap="lg">
+      <OverviewKpiStrip
+        items={[
+          {
+            label: "Total trains",
+            value: sumCounts(data.trainStatusBreakdown),
+            icon: Train,
+            accent: "gold",
+            hint: "All time",
+          },
+          {
+            label: "Active trains",
+            value: data.kpis.trainsActive,
+            icon: Train,
+            accent: "emerald",
+          },
+          {
+            label: "Total wagons",
+            value: sumCounts(data.wagonStatusBreakdown),
+            icon: Truck,
+            accent: "gold",
+            hint: "All time",
+          },
+          {
+            label: "Wagons available",
+            value: data.kpis.wagonsAvailable,
+            icon: Truck,
+            accent: "emerald",
+          },
+          {
+            label: "In maintenance",
+            value: countByStatus(data.wagonStatusBreakdown, "MAINTENANCE"),
+            icon: Wrench,
+            accent: "amber",
+          },
+        ]}
+      />
+
+      <Grid gap="md">
+        <Grid.Col span={{ base: 12, md: 6 }}>
+          <OverviewHorizontalBarChart
+            title="Wagon fleet by type"
+            data={data.wagonsByType.map((item) => ({
+              label: item.label,
+              value: item.count,
+            }))}
+            valueLabel="Wagons"
+          />
+        </Grid.Col>
+        <Grid.Col span={{ base: 12, md: 6 }}>
+          <OverviewHorizontalBarChart
+            title="Wagons by yard"
+            data={data.wagonsByYard.map((item) => ({
+              label: item.label,
+              value: item.count,
+            }))}
+            valueLabel="Wagons"
+            emptyMessage="No wagons assigned to yards"
+          />
+        </Grid.Col>
+      </Grid>
+
+      <Grid gap="md">
+        <Grid.Col span={{ base: 12, md: 6 }}>
+          <OverviewDonutChart
+            title="Train status"
+            data={toDonutData(data.trainStatusBreakdown)}
+          />
+        </Grid.Col>
+        <Grid.Col span={{ base: 12, md: 6 }}>
+          <OverviewDonutChart
+            title="Wagon status"
+            data={toDonutData(data.wagonStatusBreakdown)}
+          />
+        </Grid.Col>
+      </Grid>
+    </Stack>
+  );
+}

apps/edr-freight-web/backoffice/src/components/overview/tabs/OverviewOperationsTabPanel.tsx

@@ -105,30 +105,6 @@ export function OverviewOperationsTabPanel({ data }: OverviewOperationsTabPanelP
         </Grid.Col>
       </Grid>
 
-      <Grid gap="md">
-        <Grid.Col span={{ base: 12, md: 6 }}>
-          <OverviewHorizontalBarChart
-            title="Wagon fleet by type"
-            data={data.wagonsByType.map((item) => ({
-              label: item.label,
-              value: item.count,
-            }))}
-            valueLabel="Wagons"
-          />
-        </Grid.Col>
-        <Grid.Col span={{ base: 12, md: 6 }}>
-          <OverviewHorizontalBarChart
-            title="Wagons by yard"
-            data={data.wagonsByYard.map((item) => ({
-              label: item.label,
-              value: item.count,
-            }))}
-            valueLabel="Wagons"
-            emptyMessage="No wagons assigned to yards"
-          />
-        </Grid.Col>
-      </Grid>
-
       <Grid gap="md">
         <Grid.Col span={{ base: 12, md: 6 }}>
           <OverviewHorizontalBarChart
@@ -153,18 +129,6 @@ export function OverviewOperationsTabPanel({ data }: OverviewOperationsTabPanelP
       </Grid>
 
       <Grid gap="md">
-        <Grid.Col span={{ base: 12, md: 6 }}>
-          <OverviewDonutChart
-            title="Train status"
-            data={toDonutData(data.trainStatusBreakdown)}
-          />
-        </Grid.Col>
-        <Grid.Col span={{ base: 12, md: 6 }}>
-          <OverviewDonutChart
-            title="Wagon status"
-            data={toDonutData(data.wagonStatusBreakdown)}
-          />
-        </Grid.Col>
         <Grid.Col span={{ base: 12, md: 6 }}>
           <OverviewDonutChart
             title="Container status"

apps/edr-freight-web/backoffice/src/constants/URLS.ts

@@ -109,6 +109,10 @@ export const URL_CONSTANTS = {
     BY_USER_ID: (id: string) => `/api/customers/user/${id}`,
   },
 
+  REPORTS: {
+    RUN: (key: string) => `/reports/${key}`,
+  },
+
   OVERVIEW: {
     BASE: "/overview",
     BOOKINGS: "/overview/bookings",

apps/edr-freight-web/backoffice/src/pages/dashboard/OverviewPage.tsx

@@ -5,6 +5,7 @@ import {
   FileSignature,
   FileText,
   Train,
+  TrainFront,
   UserCheck,
   Users,
 } from "lucide-react";
@@ -13,7 +14,6 @@ import {
   Badge,
   Button,
   Container,
-  Paper,
   Skeleton,
   Stack,
   Tabs,
@@ -22,7 +22,6 @@ import { useQueryClient } from "@tanstack/react-query";
 
 import { useAuth } from "@/auth/useAuth";
 import { OverviewPageHeader } from "@/components/overview/OverviewPageHeader";
-import { OverviewQuickLinks } from "@/components/overview/OverviewQuickLinks";
 import { OverviewTabContent } from "@/components/overview/OverviewTabContent";
 import "@/components/overview/overview.css";
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
@@ -82,6 +81,18 @@ const TAB_ITEMS: Array<{
       FREIGHT_PERMS.lastMile.view,
     ],
   },
+  {
+    value: "fleet",
+    label: "Fleet",
+    icon: TrainFront,
+    kpiKey: "operations",
+    metricKey: "wagonsAvailable",
+    permission: [
+      FREIGHT_PERMS.fleet.view,
+      FREIGHT_PERMS.wagons.view,
+      FREIGHT_PERMS.trainScheduling.view,
+    ],
+  },
   {
     value: "customers",
     label: "Customers",
@@ -174,6 +185,12 @@ const OverviewPage = () => {
           </Alert>
         )}
 
+        {visibleTabs.length === 0 && !isLoading && !isError && (
+          <Alert color="gray" variant="light" title="No dashboard sections available">
+            Your role has no access to any overview section.
+          </Alert>
+        )}
+
         {visibleTabs.length > 0 && (
           <Tabs
             value={currentTab}
@@ -220,10 +237,6 @@ const OverviewPage = () => {
             ))}
           </Tabs>
         )}
-
-        <Paper p="lg" radius="lg" withBorder>
-          <OverviewQuickLinks />
-        </Paper>
       </Stack>
     </Container>
   );

apps/edr-freight-web/backoffice/src/pages/reports/ReportPage.tsx

@@ -0,0 +1,441 @@
+import {
+  Button,
+  Card,
+  Group,
+  MultiSelect,
+  Select,
+  Text,
+} from "@mantine/core";
+import { DateInput } from "@mantine/dates";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import {
+  DataTable,
+  DataTableFooter,
+  usePagination,
+  type ColumnDef,
+} from "@edr/ui-common";
+import { Download, FileSpreadsheet, Printer, RotateCcw } from "lucide-react";
+import { useMemo } from "react";
+import { useParams, useSearchParams, Link } from "react-router-dom";
+import {
+  Area,
+  AreaChart,
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Legend,
+  Line,
+  LineChart,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from "recharts";
+import * as XLSX from "xlsx";
+
+import { KpiStrip, PageContainer, PageHeader } from "@/components/page";
+import { overviewChartColors } from "@/components/overview/overview.styles";
+import { api } from "@/services/api";
+import type { ReportQueryInput, ReportRow } from "@/types/reports";
+import {
+  REPORT_CONFIG_BY_KEY,
+  type ReportColumn,
+  type ReportConfig,
+} from "./reportConfigs";
+
+const compact = new Intl.NumberFormat("en", { notation: "compact" });
+
+const UNIT_SUFFIX = { ETB: " ETB", t: " t", "%": "%", min: " min" } as const;
+
+function formatCell(value: unknown, col: ReportColumn): string {
+  if (value === null || value === undefined || value === "") return "—";
+  if (col.unit || col.numeric) {
+    const n = Number(value);
+    if (!Number.isNaN(n)) {
+      return `${n.toLocaleString()}${col.unit ? UNIT_SUFFIX[col.unit] : ""}`;
+    }
+  }
+  return String(value);
+}
+
+const toDate = (s: string | null): Date | null => (s ? new Date(s) : null);
+// Mantine DateInput onChange emits a date string (or null).
+const toParam = (d: Date | string | null): string | null => {
+  if (!d) return null;
+  return typeof d === "string" ? d.slice(0, 10) : d.toISOString().slice(0, 10);
+};
+
+function downloadBlob(content: BlobPart, type: string, filename: string) {
+  const url = URL.createObjectURL(new Blob([content], { type }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+function exportCsv(config: ReportConfig, rows: ReportRow[]) {
+  const esc = (v: unknown) => `"${String(v ?? "").replace(/"/g, '""')}"`;
+  const lines = [
+    config.columns.map((c) => esc(c.label)).join(","),
+    ...rows.map((r) => config.columns.map((c) => esc(r[c.key])).join(",")),
+  ];
+  downloadBlob(lines.join("\n"), "text/csv;charset=utf-8", `${config.key}.csv`);
+}
+
+function exportXlsx(config: ReportConfig, rows: ReportRow[]) {
+  const sheetRows = rows.map((r) =>
+    Object.fromEntries(config.columns.map((c) => [c.label, r[c.key] ?? ""])),
+  );
+  const wb = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(
+    wb,
+    XLSX.utils.json_to_sheet(sheetRows),
+    config.title.slice(0, 31),
+  );
+  XLSX.writeFile(wb, `${config.key}.xlsx`);
+}
+
+function ReportChartView({
+  config,
+  rows,
+}: {
+  config: ReportConfig;
+  rows: ReportRow[];
+}) {
+  const chart = config.chart;
+  const data = useMemo(() => {
+    if (!chart) return [];
+    const sliced = chart.topN ? rows.slice(0, chart.topN) : rows;
+    // xKey "a+b" concatenates columns (e.g. origin+destination → "A → B").
+    const keys = chart.xKey.split("+");
+    return sliced.map((r) => ({
+      ...r,
+      __x:
+        keys.length > 1
+          ? keys.map((k) => String(r[k] ?? "")).join(" → ")
+          : String(r[chart.xKey] ?? ""),
+    }));
+  }, [chart, rows]);
+
+  if (!chart) return null;
+  if (data.length === 0) {
+    return (
+      <Card withBorder shadow="sm">
+        <Text c="dimmed" ta="center" py="xl">
+          No data for the selected filters
+        </Text>
+      </Card>
+    );
+  }
+
+  const ChartComponent =
+    chart.type === "bar" ? BarChart : chart.type === "line" ? LineChart : AreaChart;
+
+  return (
+    <Card withBorder shadow="sm">
+      <ResponsiveContainer width="100%" height={280}>
+        <ChartComponent data={data} margin={{ top: 8, right: 8, left: 8, bottom: 0 }}>
+          <CartesianGrid strokeDasharray="3 3" stroke="#e5e7eb" />
+          <XAxis dataKey="__x" tick={{ fontSize: 12 }} interval="preserveStartEnd" />
+          <YAxis
+            tick={{ fontSize: 12 }}
+            tickFormatter={(v: number) => compact.format(v)}
+            width={56}
+          />
+          <Tooltip formatter={(value) => Number(value ?? 0).toLocaleString()} />
+          {chart.series.length > 1 ? <Legend /> : null}
+          {chart.series.map((s, i) => {
+            const color =
+              overviewChartColors.pipeline[i % overviewChartColors.pipeline.length];
+            if (chart.type === "bar") {
+              return (
+                <Bar key={s.key} dataKey={s.key} name={s.label} fill={color} radius={[4, 4, 0, 0]} />
+              );
+            }
+            if (chart.type === "line") {
+              return (
+                <Line
+                  key={s.key}
+                  type="monotone"
+                  dataKey={s.key}
+                  name={s.label}
+                  stroke={color}
+                  strokeWidth={2}
+                  dot={false}
+                />
+              );
+            }
+            return (
+              <Area
+                key={s.key}
+                type="monotone"
+                dataKey={s.key}
+                name={s.label}
+                stroke={color}
+                fill={color}
+                fillOpacity={0.15}
+                strokeWidth={2}
+              />
+            );
+          })}
+        </ChartComponent>
+      </ResponsiveContainer>
+    </Card>
+  );
+}
+
+export default function ReportPage() {
+  const { reportKey = "" } = useParams<{ reportKey: string }>();
+  const config = REPORT_CONFIG_BY_KEY.get(reportKey);
+  const [params, setParams] = useSearchParams();
+  const { pagination, setPagination } = usePagination({ pageSize: 20 });
+
+  const setParam = (name: string, value: string | null) => {
+    setParams(
+      (prev) => {
+        if (value) prev.set(name, value);
+        else prev.delete(name);
+        return prev;
+      },
+      { replace: true },
+    );
+    setPagination((p) => ({ ...p, pageIndex: 0 }));
+  };
+
+  const input: ReportQueryInput = {
+    key: reportKey,
+    dateFrom: params.get("dateFrom") ?? undefined,
+    dateTo: params.get("dateTo") ?? undefined,
+    granularity:
+      (params.get("granularity") as ReportQueryInput["granularity"]) ?? undefined,
+    yardIds: params.get("yardIds") ?? undefined,
+    statuses: params.get("statuses") ?? undefined,
+    direction: params.get("direction") ?? undefined,
+    freightType: params.get("freightType") ?? undefined,
+  };
+
+  const reportQuery = useQuery(
+    api.reports.run.queryOptions({
+      input,
+      placeholderData: keepPreviousData,
+      staleTime: 30_000,
+      enabled: Boolean(config),
+    }),
+  );
+
+  const yardsQuery = useQuery(
+    api.routes.yards.queryOptions({
+      staleTime: 5 * 60_000,
+      enabled: Boolean(config?.filters.includes("yards")),
+    }),
+  );
+
+  if (!config) {
+    return (
+      <PageContainer>
+        <PageHeader title="Unknown report" backTo="/dashboard/reports" />
+        <Text>
+          This report does not exist. <Link to="/dashboard/reports">Back to reports</Link>
+        </Text>
+      </PageContainer>
+    );
+  }
+
+  const rows = reportQuery.data?.rows ?? [];
+  const kpis = reportQuery.data?.kpis ?? [];
+  const pageCount = Math.max(1, Math.ceil(rows.length / pagination.pageSize));
+
+  const columns: ColumnDef<ReportRow, unknown>[] = config.columns.map((col) => ({
+    accessorKey: col.key,
+    header: col.label,
+    cell: (info) => formatCell(info.getValue(), col),
+  }));
+
+  const tableStatus = reportQuery.isLoading
+    ? "loading"
+    : reportQuery.isError
+      ? "error"
+      : "success";
+
+  return (
+    <PageContainer>
+      <PageHeader
+        title={config.title}
+        subtitle={config.description}
+        backTo="/dashboard/reports"
+        action={
+          <Group gap="xs">
+            <Button
+              variant="default"
+              size="xs"
+              leftSection={<Download size={14} />}
+              onClick={() => exportCsv(config, rows)}
+              disabled={rows.length === 0}
+            >
+              CSV
+            </Button>
+            <Button
+              variant="default"
+              size="xs"
+              leftSection={<FileSpreadsheet size={14} />}
+              onClick={() => exportXlsx(config, rows)}
+              disabled={rows.length === 0}
+            >
+              Excel
+            </Button>
+            <Button
+              variant="default"
+              size="xs"
+              leftSection={<Printer size={14} />}
+              onClick={() => window.print()}
+            >
+              Print
+            </Button>
+          </Group>
+        }
+      />
+
+      <Card withBorder shadow="sm">
+        <Group gap="sm" align="flex-end" wrap="wrap">
+          <DateInput
+            label="From"
+            size="xs"
+            clearable
+            value={toDate(params.get("dateFrom"))}
+            maxDate={toDate(params.get("dateTo")) ?? undefined}
+            onChange={(d) => setParam("dateFrom", toParam(d))}
+            placeholder="30 days ago"
+          />
+          <DateInput
+            label="To"
+            size="xs"
+            clearable
+            value={toDate(params.get("dateTo"))}
+            minDate={toDate(params.get("dateFrom")) ?? undefined}
+            onChange={(d) => setParam("dateTo", toParam(d))}
+            placeholder="Today"
+          />
+          {config.filters.includes("granularity") ? (
+            <Select
+              label="Group by"
+              size="xs"
+              data={[
+                { value: "day", label: "Day" },
+                { value: "week", label: "Week" },
+                { value: "month", label: "Month" },
+              ]}
+              value={params.get("granularity") ?? "day"}
+              onChange={(v) => setParam("granularity", v)}
+              allowDeselect={false}
+            />
+          ) : null}
+          {config.filters.includes("yards") ? (
+            <MultiSelect
+              label="Yards"
+              size="xs"
+              searchable
+              clearable
+              w={220}
+              data={(yardsQuery.data ?? []).map((y) => ({
+                value: y.id,
+                label: y.label,
+              }))}
+              value={params.get("yardIds")?.split(",").filter(Boolean) ?? []}
+              onChange={(v) => setParam("yardIds", v.length ? v.join(",") : null)}
+              placeholder="All yards"
+            />
+          ) : null}
+          {config.filters.includes("direction") ? (
+            <Select
+              label="Direction"
+              size="xs"
+              clearable
+              data={["IMPORT", "EXPORT"]}
+              value={params.get("direction")}
+              onChange={(v) => setParam("direction", v)}
+              placeholder="All"
+            />
+          ) : null}
+          {config.filters.includes("freightType") ? (
+            <Select
+              label="Freight type"
+              size="xs"
+              clearable
+              data={["CONTAINER", "BULK"]}
+              value={params.get("freightType")}
+              onChange={(v) => setParam("freightType", v)}
+              placeholder="All"
+            />
+          ) : null}
+          {config.filters.includes("statuses") && config.statusOptions ? (
+            <MultiSelect
+              label="Status"
+              size="xs"
+              searchable
+              clearable
+              w={220}
+              data={config.statusOptions}
+              value={params.get("statuses")?.split(",").filter(Boolean) ?? []}
+              onChange={(v) => setParam("statuses", v.length ? v.join(",") : null)}
+              placeholder="Default (active)"
+            />
+          ) : null}
+          <Button
+            variant="subtle"
+            size="xs"
+            leftSection={<RotateCcw size={14} />}
+            onClick={() => setParams({}, { replace: true })}
+          >
+            Reset
+          </Button>
+        </Group>
+      </Card>
+
+      <KpiStrip
+        loading={reportQuery.isLoading}
+        items={kpis.map((k) => ({
+          label: k.label,
+          value: k.value.toLocaleString(),
+          hint: k.unit,
+        }))}
+      />
+
+      <ReportChartView config={config} rows={rows} />
+
+      <DataTable
+        columns={columns}
+        data={rows}
+        status={tableStatus}
+        emptyMessage="No data for the selected filters"
+        error={
+          reportQuery.isError
+            ? {
+                message: "Failed to load report",
+                onRetry: () => void reportQuery.refetch(),
+              }
+            : undefined
+        }
+        pagination={{
+          pageIndex: pagination.pageIndex,
+          pageSize: pagination.pageSize,
+          pageCount,
+          totalCount: rows.length,
+        }}
+        tableOptions={{
+          manualPagination: false,
+          state: { pagination },
+          onPaginationChange: setPagination,
+          autoResetPageIndex: false,
+        }}
+        footer={({ table, pagination: p }) => (
+          <DataTableFooter
+            table={table}
+            pagination={p}
+            options={{ labels: { items: "rows" } }}
+          />
+        )}
+      />
+    </PageContainer>
+  );
+}

apps/edr-freight-web/backoffice/src/pages/reports/ReportsHubPage.tsx

@@ -0,0 +1,159 @@
+import {
+  ActionIcon,
+  Badge,
+  Card,
+  Group,
+  SimpleGrid,
+  Stack,
+  Text,
+  TextInput,
+  Title,
+} from "@mantine/core";
+import { Search, Star } from "lucide-react";
+import { useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { PageContainer, PageHeader } from "@/components/page";
+import {
+  REPORT_CONFIGS,
+  REPORT_DOMAINS,
+  type ReportConfig,
+} from "./reportConfigs";
+
+const FAVORITES_KEY = "reports.favorites";
+
+const loadFavorites = (): string[] => {
+  try {
+    return JSON.parse(localStorage.getItem(FAVORITES_KEY) ?? "[]");
+  } catch {
+    return [];
+  }
+};
+
+function ReportCard({
+  config,
+  favorite,
+  onToggleFavorite,
+}: {
+  config: ReportConfig;
+  favorite: boolean;
+  onToggleFavorite: () => void;
+}) {
+  const navigate = useNavigate();
+  return (
+    <Card
+      withBorder
+      shadow="sm"
+      className="cursor-pointer transition-colors hover:bg-gray-50"
+      onClick={() => navigate(`/dashboard/reports/${config.key}`)}
+    >
+      <Group justify="space-between" align="flex-start" wrap="nowrap">
+        <div style={{ minWidth: 0 }}>
+          <Text fw={600} truncate>
+            {config.title}
+          </Text>
+          <Text size="sm" c="dimmed" lineClamp={2}>
+            {config.description}
+          </Text>
+        </div>
+        <ActionIcon
+          variant="subtle"
+          color={favorite ? "yellow" : "gray"}
+          aria-label={favorite ? "Remove from favorites" : "Add to favorites"}
+          onClick={(e) => {
+            e.stopPropagation();
+            onToggleFavorite();
+          }}
+        >
+          <Star size={16} fill={favorite ? "currentColor" : "none"} />
+        </ActionIcon>
+      </Group>
+      <Badge mt="sm" size="sm" variant="light">
+        {config.domain}
+      </Badge>
+    </Card>
+  );
+}
+
+export default function ReportsHubPage() {
+  const [search, setSearch] = useState("");
+  const [favorites, setFavorites] = useState<string[]>(loadFavorites);
+
+  const toggleFavorite = (key: string) => {
+    setFavorites((prev) => {
+      const next = prev.includes(key)
+        ? prev.filter((k) => k !== key)
+        : [...prev, key];
+      localStorage.setItem(FAVORITES_KEY, JSON.stringify(next));
+      return next;
+    });
+  };
+
+  const visible = useMemo(() => {
+    const q = search.trim().toLowerCase();
+    if (!q) return REPORT_CONFIGS;
+    return REPORT_CONFIGS.filter(
+      (c) =>
+        c.title.toLowerCase().includes(q) ||
+        c.description.toLowerCase().includes(q),
+    );
+  }, [search]);
+
+  const pinned = visible.filter((c) => favorites.includes(c.key));
+
+  const renderGrid = (configs: ReportConfig[]) => (
+    <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="md">
+      {configs.map((c) => (
+        <ReportCard
+          key={c.key}
+          config={c}
+          favorite={favorites.includes(c.key)}
+          onToggleFavorite={() => toggleFavorite(c.key)}
+        />
+      ))}
+    </SimpleGrid>
+  );
+
+  return (
+    <PageContainer>
+      <PageHeader
+        title="Reports"
+        subtitle="Operational, commercial and financial reporting"
+        action={
+          <TextInput
+            size="xs"
+            w={240}
+            leftSection={<Search size={14} />}
+            placeholder="Search reports…"
+            value={search}
+            onChange={(e) => setSearch(e.currentTarget.value)}
+          />
+        }
+      />
+
+      {pinned.length ? (
+        <Stack gap="sm">
+          <Title order={4}>Favorites</Title>
+          {renderGrid(pinned)}
+        </Stack>
+      ) : null}
+
+      {REPORT_DOMAINS.map((domain) => {
+        const configs = visible.filter((c) => c.domain === domain);
+        if (!configs.length) return null;
+        return (
+          <Stack key={domain} gap="sm">
+            <Title order={4}>{domain}</Title>
+            {renderGrid(configs)}
+          </Stack>
+        );
+      })}
+
+      {visible.length === 0 ? (
+        <Text c="dimmed" ta="center" py="xl">
+          No reports match “{search}”
+        </Text>
+      ) : null}
+    </PageContainer>
+  );
+}

apps/edr-freight-web/backoffice/src/pages/reports/reportConfigs.ts

@@ -0,0 +1,295 @@
+export type ReportDomain = "Commercial" | "Operations" | "Finance";
+
+export type ReportColumnUnit = "ETB" | "t" | "%" | "min";
+
+export interface ReportColumn {
+  key: string;
+  label: string;
+  /** Numeric unit — formats the cell (thousands separators, suffix). */
+  unit?: ReportColumnUnit;
+  numeric?: boolean;
+}
+
+export interface ReportChart {
+  type: "area" | "line" | "bar";
+  xKey: string;
+  series: { key: string; label: string }[];
+  /** Chart only the first N rows (rows arrive sorted by the backend). */
+  topN?: number;
+}
+
+export type ReportFilterKey =
+  | "granularity"
+  | "yards"
+  | "direction"
+  | "freightType"
+  | "statuses";
+
+export interface ReportConfig {
+  key: string;
+  title: string;
+  description: string;
+  domain: ReportDomain;
+  filters: ReportFilterKey[];
+  /** Options for the `statuses` filter, when enabled. */
+  statusOptions?: string[];
+  chart?: ReportChart;
+  columns: ReportColumn[];
+}
+
+const BOOKING_STATUSES = [
+  "SUBMITTED",
+  "PENDING_APPROVAL",
+  "APPROVED",
+  "INVOICED",
+  "PAID",
+  "IN_TRANSIT",
+  "ARRIVED",
+  "COMPLETED",
+  "CANCELLED",
+  "REJECTED",
+];
+
+const CONTRACT_STATUSES = [
+  "SUBMITTED",
+  "PENDING_APPROVAL",
+  "APPROVED",
+  "CONTRACT_ACTIVE",
+  "ACTIVE_SHIPMENT_IN_PROGRESS",
+  "SUSPENDED",
+  "CONTRACT_CLOSED",
+  "EXPIRED",
+  "CANCELLED",
+];
+
+const INVOICE_STATUSES = [
+  "ISSUED",
+  "PENDING",
+  "PARTIALLY_PAID",
+  "PAID",
+  "OVERDUE",
+  "REFUNDED",
+];
+
+export const REPORT_CONFIGS: ReportConfig[] = [
+  {
+    key: "bookings-trend",
+    title: "Bookings Trend",
+    description: "Booking volume, tonnage and revenue over time",
+    domain: "Commercial",
+    filters: ["granularity", "yards", "direction", "freightType", "statuses"],
+    statusOptions: BOOKING_STATUSES,
+    chart: {
+      type: "area",
+      xKey: "period",
+      series: [{ key: "revenue", label: "Revenue (ETB)" }],
+    },
+    columns: [
+      { key: "period", label: "Period" },
+      { key: "bookings", label: "Bookings", numeric: true },
+      { key: "tons", label: "Tonnage", unit: "t" },
+      { key: "revenue", label: "Revenue", unit: "ETB" },
+    ],
+  },
+  {
+    key: "revenue-by-customer",
+    title: "Revenue by Customer",
+    description: "Ranked customers by booking revenue",
+    domain: "Commercial",
+    filters: ["yards", "direction", "freightType", "statuses"],
+    statusOptions: BOOKING_STATUSES,
+    chart: {
+      type: "bar",
+      xKey: "customer",
+      series: [{ key: "revenue", label: "Revenue (ETB)" }],
+      topN: 10,
+    },
+    columns: [
+      { key: "customer", label: "Customer" },
+      { key: "bookings", label: "Bookings", numeric: true },
+      { key: "tons", label: "Tonnage", unit: "t" },
+      { key: "revenue", label: "Revenue", unit: "ETB" },
+    ],
+  },
+  {
+    key: "revenue-by-lane",
+    title: "Revenue by Lane",
+    description: "Origin → destination lanes by tonnage and revenue",
+    domain: "Commercial",
+    filters: ["direction", "freightType", "statuses"],
+    statusOptions: BOOKING_STATUSES,
+    chart: {
+      type: "bar",
+      xKey: "origin+destination",
+      series: [{ key: "revenue", label: "Revenue (ETB)" }],
+      topN: 10,
+    },
+    columns: [
+      { key: "origin", label: "Origin" },
+      { key: "destination", label: "Destination" },
+      { key: "bookings", label: "Bookings", numeric: true },
+      { key: "tons", label: "Tonnage", unit: "t" },
+      { key: "revenue", label: "Revenue", unit: "ETB" },
+    ],
+  },
+  {
+    key: "contract-utilization",
+    title: "Contract Utilization",
+    description: "Committed scope caps vs booked tonnage per contract",
+    domain: "Commercial",
+    filters: ["direction", "statuses"],
+    statusOptions: CONTRACT_STATUSES,
+    columns: [
+      { key: "reference", label: "Contract" },
+      { key: "customer", label: "Customer" },
+      { key: "status", label: "Status" },
+      { key: "kind", label: "Kind" },
+      { key: "valid_from", label: "Valid from" },
+      { key: "valid_until", label: "Valid until" },
+      { key: "committed", label: "Committed", unit: "t" },
+      { key: "booked_tons", label: "Booked", unit: "t" },
+      { key: "bookings", label: "Bookings", numeric: true },
+      { key: "utilization_pct", label: "Utilization", unit: "%" },
+    ],
+  },
+  {
+    key: "train-on-time",
+    title: "Train On-Time Performance",
+    description: "Departure punctuality and delays by lane (60-min grace)",
+    domain: "Operations",
+    filters: ["yards", "direction"],
+    chart: {
+      type: "bar",
+      xKey: "origin+destination",
+      series: [{ key: "on_time_pct", label: "On-time %" }],
+      topN: 15,
+    },
+    columns: [
+      { key: "origin", label: "Origin" },
+      { key: "destination", label: "Destination" },
+      { key: "trips", label: "Trips", numeric: true },
+      { key: "departed", label: "Departed", numeric: true },
+      { key: "avg_dep_delay_min", label: "Avg dep. delay", unit: "min" },
+      { key: "avg_arr_delay_min", label: "Avg arr. delay", unit: "min" },
+      { key: "on_time_pct", label: "On-time", unit: "%" },
+    ],
+  },
+  {
+    key: "schedule-fill-rate",
+    title: "Schedule Fill Rate",
+    description: "Booked tonnage vs wagon capacity per train schedule",
+    domain: "Operations",
+    filters: ["yards", "direction"],
+    chart: {
+      type: "line",
+      xKey: "departure",
+      series: [{ key: "fill_pct", label: "Fill %" }],
+    },
+    columns: [
+      { key: "train_number", label: "Train" },
+      { key: "departure", label: "Departure" },
+      { key: "origin", label: "Origin" },
+      { key: "destination", label: "Destination" },
+      { key: "direction", label: "Direction" },
+      { key: "status", label: "Status" },
+      { key: "wagon_count", label: "Wagons", numeric: true },
+      { key: "capacity_tons", label: "Capacity", unit: "t" },
+      { key: "booked_tons", label: "Booked", unit: "t" },
+      { key: "fill_pct", label: "Fill", unit: "%" },
+    ],
+  },
+  {
+    key: "trips-per-route",
+    title: "Trips per Route",
+    description: "Completed trips and tonnage hauled per lane",
+    domain: "Operations",
+    filters: ["yards", "direction"],
+    chart: {
+      type: "bar",
+      xKey: "origin+destination",
+      series: [{ key: "trips", label: "Trips" }],
+      topN: 15,
+    },
+    columns: [
+      { key: "origin", label: "Origin" },
+      { key: "destination", label: "Destination" },
+      { key: "direction", label: "Direction" },
+      { key: "trips", label: "Trips", numeric: true },
+      { key: "tons_hauled", label: "Tonnage hauled", unit: "t" },
+      { key: "avg_tons_per_trip", label: "Avg per trip", unit: "t" },
+    ],
+  },
+  {
+    key: "invoiced-vs-collected",
+    title: "Invoiced vs Collected",
+    description: "Billing issued vs payments received over time",
+    domain: "Finance",
+    filters: ["granularity", "direction"],
+    chart: {
+      type: "line",
+      xKey: "period",
+      series: [
+        { key: "invoiced", label: "Invoiced (ETB)" },
+        { key: "collected", label: "Collected (ETB)" },
+      ],
+    },
+    columns: [
+      { key: "period", label: "Period" },
+      { key: "invoices", label: "Invoices", numeric: true },
+      { key: "invoiced", label: "Invoiced", unit: "ETB" },
+      { key: "collected", label: "Collected", unit: "ETB" },
+      { key: "outstanding", label: "Outstanding", unit: "ETB" },
+    ],
+  },
+  {
+    key: "aging-receivables",
+    title: "Aging Receivables",
+    description: "Outstanding invoice balances by age bucket per customer",
+    domain: "Finance",
+    filters: ["direction", "statuses"],
+    statusOptions: INVOICE_STATUSES,
+    chart: {
+      type: "bar",
+      xKey: "customer",
+      series: [{ key: "outstanding", label: "Outstanding (ETB)" }],
+      topN: 10,
+    },
+    columns: [
+      { key: "customer", label: "Customer" },
+      { key: "invoices", label: "Invoices", numeric: true },
+      { key: "outstanding", label: "Outstanding", unit: "ETB" },
+      { key: "current", label: "Current", unit: "ETB" },
+      { key: "overdue_0_30", label: "0–30d", unit: "ETB" },
+      { key: "overdue_31_60", label: "31–60d", unit: "ETB" },
+      { key: "overdue_61_90", label: "61–90d", unit: "ETB" },
+      { key: "overdue_90_plus", label: "90d+", unit: "ETB" },
+    ],
+  },
+  {
+    key: "revenue-by-payment-method",
+    title: "Revenue by Payment Method",
+    description: "Successful payments broken down by method",
+    domain: "Finance",
+    filters: ["direction"],
+    chart: {
+      type: "bar",
+      xKey: "method",
+      series: [{ key: "amount", label: "Amount (ETB)" }],
+    },
+    columns: [
+      { key: "method", label: "Method" },
+      { key: "payments", label: "Payments", numeric: true },
+      { key: "amount", label: "Amount", unit: "ETB" },
+    ],
+  },
+];
+
+export const REPORT_CONFIG_BY_KEY = new Map(
+  REPORT_CONFIGS.map((c) => [c.key, c]),
+);
+
+export const REPORT_DOMAINS: ReportDomain[] = [
+  "Commercial",
+  "Operations",
+  "Finance",
+];

apps/edr-freight-web/backoffice/src/services/api.ts

@@ -163,6 +163,8 @@ import {
   type SaveLocomotivePayload,
 } from "./locomotives.service";
 import { overviewService } from "./overview.service";
+import { reportsService } from "./reports.service";
+import type { ReportQueryInput, ReportResult } from "@/types/reports";
 import {
   paymentsService,
   type PaginatedPayments,
@@ -2880,4 +2882,13 @@ export const api = {
       ({ range }) => overviewService.getDashboard(range),
     ),
   },
+
+  reports: {
+    run: endpoint<ReportQueryInput, ReportResult>(
+      "reports",
+      "run",
+      (input) => reportsService.run(input),
+      (input) => ["reports", input.key, input],
+    ),
+  },
 };

apps/edr-freight-web/backoffice/src/services/reports.service.ts

@@ -0,0 +1,14 @@
+import { api as client } from "../auth/http";
+import { unwrap } from "@/utils/endpoint";
+import { URL_CONSTANTS } from "@/constants/URLS";
+import type { ReportQueryInput, ReportResult } from "@/types/reports";
+
+export const reportsService = {
+  run: async ({ key, ...params }: ReportQueryInput): Promise<ReportResult> => {
+    const response = await client.get<ReportResult>(
+      URL_CONSTANTS.REPORTS.RUN(key),
+      { params },
+    );
+    return unwrap(response.data);
+  },
+};

apps/edr-freight-web/backoffice/src/types/reports.ts

@@ -0,0 +1,27 @@
+export interface ReportKpi {
+  label: string;
+  value: number;
+  unit?: string;
+}
+
+export type ReportRow = Record<string, unknown>;
+
+export interface ReportResult {
+  kpis: ReportKpi[];
+  rows: ReportRow[];
+}
+
+/** Query params for GET /reports/:key. List filters are comma-separated. */
+export interface ReportQueryInput {
+  key: string;
+  dateFrom?: string;
+  dateTo?: string;
+  granularity?: "day" | "week" | "month";
+  companyIds?: string;
+  routeIds?: string;
+  yardIds?: string;
+  cargoTypeIds?: string;
+  statuses?: string;
+  direction?: string;
+  freightType?: string;
+}

packages/types/src/freight/overview.ts

@@ -1,6 +1,8 @@
 export type OverviewRange = '7d' | '30d' | '90d';
 
 export interface IOverviewBookingKpis {
+  /** All bookings ever recorded (excluding deleted / GENERAL umbrella rows). */
+  total: number;
   totalActive: number;
   needsAction: number;
   urgent: number;
@@ -35,6 +37,8 @@ export interface IOverviewStaffKpis {
 }
 
 export interface IOverviewContractKpis {
+  /** All contracts ever recorded (excluding deleted). */
+  total: number;
   totalActive: number;
   needsAction: number;
   inApproval: number;
@@ -202,5 +206,6 @@ export type OverviewTabKey =
   | 'contracts'
   | 'billing'
   | 'operations'
+  | 'fleet'
   | 'customers'
   | 'staff';