Import documentation: docs/superpowers/specs/2026-05-30-dashboard-polish-design.md
Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
This commit is contained in:
arsam
@@ -0,0 +1,167 @@
|
|||||||
|
# CShare Dashboard Enhancement & App Polish
|
||||||
|
|
||||||
|
**Date:** 2026-05-30
|
||||||
|
**Status:** Approved
|
||||||
|
**Approach:** Parallel — backend analytics API built simultaneously with frontend enhancements
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
CShare has a working frontend (12+ pages, React Router v7, dark theme design system) and a live backend (Express 5 + TypeScript, local JSON storage). The biggest gaps are in the dashboard experience and overall app polish. This spec covers both tracks.
|
||||||
|
|
||||||
|
**Strategy:** Start simple, grow. Focus on the dashboard (where returning users live) and app-wide polish (makes everything feel trustworthy). The backend analytics API is built in parallel, and the frontend starts with mock data then wires to real endpoints.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Track 1: Backend — Analytics & Dashboard API
|
||||||
|
|
||||||
|
### New/Expanded Endpoints
|
||||||
|
|
||||||
|
| Method | Endpoint | Purpose |
|
||||||
|
|--------|----------|---------|
|
||||||
|
| GET | `/api/v1/dashboard/stats` | Aggregate: total files, storage used, total views, total downloads, active links, expiring soon count |
|
||||||
|
| GET | `/api/v1/dashboard/activity` | Recent activity feed: last 20 events (views, downloads, uploads) with timestamps |
|
||||||
|
| GET | `/api/v1/files/:id/analytics` | Per-file: view count, download count, daily breakdown (last 30 days), top referrers |
|
||||||
|
| POST | `/api/v1/events` | Record a view/download event (called when links are resolved) |
|
||||||
|
| GET | `/api/v1/dashboard/storage` | Storage breakdown by file type, monthly upload volume |
|
||||||
|
|
||||||
|
### Event Recording
|
||||||
|
|
||||||
|
- `GET /api/v1/links/:linkId` automatically records a `view` event
|
||||||
|
- `GET /api/v1/links/:linkId/download` records a `download` event
|
||||||
|
- Events include: timestamp, hashed IP, user agent
|
||||||
|
- Stored in the existing events table
|
||||||
|
|
||||||
|
### Stats Computation
|
||||||
|
|
||||||
|
- Dashboard stats computed on-the-fly from DB (no caching initially)
|
||||||
|
- If performance becomes an issue, add Redis caching with 5-minute TTL
|
||||||
|
- Per-file analytics queries use a 30-day window by default
|
||||||
|
|
||||||
|
### Files to Create/Modify
|
||||||
|
|
||||||
|
- `backend/src/routes/analytics.ts` — new file for analytics endpoints
|
||||||
|
- `backend/src/routes/dashboard.ts` — expand existing file
|
||||||
|
- `backend/src/services/analytics.ts` — new service for event recording and aggregation
|
||||||
|
- `backend/src/routes/links.ts` — modify to record events on link resolution
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Track 2: Frontend — Dashboard Enhancement
|
||||||
|
|
||||||
|
**Principle:** Enhance the existing `DashboardPage.jsx`, do not rewrite.
|
||||||
|
|
||||||
|
### Stat Cards Enhancement
|
||||||
|
|
||||||
|
- Animated count-up on first render (number rolls from 0 to actual value)
|
||||||
|
- Subtle gradient backgrounds per metric theme
|
||||||
|
- Trend indicators comparing to previous period (up/down arrow + percentage)
|
||||||
|
|
||||||
|
### File Table Enhancement
|
||||||
|
|
||||||
|
- Inline file type icons with color coding (using existing `getFileIcon` and `getFileIconColor`)
|
||||||
|
- Quick-action buttons on hover: copy link, download, delete
|
||||||
|
- Click-to-expand row revealing file details: analytics preview, share link, expiry countdown
|
||||||
|
- Better sort controls: date, name, size, type with visual indicators
|
||||||
|
|
||||||
|
### New Components (added within existing dashboard structure)
|
||||||
|
|
||||||
|
- **Search + filters bar** — above the table, type filter chips, date range, size range
|
||||||
|
- **Storage usage bar** — near stats cards, shows used vs. available
|
||||||
|
- **Recent activity feed** — compact section below stats, last 5-10 events with timestamps and badges
|
||||||
|
- **File detail slide-over** — triggered by clicking a file row, contains:
|
||||||
|
- File info (name, size, type, upload date, expiry)
|
||||||
|
- Share link with copy button
|
||||||
|
- QR code for the share link
|
||||||
|
- Analytics mini-chart (views/downloads over last 30 days)
|
||||||
|
- Delete action with confirmation
|
||||||
|
- **Batch operations** — checkbox column, bulk delete, bulk copy links
|
||||||
|
|
||||||
|
### Polish Details
|
||||||
|
|
||||||
|
- Smooth animations on card hover, row expand, filter changes
|
||||||
|
- Skeleton loading states while data loads
|
||||||
|
- Better empty state for new users with upload CTA
|
||||||
|
|
||||||
|
### Files to Create/Modify
|
||||||
|
|
||||||
|
- `cshare-app/src/pages/DashboardPage.jsx` — enhance existing
|
||||||
|
- `cshare-app/src/components/StatsCards.jsx` — new, extracted stat cards section
|
||||||
|
- `cshare-app/src/components/FileDetailSlideOver.jsx` — new slide-over panel
|
||||||
|
- `cshare-app/src/components/ActivityFeed.jsx` — new activity feed component
|
||||||
|
- `cshare-app/src/components/StorageBar.jsx` — new storage usage indicator
|
||||||
|
- `cshare-app/src/components/SkeletonLoader.jsx` — new reusable skeleton
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Track 3: Frontend — App-Wide Polish & Micro-Interactions
|
||||||
|
|
||||||
|
### Animations & Transitions
|
||||||
|
|
||||||
|
- Page transitions: subtle fade + slide between route changes
|
||||||
|
- Staggered entrance animations on card grids and file lists (elements appear sequentially)
|
||||||
|
- Button press feedback: scale-down on mousedown, spring-back on release
|
||||||
|
- Card hover: gentle lift with shadow deepening
|
||||||
|
|
||||||
|
### Loading States
|
||||||
|
|
||||||
|
- Skeleton screens for file lists, stat cards, and page content (no spinners)
|
||||||
|
- Upload progress: smoother easing curves on the progress bar
|
||||||
|
- File preview loading: blur-up placeholder technique
|
||||||
|
|
||||||
|
### Mobile Refinements
|
||||||
|
|
||||||
|
- Swipe gestures on file cards (swipe left to reveal delete)
|
||||||
|
- Better touch targets: minimum 44px hit areas
|
||||||
|
- Bottom sheet for file details on mobile (instead of slide-over)
|
||||||
|
- Pull-to-refresh on dashboard
|
||||||
|
|
||||||
|
### Micro-Interactions
|
||||||
|
|
||||||
|
- Copy-to-clipboard: checkmark animation + toast
|
||||||
|
- Delete confirmation: slide-in modal with undo option
|
||||||
|
- Share link generation: animated link appearance with "Copied!" feedback
|
||||||
|
- File type icons: subtle bounce on appearance
|
||||||
|
|
||||||
|
### Other
|
||||||
|
|
||||||
|
- 404 page with CShare branding and "Upload a file" CTA
|
||||||
|
- Better scroll-to-top on navigation
|
||||||
|
- Enhance existing `useScrollReveal` for below-fold content
|
||||||
|
|
||||||
|
### Files to Create/Modify
|
||||||
|
|
||||||
|
- `cshare-app/src/pages/NotFoundPage.jsx` — new 404 page
|
||||||
|
- `cshare-app/src/components/PageTransition.jsx` — new route transition wrapper
|
||||||
|
- `cshare-app/src/hooks/useCountUp.js` — new animated number hook
|
||||||
|
- `cshare-app/src/hooks/useSwipe.js` — new swipe gesture hook
|
||||||
|
- `cshare-app/src/components/SkeletonLoader.jsx` — reusable skeleton
|
||||||
|
- `cshare-app/src/index.css` — new animation keyframes and utility classes
|
||||||
|
- Various page files — apply transitions and polish
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Order
|
||||||
|
|
||||||
|
1. **Skeleton + loading states** — immediately improves perceived performance
|
||||||
|
2. **Dashboard stat cards enhancement** — animated count-up, trend indicators
|
||||||
|
3. **File table enhancements** — hover actions, expand rows, sort controls
|
||||||
|
4. **Backend analytics API** — event recording, stats endpoints (parallel with #2-3)
|
||||||
|
5. **File detail slide-over** — info, share link, QR code, analytics chart
|
||||||
|
6. **Activity feed + storage bar** — new dashboard sections
|
||||||
|
7. **Page transitions** — route-level fade + slide
|
||||||
|
8. **Micro-interactions** — copy feedback, delete undo, icon bounce
|
||||||
|
9. **Mobile refinements** — swipe, bottom sheet, touch targets
|
||||||
|
10. **404 page** — standalone task
|
||||||
|
11. **Wire frontend to real API** — swap mock data for analytics endpoints
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Out of Scope
|
||||||
|
|
||||||
|
- Authentication pages (login/register/account) — separate effort
|
||||||
|
- Stripe payments integration
|
||||||
|
- PostgreSQL migration
|
||||||
|
- Cloudflare R2 storage migration
|
||||||
|
- Email verification flows
|
||||||
Reference in New Issue
Block a user