🧾 Audit Reports Dashboard – Specification Document

🔹 Objective

Design and implement a centralized Audit Reports Dashboard that enables users to:
• Generate, preview, and export reports (CSV/Excel) across various categories.
• Apply dynamic filters based on report type.
• Maintain a complete audit trail of who generated which report, when, and with what filters.
• Provide downloadable links for previously generated reports.

The dashboard must be modern, responsive, and accessible, using Shadcn UI and TailwindCSS, and built with TypeScript and React.

⸻

🗂️ 1. Page Structure & Navigation

Component: AuditReportsPage

Layout Overview:
• Two-Level Tab System:
• Top-Level Tabs: Report Categories (e.g., Accounts, Clients, Taxes, Users)
• Second-Level Tabs: Individual Reports within each category
• Responsive Grid Layout: Works seamlessly across desktop and mobile devices.
• Breadcrumb Navigation: Shows current location in the report hierarchy.

⸻

🧱 2. UI Components (Shadcn UI)
• AppDetailPageHeader: Title and description of the page
• Tabs: Used for both category and sub-report navigation
• AppCard: Display report details with icons and summaries
• Collapsible: Show/hide detailed views and column previews
• Floating Action Panel: Export/report action controls (fixed on desktop, bottom-sheet on mobile)
• Tooltip, Badge, Sheet, Dialog, etc., for enhanced interactions

⸻

📋 3. Report UX Features

Export & Filters:
• Export Formats: CSV (default), Excel
• Provider Filter: Visible based on user role (e.g., Admins only)
• Date Range Picker: Includes presets (Today, Last 7 Days, Last Month, Custom)
• Summary Card: Display selected options for review
• Tooltips: Describe fields, filters, and export options

Report Preview:
• Collapsible Table: Displays column names and descriptions
• Virtual Scrolling: For efficient rendering of large datasets
• Sorting & Filtering: Column-wise filtering and sorting
• Quick Search: Instantly filter report list by name or keyword

⸻

🧾 4. Audit Trail Requirements

Track every report generation and display a history of exports.

Audit Log Features:
• Track:
• Report name
• Filters applied
• Export format
• Timestamp
• User info
• Download URL
• Display in “Export History” or “Recently Generated” section
• Include:
• Pagination
• Search by user/date/report
• Filtering by report category or export status
• Access Control:
• Admins see full history
• Users see only their own history
• Download Link Retention: Link should remain valid for a configurable time (e.g., 7 days)

⸻

🧑‍💻 5. Developer Features

TypeScript Interfaces:
• ReportCategory: { id, label, icon, description }
• Report: { id, heading, subheading, description, columns, useReport hook }
• ReportColumn: { name, description }

Notes:
• Use const assertions for type safety
• Type guards and discriminated unions for dynamic report structures

State Management:
• React Query: For data fetching, caching, and invalidation
• Form Validation: Use zod or similar schema validators
• Error Handling: Use ErrorBoundary and display fallback UI
• Optimistic Updates: For filters and report previews

⸻

🌐 6. Backend Integration Expectations
• Endpoints Required:
• GET /report-categories
• GET /reports/:category
• POST /generate-report – accepts filters, returns file URL
• GET /audit-logs – for export history
• Async Processing:
• Support async job queue for large report generation
• Display loading/progress indicators
• File Storage:
• Reports stored in S3 or similar
• Download URLs returned with expiration

⸻

🎨 7. Styling (TailwindCSS)
• Mobile-first layout
• Consistent spacing, color, and typography scale
• Dark mode support
• Animations for interactions (e.g., expand/collapse, tab change)
• Skeletons for loading states
• Proper hover, focus, and active states

⸻

⚙️ 8. Accessibility
• Use ARIA roles and labels for interactive elements
• Full keyboard navigation support
• Ensure sufficient color contrast (WCAG AA/AAA)
• Manage focus within modals/sheets
• Screen-reader friendly labeling on forms and actions

⸻

🚀 9. Performance Optimization
• Code Splitting: Dynamically import tab panels and previews
• Virtualization: For table previews using react-virtual
• Lazy Loading: Load column data and previews on demand
• Bundle Optimization: Remove unused dependencies, optimize Shadcn tree-shaking
• Cache: Reports and audit history caching using React Query

⸻

🔐 10. Security & Access Control
• Role-Based Access Control (RBAC):
• Admin: Full access to all reports and audit logs
• Manager/User: Access limited by provider or team
• Validate report generation permissions on the server
• Protect download links with tokens or short-lived URLs

⸻

📈 11. Scalability & Extensibility
• Report definitions should be config-driven
• New categories/reports should require minimal UI changes
• Column definitions and filters fetched from server schema
• Modularize components (e.g., ReportConfigurator, ReportPreview, ExportPanel)

⸻

🧠 12. UX Enhancements (Optional Features)
• Save and load Report Templates/Presets
• Allow “Compare Reports” (side-by-side preview)
• Add Data Visualization Previews (charts, graphs)
• Batch export multiple reports with shared filters
• Keyboard shortcuts for power users (e.g. “Ctrl + E” to export)