# NAS Tools Project

## PDD Workflow

This project follows **PDD (Product Definition Document)** development.

**Always read these files before writing code:**
- `docs/PDD.md` — product vision, goals, targets (the north star)
- `docs/specs/active.md` — current sprint spec (what we're building now)

**Workflow:**
1. PDD → Sprint Spec → Implementation → Validate ACs
2. Scope changes update the sprint spec first, code second
3. Never ship without ACs passing

## Dev Commands

- **Build dashboard:** `cd dashboard/frontend && npm run build`
- **Dev dashboard:** `cd dashboard/backend && uvicorn main:app --reload` + `cd dashboard/frontend && npm run dev`
- **Test:** `cd dashboard && python -m pytest backend/tests/`
- **Deploy:** Push to main → Gitea CI builds + deploys to NAS

## Architecture

- **Synology DS224+** (x86_64, 18GB RAM), Tailscale IP: `100.78.131.124`, LAN: `192.168.31.221`
- **Docker:** `/volume1/@appstore/ContainerManager/usr/bin/docker`, compose dirs: `/volume1/docker/*`
- **VPS Caddy** (`161.33.182.109`, Tailscale: `100.109.198.126`): reverse proxy for `*.jimmygan.com`
- **Build VPS** (server2, `158.101.140.85`, Tailscale: `100.70.115.1`): podman builds
- **NAS Caddy:** port 8443 fallback only (SNI broken)

### Dashboard
- Backend: Python FastAPI (`dashboard/backend/`)
- Frontend: Svelte 5 + Tailwind CSS (`dashboard/frontend/`)
- Svelte 5 runes: `$state`, `$props`, `$bindable` (not `export let`)
- New pages: create route in `src/routes/`, import in `App.svelte`, update `Sidebar.svelte`

### CI/CD
Two Gitea workflows in `.gitea/workflows/`:
- **deploy.yml** — main branch: tests → build → deploy to production
- **deploy-dev.yml** — dev branch: tests → build → deploy to dev

Build flow: VPS builds → pushes to local registry (`100.78.131.124:5501/`) → streams to NAS → `docker compose up -d`

## Key Files

- `docs/architecture.md` — full architecture reference
- `docs/TESTING.md` — test patterns and conventions
- `specs/` — sprint history
- `.gitea/workflows/deploy.yml` — main CI
- `.gitea/workflows/deploy-dev.yml` — dev CI
- `dashboard/backend/main.py` — FastAPI entry point
- `dashboard/frontend/src/App.svelte` — Svelte entry point

## Synology Quirks

- No `crontab` — edit `/etc/crontab` with `sudo` + `printf`, restart crond
- No `scp` subsystem — use `cat file | ssh ... 'cat > dest'`
- ACLs override Unix perms — use `sudo chmod 777` + `synoacltool -enforce-inherit`
- Tailscale userspace mode — cannot bind Docker ports to Tailscale IPs

## DNS

- dnsmasq on NAS resolves `*.jimmygan.com` → `161.33.182.109` (Caddy VPS)
- Tailscale split DNS: `jimmygan.com` → NAS (queries hit dnsmasq)