# Project Overview
NetWave is a self-hosted media streaming application with a React/Vite/Tailwind client and an Express/TypeScript server backed by SQLite. It scans configured local directories for audio and video files, indexes metadata into SQLite, serves searchable/paginated media APIs, streams audio/video through direct file serving or FFmpeg transcoding, and presents a PWA-capable frontend with MobX-managed playback, queueing, likes, playlists, infinite scrolling, and media-session integration.

# Project Map
- `package.json` (repo root): orchestration scripts for running/building both apps together.
- `client/`: Vite React frontend.
- `client/src/main.tsx`: app bootstrap; wraps the app in the MobX `StoreProvider`.
- `client/src/App.tsx`: top-level router; gates setup/login vs authenticated app routes.
- `client/src/store.ts`: the main client state container. `MediaStore` normalizes track entities and liked state, `PlayerStore` owns playback/queue/queue-source extension, `PlaylistStore` owns playlist CRUD and paginated playlist items, and `AuthStore` mirrors auth state from `localStorage`.
- `client/src/api.ts`: Axios API layer plus stream/cover URL builders. Stream URLs intentionally embed the JWT in a query string for use by `<audio>`/`<video>` tags.
- `client/src/components/Layout.tsx`: app shell with sidebar, content area, and persistent bottom player.
- `client/src/components/PlayerBar.tsx`: the most sensitive client file. Owns the active media elements, play/pause/seek behavior, expanded player UI, queue preloading, media-session integration, and next-track warmup.
- `client/src/components/Sidebar.tsx`: primary navigation plus playlist tree/create/rename UI.
- `client/src/components/TrackRow.tsx`: reusable list row for tracks.
- `client/src/components/PlaylistMenu.tsx`: track context menu with playlist and queue flyouts.
- `client/src/pages/`: routed screens: `Library`, `Search`, `Liked`, `Playlists`, `Queue`, `Settings`, `Admin`, `Login`, `Setup`.
- `client/public/manifest.json`, `client/public/sw.js`, `client/public/icon-*.png`: PWA manifest, service worker, and install icons.
- `server/`: Express backend.
- `server/src/index.ts`: server entrypoint; loads env, initializes the DB, mounts API routes, serves `client/dist` in production, and shuts down FFmpeg child processes on exit.
- `server/src/db/index.ts`: opens `server/data/netwave.db`, enables WAL, creates tables/indexes imperatively, and applies simple additive migrations with `ALTER TABLE ... ADD COLUMN` inside `try/catch`.
- `server/src/db/schema.ts`: Drizzle schema definition for `users`, `settings`, `sources`, `media`, `playlists`, `playlist_items`, and `likes`.
- `server/src/routes/auth.ts`: first-run setup, signup/login, JWT auth, and profile update endpoints.
- `server/src/routes/admin.ts`: admin-only source management, indexing, settings, and stats. Admin access is additionally gated by localhost/private-network checks unless `remote_access` is enabled.
- `server/src/routes/media.ts`: authenticated metadata APIs for media listing, search, likes, playlist CRUD, and playlist item pagination.
- `server/src/routes/stream.ts`: authenticated media streaming, transcoding, audio extraction for videos, cover art delivery, and FFmpeg child-process lifecycle management.
- `server/src/services/indexer.ts`: recursive media indexing pipeline; reads files from configured sources, extracts metadata with `music-metadata`/`ffprobe`, and upserts into SQLite.
- `server/src/services/sourceProvider.ts`: local filesystem source walker and supported extension list.
- `server/src/services/thumbnailCache.ts`: separate SQLite-backed thumbnail cache in `server/data/thumbnails.db`; resizes images through FFmpeg.
- `server/data/`: runtime SQLite databases and WAL/SHM files. These are application state, not source files.
- `setup_test_db.js`: helper script that seeds a dummy media row directly into the DB for local debugging.
- `get_admin_token.js`: helper script that prints a JWT for the first admin user in the DB. Treat as a local debugging tool only.
- `admin_token.txt`: scratch file in repo root; treat as sensitive/local-only if it is ever populated.
- `System.Drawing.Drawing2D.GraphicsPath`: stray/generated artifact in the repo root. Do not rely on it for app behavior.

