# CLAUDE.md

Project context for Claude Code. See `PLANNING.md` for the full roadmap.

## What this is
A lightweight web GUI to manage file shares on a single home server (Proxmox
LXC/VM) — a minimal NAS control panel. It manages **SMB shares**, **NFS
exports**, and **quotas** by editing host config files and reloading the
daemons. Home/LAN use only.

## Files
- `app.py` — Flask backend (API + share/export/quota logic).
- `index.html` — Bootstrap single-page UI.
- `docker-compose.yml` — optional dev/test sandbox only.
- `PLANNING.md` — roadmap and feature list.

## How it runs (target)
Directly on the LXC/VM as a `systemd` service, Flask behind `gunicorn`.
**Not** in Docker for production — the app manipulates host services
(`smbd`, `nfsd`, `/etc/exports`, `exportfs`, `setquota`), so it must run on the
host. Docker stays only as a test sandbox.

## Conventions & constraints
- **Keep it simple.** No database, no auth framework, dependency-light. Config
  files (`/etc/samba/smb.conf`, `/etc/exports`) are the source of truth.
- **Security basics are non-negotiable even for home use:**
  - Never use `subprocess.run(..., shell=True)` with user input. Use argument
    lists.
  - Validate all input: names `^[A-Za-z0-9_-]+$`; paths must resolve under
    `/srv`.
  - All routes require auth (single-user HTTP Basic Auth from an env var).
- **Config edits must be safe:** parse into blocks and rewrite whole files for
  edit/delete — do not blindly append.
- LAN-only. Do not add internet-facing features.

## Out of scope
Backups (handled by Proxmox Backup Server), multi-user roles, databases,
internet exposure, multi-host management.

## Working agreement
- Work in the phases defined in `PLANNING.md`; pause after each phase for the
  user to test.
- Explain changes briefly. Don't add heavy dependencies without asking.