From 64ae9731e7dd40d933e20a8bd8d65884b8a91c8e Mon Sep 17 00:00:00 2001 From: arsam Date: Fri, 18 Sep 2026 23:15:37 +0330 Subject: [PATCH] Import documentation: CLAUDE.md Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality. --- CLAUDE.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5b1210b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,68 @@ +# 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/`.