# Build/Test Scripts
- Install all dependencies: `npm run setup`
- Run full stack in development: `npm run dev`
- Run backend only in development: `npm run dev:server`
- Run frontend only in development: `npm run dev:client`
- Build backend only: `npm run build:server`
- Build frontend only: `npm run build:client`
- Build the full project: `npm run build`
- Lint the frontend: `cd client && npm run lint`
- Preview the production frontend build: `cd client && npm run preview`
- Run the built backend: `cd server && npm run start`
- Automated tests: there is currently no `npm test` script or formal test suite in this repository. The minimum validation path is `npm run build` plus `cd client && npm run lint`.
- Optional local DB helpers: `node setup_test_db.js` and `node get_admin_token.js`

# Code Style
- TypeScript strict mode is enabled on both client and server; the client additionally enables `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`, and `noUncheckedSideEffectImports`.
- Use ES modules everywhere.
- Prefer single quotes and keep semicolons; that is the dominant style across the repo.
- Match the surrounding file’s indentation rather than reformatting wholesale. The client and server are not perfectly uniform.
- Use React function components and hooks; no class components are used in app code.
- Client state should flow through MobX stores in `client/src/store.ts`, not duplicated local state across pages/components. Normalize track entities through `MediaStore` whenever new media records are loaded.
- Wrap reactive React components with `asObserver(...)` from `client/src/store.ts`.
- The frontend styling approach is Tailwind utility classes in JSX plus shared theme variables in `client/src/index.css`.
- Do not mass-reformat files or switch quoting/spacing styles unless asked. Keep diffs surgical.
- Avoid introducing new `any` types unless the boundary is genuinely dynamic and the surrounding code already follows that pattern.

# Security
- Do not hand-edit or delete `server/data/netwave.db`, `server/data/thumbnails.db`, or their `-wal`/`-shm` companions unless the task is explicitly about DB repair/reset. These are live application state.
- Treat `admin_token.txt`, JWTs, and anything emitted by `get_admin_token.js` as sensitive. Never commit real tokens or log them in new code.
- `server/src/middleware/auth.ts` currently has an insecure default `JWT_SECRET` fallback for development. Do not rely on that in production-facing changes, and do not weaken auth checks.
- Do not casually loosen `server/src/middleware/admin.ts`; admin routes are intentionally limited to admins on localhost/private networks unless `remote_access` is enabled.
- Do not remove stream auth from `server/src/routes/stream.ts` or the token-bearing stream URL logic in `client/src/api.ts`; `<audio>`/`<video>` elements depend on it.
- Source paths added through admin settings point to real filesystem directories outside the repo. Do not write destructive code that mutates source media folders.
- FFmpeg is part of the runtime contract for transcoding, audio extraction, and thumbnail resizing. Changes around FFmpeg process handling can affect stability and resource usage.

# Guardrails
- Preserve the split architecture: the client only talks to the server through `/api` and stream URLs; the server owns indexing, auth, persistence, and filesystem/FFmpeg access.
- Prefer build-safe changes. At minimum, re-run `npm run build` after meaningful edits; also run `cd client && npm run lint` when touching client TypeScript/React code.
- Be careful with route ordering in `server/src/routes/media.ts`: static paths like `/playlists/list` must stay above dynamic `/:id` routes.
- Be careful with streaming changes in `server/src/routes/stream.ts` and playback changes in `client/src/components/PlayerBar.tsx`; these are the highest-risk areas for regressions in audio/video playback.
- Keep paginated list behavior consistent. Library, liked songs, search, playlists, and queue extension all assume page sizes of 100 and infinite scrolling semantics.
- When creating playback queues from paginated lists, preserve queue-source metadata so the queue can extend itself as playback or queue scrolling approaches the end.
- Prefer updating MobX stores over pushing one-off fixes into page-local component state. Global sync issues in this app are usually store-design issues.
- Do not hand-edit generated/runtime assets in `client/dist/` or `server/dist/`; rebuild instead.
- Do not assume helper scripts are production-grade. `setup_test_db.js` and `get_admin_token.js` are debugging conveniences only.
- Avoid touching unrelated root artifacts like `System.Drawing.Drawing2D.GraphicsPath` unless cleanup is explicitly requested.