# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

CShare is a file-sharing web application with a React frontend and an Express/TypeScript backend. The frontend is feature-rich with 12+ pages; the backend is live and working with local JSON storage. The backend (Postgres, R2 storage, auth, Stripe) is the next major work item (see `CONTINUE.md`).

## Commands

All commands run from `/srv/CShare/cshare-app/`:

```bash
npm run dev       # Start Vite dev server with HMR
npm run build     # Production build to dist/
npm run lint      # ESLint (flat config, React hooks + refresh plugins)
npm run preview   # Serve production build locally
```

No test framework is configured yet.

Backend commands run from `/srv/CShare/backend/`:

```bash
npm run dev       # Start API with tsx watch
npm test          # Run test suite (tsx --test)
npm run build     # Compile TypeScript to dist/
```

## Architecture

**Stack:** React 19 + Vite 8, Tailwind CSS 4 (via `@tailwindcss/vite` plugin), no TypeScript. Backend: Express 5 + TypeScript + tsx.

**Routing:** React Router v7 with lazy-loaded routes and real URLs. All routes defined in `App.jsx`. Page keys: `/`, `/upload`, `/dashboard`, `/preview/:linkId`, `/pricing`, `/docs`, `/about`, `/blog`, `/careers`, `/contact`, `/privacy`, `/terms`, `/security`, `/gdpr`. A catch-all `*` route renders `NotFoundPage`.

**Directory layout (inside `cshare-app/src/`):**
- `pages/` — One component per view. Pages receive route props; `LandingPage` and `UploadPage` also accept external data props.
- `components/` — `Navbar` (sticky, mobile hamburger), `Footer` (hidden on landing/fileview), `Icons` (17 hand-drawn SVG icons), `Toast` (`ToastProvider` context + `useToast` hook), `PageTransition` (route-level fade+slide wrapper), `SkeletonLoader` (shimmer skeleton components), `StorageBar` (segmented storage usage bar), `ActivityFeed` (recent activity feed), `FileDetailSlideOver` (slide-over panel for file details/analytics).
- `hooks/` — `useLenis` (smooth scroll), `useScrollReveal` (intersection observer for below-fold animations).
- `data/mockData.js` — 6 mock files + 1 `sharedFile` object, mock activity data, storage breakdown, and helper functions (`formatFileSize`, `formatDate`, `formatDateRelative`, `formatActivityTime`, `getFileIcon`, `getFileIconColor`).
- `lib/api.js` — API client with `uploadFile` (XHR with progress), `listFiles`, `deleteFile`, `getDashboardStats`, `resolveLink`, `downloadUrl`, `previewUrl`.
- `assets/` — Static images (hero.png, framework SVGs).

**Backend layout (inside `backend/src/`):**
- `routes/` — `files.ts`, `auth.ts`, `links.ts`, `dashboard.ts`, `admin.ts`
- `middleware/` — `session.ts`, `errorHandler.ts`, `rateLimit.ts`, `adminAuth.ts`
- `services/` — `store.ts` (JSON file storage)
- `utils/` — `crypto.ts`, `files.ts`, `gdrive.ts`, `preview.ts`
- `server.ts` — Express app bootstrap
- `worker.ts` — Background worker entry

**Toast system:** `ToastProvider` wraps the app in `App.jsx`. Components call `useToast()` to get `addToast(message, type)` — types are `'success'`, `'info'`, `'error'`. Auto-dismisses after 3s.

**Styling:** `index.css` defines the full design system via CSS custom properties and component classes (`.btn`, `.btn-primary`, `.btn-secondary`, `.btn-ghost`, `.btn-danger`, `.card`, `.input`, `.heading-*`, `.text-*`). Tailwind utilities are used alongside these custom classes. Dark charcoal background (`#0D0D0F`) with electric blue accent (`#4A90FF`) — zero purple anywhere. Keyframe animations available: `fadeIn`, `fadeInUp`, `slideDown`, `scaleIn`, `shimmer`, `progressPulse`, `gradientMove`, `float`, `spin`, `slideInRight`, `staggerIn`, `pageFadeIn`, `copyPop`, `iconBounce`, `orbFloat1-3`, `dashMarch`, `shimmerBar`, `pulseGlow`, `countPop`, `revealLine`, `borderGlow`, `gentlePulse`.

**Fonts:** Three families loaded via `@font-face` from `/public/fonts/` — Syne (headings), Outfit (body), Playfair (decorative).

**Data flow:** Frontend calls real API endpoints via `lib/api.js`. Dashboard loads files and stats from the backend; falls back to mock data when API is unavailable. Upload uses real XHR with progress tracking. The backend stores data in `data/db.json`.

## Key Files

- `CONTINUE.md` — Full production roadmap: what's built and what's next (Postgres, Redis, R2, auth, Stripe, workers, hardening).
- `AGENTS.md` — Repository guidelines: coding style, build commands, commit conventions.
- `docs/superpowers/specs/2026-05-30-dashboard-polish-design.md` — Design spec for dashboard enhancement and app polish (frontend + backend analytics API).

## Build Note

The `dist/` directory may be owned by root (from a previous build). If `npm run build` fails with `EACCES`, fix ownership first: `sudo chown -R $(whoami) cshare-app/dist/`.