CShare/CLAUDE.md

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/:

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/:

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/.