# 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