nas-tools/CLAUDE.md

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)