# Repository Guidelines

## Commands

Run from `cshare-app/`:

```sh
npm run dev       # Vite dev server
npm run build     # Build + precompress (creates .gz/.br)
npm run check     # lint + build (run before committing)
npm run lint      # ESLint
```

Run from `backend/`:

```sh
npm run dev       # tsx watch src/server.ts
npm test          # tsx --test test/*.test.ts
npm run build     # tsc
npm run check     # test + build (run before committing)
```

## Architecture

**Two packages:** `cshare-app/` (React 19 + Vite 8, JavaScript/JSX, no TypeScript) and `backend/` (Express 5 + TypeScript strict mode).

**Backend storage:** Currently uses local JSON (`backend/data/db.json`) and disk storage. PostgreSQL/Redis/R2 adapters are planned in `CONTINUE.md` but not yet implemented.

**Frontend routing:** React Router v7 with lazy-loaded routes. All routes defined in `src/App.jsx`.

**Styling:** Tailwind CSS 4 via `@tailwindcss/vite` plugin (not PostCSS). Custom design system in `src/index.css` with CSS variables and component classes (`.btn`, `.card`, `.input`).

**Toast system:** `ToastProvider` wraps app in `App.jsx`. Use `useToast()` hook → `addToast(message, type)` where type is `'success' | 'info' | 'error'`.

**API client:** `src/lib/api.js` contains `uploadFile` (XHR with progress), `listFiles`, `deleteFile`, `getDashboardStats`, `resolveLink`, `downloadUrl`, `previewUrl`.

## Environment

**Frontend:** Set `VITE_API_BASE_URL=http://localhost:4001` only when API runs on different port. Omit in production if using Nginx reverse proxy (frontend calls `window.location.origin`).

**Backend:** Requires `.env` with `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`, `ADMIN_API_KEY` (64+ char random strings). See `backend/.env.example`.

**Build gotcha:** `dist/` may be owned by root. If `npm run build` fails with `EACCES`, run `sudo chown -R $(whoami) cshare-app/dist/`.

## Key Files

- `CONTINUE.md` — Full production roadmap (Postgres, Redis, R2, auth, Stripe implementation plan)
- `CLAUDE.md` — Detailed architecture reference
- `PRODUCTION.md` — Deployment and Nginx configuration
- `cshare-app/src/App.jsx` — All route definitions
- `cshare-app/src/lib/api.js` — API client
- `backend/src/server.ts` — Express app bootstrap
- `backend/ecosystem.config.cjs` — PM2 configuration (reads `.env` file)

## Style

**Frontend:** PascalCase for components (`UploadPage.jsx`), camelCase for hooks (`useLenis.js`) and data modules (`mockData.js`). Two-space indentation, single quotes, semicolons.

**Backend:** TypeScript strict mode, named exports. Route modules named by resource (`files.ts`, `links.ts`, `auth.ts`).

ESLint configured in `cshare-app/eslint.config.js` (flat config, React hooks + refresh plugins).