adds dashbaord init

2026-04-16 13:55:10 -04:00
parent 2353b19ee7
commit 2bdddd3188
2 changed files with 520 additions and 0 deletions
@@ -0,0 +1,493 @@
 # thekims-dashboard — Claude Code Plan
 A DAKboard-style family dashboard served at `https://thekims.family/dashboard`, rendered on a Raspberry Pi 5 driving a 1440p portrait monitor via Firefox kiosk mode.
 ---
 ## Architecture Overview
 ```
 ┌─────────────────────┐       ┌──────────────────────────────────┐
 │  Raspberry Pi 5     │       │  hantim (Vultr VPS)              │
 │  Firefox kiosk mode │──────▶│  nginx ─► Go binary (Docker)     │
 │  1440x2560 portrait │       │           ├─ /dashboard          │
 └─────────────────────┘       │           ├─ /dashboard/admin    │
                              │           └─ /dashboard/api/*    │
                              │                                  │
                              │  config.json (Docker volume)     │
                              │  themes/*.css (Docker volume)    │
                              └───────┬──────────┬───────────────┘
                                      │          │
                         ┌────────────┘          └────────────┐
                         ▼                                    ▼
                ┌───────────────────┐                ┌─────────────────┐
                │ External Services │                │ Home Server     │
                │ - api.weather.gov │                │ (argento)       │
                │ - CalDAV servers  │                │ - Immich API    │
                │   (incl Google)   │                │                 │
                └───────────────────┘                └─────────────────┘
 ```
 **Key decisions:**
 - Go backend does ALL external fetching. Client never talks to third-party services.
 - Client receives lightweight JSON + proxied images. Vanilla JS: poll, swap DOM, CSS transitions.
 - Server caches aggressively. Client polls server on staggered intervals.
 - No frameworks (JS or Go). Vanilla JS. Go `html/template`. CSS custom properties for theming.
 ---
 ## Go Concepts You'll Encounter, By Phase
 This is not a Go tutorial — you'll pick up syntax from Claude Code and the spec. This section maps *engineering concepts you already know* to *Go's way of expressing them*, so you can pattern-match instead of cargo-culting.
 ### The things that'll feel familiar
 - Statically typed, compiled, C-family syntax.
 - Structs instead of classes. Methods are functions with a receiver argument.
 - Explicit error returns (`val, err := doThing()`) instead of exceptions. You'll write `if err != nil` hundreds of times. This is normal.
 - Interfaces are satisfied implicitly — if your struct has the right method signatures, it implements the interface. No `implements` keyword.
 ### The things that'll trip you up
 **Packages, not files.** All `.go` files in a directory share the same package namespace. There are no file-scoped imports or per-file visibility. If you declare `func helper()` in `a.go` and `func Handler()` in `b.go` in the same package, `Handler` can call `helper` directly. Capitalization controls visibility: `Exported` (public) vs `unexported` (package-private).
 **No constructors.** You'll see a convention of `NewThing()` functions that return initialized structs. That's just a convention, not language machinery.
 **Goroutines and channels.** Go's concurrency primitive. `go doSomething()` spawns a lightweight thread. Channels (`chan T`) are typed pipes between goroutines. You'll use these for the cache refresh tickers and background photo list fetching. The `sync` package (`sync.Mutex`, `sync.RWMutex`) is the alternative when channels are overkill.
 **`context.Context`.** Passed as the first argument to almost every function that does I/O. It carries deadlines, cancellation signals, and request-scoped values. The HTTP handler gives you one via `r.Context()`. Thread it through to all downstream calls.
 **Dependency injection via struct fields.** Go has no DI framework. You wire dependencies manually:
 ```go
 type Server struct {
    config  *config.Config
    photos  *photos.Manager
    weather *weather.Client
 }
 ```
 Construct it in `main()`, pass it around. This will feel tedious at first. It's intentional — the dependency graph is always explicit.
 **`defer`.** Schedules a function call to run when the enclosing function returns. Used for cleanup: `defer file.Close()`, `defer mutex.Unlock()`. Runs in LIFO order. You'll use it constantly.
 **Zero values.** Uninitialized variables get the zero value for their type: `0` for ints, `""` for strings, `nil` for pointers/slices/maps. This matters because Go has no `null` in the Java/JS sense — but `nil` on a slice or map will still panic if you write to it without initializing.
 **Slices vs arrays.** You almost never use arrays directly. Slices (`[]T`) are the standard dynamic-length sequence type. `append()` grows them. They're reference types (like Java's ArrayList, but built-in).
 **Error wrapping.** `fmt.Errorf("failed to fetch weather: %w", err)` wraps an error with context while preserving the original for `errors.Is()` / `errors.As()` checks downstream. Always wrap, never swallow.
 ### Project layout conventions
 Go doesn't enforce directory structure, but the community follows a loose standard:
 ```
 thekims-dashboard/
 ├── main.go                    # Entry point only: wire deps, start server
 ├── go.mod                     # Module name + dependencies (like package.json)
 ├── go.sum                     # Lock file (committed to git)
 │
 ├── internal/                  # Private to this module — can't be imported externally
 │   ├── config/
 │   │   └── config.go
 │   ├── server/
 │   │   └── server.go          # HTTP server struct, router setup, middleware
 │   ├── handler/
 │   │   ├── pages.go
 │   │   ├── api_config.go
 │   │   ├── api_photo.go
 │   │   ├── api_calendar.go
 │   │   └── api_weather.go
 │   ├── service/
 │   │   ├── photo/
 │   │   │   ├── manager.go     # Rotation logic, queue, index tracking
 │   │   │   └── immich.go      # Immich API client
 │   │   ├── calendar/
 │   │   │   └── caldav.go      # CalDAV client, event parsing/merging
 │   │   └── weather/
 │   │       └── nws.go         # NWS API client, zip-to-latlon
 │   └── cache/
 │       └── cache.go           # Generic TTL cache
 │
 ├── templates/
 │   ├── dashboard.html
 │   └── admin.html
 │
 ├── static/
 │   ├── css/
 │   │   └── dashboard.css
 │   ├── js/
 │   │   ├── dashboard.js
 │   │   └── admin.js
 │   └── themes/
 │       └── default.css
 │
 ├── data/                      # Docker volume mount (gitignored)
 │   ├── config.json
 │   └── themes/
 │
 ├── Dockerfile
 ├── docker-compose.yml
 └── README.md
 ```
 The `internal/` directory is special in Go — the compiler enforces that nothing outside this module can import packages under it. It's the idiomatic way to say "these are implementation details."
 ---
 ## Data Model
 ### config.json
 ```json
 {
  "timezone": "America/New_York",
  "weather": {
    "zip_code": "22030",
    "lat": 38.8462,
    "lon": -77.3064,
    "grid_office": "LWX",
    "grid_x": 90,
    "grid_y": 78,
    "observation_station": "KDAA"
  },
  "photo_sources": [
    {
      "id": "immich-main",
      "type": "immich",
      "name": "Family Photos",
      "url": "https://photos.example.com",
      "api_key": "...",
      "album_id": "optional-album-uuid"
    }
  ],
  "active_photo_source": "immich-main",
  "calendar_sources": [
    {
      "id": "family-cal",
      "name": "Family",
      "url": "https://caldav.example.com/dav/calendars/...",
      "username": "...",
      "password": "...",
      "color": "#e74c3c"
    },
    {
      "id": "google-tim",
      "name": "Tim's Google",
      "url": "https://apidata.googleusercontent.com/caldav/v2/.../events",
      "username": "tim@gmail.com",
      "password": "app-specific-password",
      "color": "#3498db"
    }
  ],
  "active_theme": "default",
  "photo_interval_seconds": 10,
  "calendar_refresh_seconds": 60,
  "weather_refresh_seconds": 600
 }
 ```
 **Weather grid resolution:** On admin save of a zip code, the backend geocodes zip → lat/lon, calls `GET https://api.weather.gov/points/{lat},{lon}` to resolve `gridId`, `gridX`, `gridY`, and nearest `observationStation`, then persists all resolved values so subsequent weather fetches skip re-resolution.
 ---
 ## API Endpoints
 All prefixed with `/dashboard/api`. All return `application/json` unless noted.
 | Endpoint | Method | Description |
 |---|---|---|
 | `/config` | GET | Display-relevant config (timezone, theme, intervals). No secrets. |
 | `/config` | POST | Full config update from admin. Triggers cache invalidation. |
 | `/photo/current` | GET | `{imageUrl, sourceUrl, index, total}` |
 | `/photo/next` | GET | Same shape, for preloading. |
 | `/photo/image/{index}` | GET | Proxied image binary. Resized server-side to ≤2560px tall. |
 | `/calendar/today` | GET | `{events: [{title, start, end, color, calendarName}]}` |
 | `/calendar/month` | GET | `{startDate, endDate, events: [...]}` — 4-week window |
 | `/weather` | GET | `{current: {temp, humidity, condition, icon}, today: {high, low}}` |
 | `/themes` | GET | List available theme filenames. |
 | `/themes/{name}` | GET | Serve CSS file. |
 ---
 ## Frontend Notes
 ### Display page DOM
 ```html
 <body class="dashboard" data-theme="default">
  <div id="photo-layer">
    <img id="photo-a" class="photo active" />
    <img id="photo-b" class="photo" />
  </div>
  <div id="gradient-overlay"></div>
  <div id="overlay-top-left" class="overlay">
    <canvas id="qr-code"></canvas>
  </div>
  <div id="overlay-top-center" class="overlay">
    <div id="clock-time"></div>
    <div id="clock-date"></div>
  </div>
  <div id="overlay-top-right" class="overlay">
    <h2>Today</h2>
    <ul id="today-events"></ul>
  </div>
  <div id="overlay-weather" class="overlay">
    <div id="weather-temp"></div>
    <div id="weather-condition"></div>
    <div id="weather-range"></div>
    <div id="weather-humidity"></div>
  </div>
  <div id="calendar-month">
    <div class="calendar-header">
      <span>S</span><span>M</span><span>T</span><span>W</span>
      <span>T</span><span>F</span><span>S</span>
    </div>
    <div id="calendar-grid"></div>
  </div>
 </body>
 ```
 **Photo crossfade:** Two `<img>` stacked via `position: absolute`. Toggle `.active` class, CSS `transition: opacity 1.5s ease`. After transition completes, preload next image into the hidden element.
 **Staggered polling:** `setInterval` with offsets — photos at t+0s, calendar at t+3s, weather at t+7s.
 **QR code:** `qrcode-generator` library (~4 KB, no deps, renders to canvas). Updates on each photo swap.
 ### Admin page
 Vanilla HTML form. Sections: timezone select (auto-detect via `Intl.DateTimeFormat`), zip code, photo sources (dynamic add/remove), calendar sources (dynamic with color picker), theme upload + selector. `admin.js` serializes → `POST /api/config`.
 ---
 ## Implementation Phases
 Each phase introduces Go concepts incrementally. Complete each end-to-end (compile, run, test in browser) before moving to the next.
 ---
 ### Phase 1 — Hello World Web Server
 **Goal:** Go toolchain, first compiled binary, first HTTP response.
 **Go concepts introduced:** `go mod init`, packages, `net/http`, `http.HandleFunc`, `http.ListenAndServe`, `log` package, `html/template`.
 **Steps:**
 1. `go mod init git.timothykim.net/timothy/thekims-dashboard`
 2. `main.go`: register one route (`GET /dashboard`), return a hardcoded HTML string. Run with `go run .`
 3. Add `templates/dashboard.html` with the full DOM structure from above (hardcoded placeholder content). Parse and execute via `html/template`.
 4. Serve `static/` via `http.FileServer`. Add `dashboard.css` with the portrait 1440×2560 layout. Add empty `dashboard.js`.
 5. Dockerfile + docker-compose.yml. Build, run, verify.
 **End state:** `http://localhost:8080/dashboard` renders the full layout skeleton with placeholder text and styling. No dynamic data.
 **Claude Code prompt hint:** *"Set up a Go HTTP server that serves an HTML template at /dashboard and static files from /static/. Use Go 1.22+ stdlib routing. Show me idiomatic project structure."*
 ---
 ### Phase 2 — Config System
 **Goal:** JSON persistence, struct serialization, first custom package.
 **Go concepts introduced:** Structs with JSON tags, `encoding/json`, `os.ReadFile`/`os.WriteFile`, `internal/` packages, exported vs unexported, pointer receivers.
 **Steps:**
 1. Define `Config` struct in `internal/config/config.go` with all JSON tags.
 2. `Load(path) (*Config, error)` — read file, unmarshal. Return defaults if file missing.
 3. `Save(path) error` — marshal indented, write atomically (temp file + `os.Rename`).
 4. Wire into `main.go`: load on startup, pass to handlers.
 5. `GET /dashboard/api/config` — return sanitized config (strip credentials).
 6. `POST /dashboard/api/config` — accept JSON, validate, save, reload in-memory state.
 **Atomic write note:** `os.Rename` is atomic on Linux (same filesystem). Write to `config.json.tmp`, then rename. Prevents corruption on crash.
 **End state:** POST config from curl, restart server, GET returns persisted values.
 **Claude Code prompt hint:** *"Create a config package under internal/ that loads/saves JSON. Show idiomatic error handling and struct tags. Use atomic file writes."*
 ---
 ### Phase 3 — Admin Page
 **Goal:** Functional admin UI that reads/writes config.
 **Go concepts introduced:** Template data passing, `http.ServeFile`.
 **Steps:**
 1. `templates/admin.html` — full form, inject current config values via template.
 2. `static/js/admin.js` — form → JSON → `POST /api/config`, inline success/error feedback.
 3. Timezone dropdown (from IANA list).
 4. Dynamic add/remove rows for photo and calendar sources.
 5. Theme file upload: `POST /dashboard/api/themes/upload` (multipart form, save to `data/themes/`).
 **End state:** Fill form, save, refresh — values persist. Basic auth is nginx config (Phase 8), not app logic.
 ---
 ### Phase 4 — Weather Service
 **Goal:** First external HTTP client, first background goroutine, first cache.
 **Go concepts introduced:** `net/http` client, `json.Decoder`, `context.Context`, goroutines, `time.Ticker`, `sync.RWMutex`, generics.
 This is the simplest external integration (no auth, well-documented API) — a good place to learn the HTTP client patterns you'll reuse in calendar and photo services.
 **Steps:**
 1. `internal/service/weather/nws.go`:
   - `FetchCurrentConditions(ctx, station) → Observation`
   - `FetchForecast(ctx, office, gridX, gridY) → Forecast`
   - Both: `http.NewRequestWithContext`, set `User-Agent` header (NWS policy), decode JSON.
 2. `internal/cache/cache.go` — generic TTL cache using Go 1.18+ generics:
   ```go
   type Cache[T any] struct {
       mu    sync.RWMutex
       data  T
       exp   time.Time
       ttl   time.Duration
       fetch func(context.Context) (T, error)
   }
   func (c *Cache[T]) Get(ctx context.Context) (T, error)
   ```
   `Get()` returns cached value if fresh, else calls fetch function under write lock.
 3. Wire in `main.go`: weather cache with 10-min TTL.
 4. `GET /dashboard/api/weather`.
 5. Weather rendering in `dashboard.js` — fetch on load, poll every 600s with stagger offset.
 6. Zip → lat/lon resolution on admin save: embed a lookup table or call Census Geocoder API. Also resolve NWS grid point + observation station and persist to config.
 **End state:** Dashboard shows live weather. Change zip in admin → weather updates on next poll.
 **Claude Code prompt hint:** *"Write an HTTP client for the NWS weather.gov API. Show context usage, custom headers, JSON decoding. Then build a generic TTL cache with sync.RWMutex and generics."*
 ---
 ### Phase 5 — Calendar Service
 **Goal:** CalDAV integration, multi-source parallel fetch and merge.
 **Go concepts introduced:** Third-party deps (`go get`), interfaces, `sync.WaitGroup` for parallel fan-out, `time.LoadLocation`.
 **Steps:**
 1. `go get github.com/emersion/go-webdav`
 2. `internal/service/calendar/caldav.go`:
   - `FetchEvents(ctx, source, start, end) → []Event`
   - CalDAV `REPORT` with time-range filter, parse iCal response.
 3. Multi-source merge: fan out with goroutines, collect with `WaitGroup`:
   ```go
   var wg sync.WaitGroup
   results := make([][]Event, len(sources))
   for i, src := range sources {
       wg.Add(1)
       go func(i int, src CalDAVConfig) {
           defer wg.Done()
           events, err := FetchEvents(ctx, src, start, end)
           if err != nil {
               log.Printf("calendar %s: %v", src.Name, err)
               return
           }
           results[i] = events
       }(i, src)
   }
   wg.Wait()
   ```
 4. Cache merged result (1-min TTL).
 5. `GET /api/calendar/today` — filter to today.
 6. `GET /api/calendar/month` — 4-week window (-1 week through +2 weeks).
 7. Client-side: render today overlay + 4-week grid.
 **Google Calendar CalDAV:** URL format is `https://apidata.googleusercontent.com/caldav/v2/{calendarId}/events`, auth via basic auth with Gmail address + app-specific password. Note this in admin form help text.
 **End state:** Dashboard shows real events from all configured CalDAV sources, color-coded.
 ---
 ### Phase 6 — Photo Service
 **Goal:** Immich API integration, image proxying, binary streaming.
 **Go concepts introduced:** Interfaces (for future extensibility), `io.Reader`/`io.Writer` streaming, `image` package.
 **Steps:**
 1. Define `PhotoSource` interface (even with only Immich, this keeps the door open for adding sources later without refactoring):
   ```go
   type PhotoSource interface {
       ListPhotos(ctx context.Context) ([]PhotoMeta, error)
       FetchPhoto(ctx context.Context, id string) (io.ReadCloser, string, error)
       SourceURL(id string) string
   }
   ```
 2. `ImmichSource` (`immich.go`):
   - List: `GET /api/assets` or `GET /api/albums/{id}`, `x-api-key` header.
   - Fetch: `GET /api/assets/{id}/original` — stream body directly, don't buffer.
   - Source URL: `{base_url}/photos/{id}`
 3. `Manager` (`manager.go`):
   - On init/config change: `ListPhotos()`, shuffle, store list.
   - Track `currentIndex` (use `sync/atomic`).
   - `ServeImage(w, r, index)` — fetch, resize to ≤2560px height, stream response.
   - Background goroutine refreshes photo list every 5 min.
 4. Image resize: `go get github.com/disintegration/imaging`. Decode → resize → JPEG encode → write. Cache current + next resized images in memory (~10-20 MB for two 1440p JPEGs).
 5. API endpoints: `/photo/current`, `/photo/next`, `/photo/image/{index}`.
 6. Client-side: crossfade, preload, QR code via `qrcode-generator`.
 **Streaming vs buffering:** For proxying without resize, stream directly via `io.Copy(w, reader)`. For resize, you must buffer (decode `image.Image`, resize, re-encode). Cache the resized result to avoid reprocessing.
 **End state:** Photos cycle from Immich with smooth crossfade and QR code linking to the photo in the Immich web UI.
 ---
 ### Phase 7 — Theming + Polish
 **Steps:**
 1. CSS custom properties in `dashboard.css` for all colors, fonts, spacing, overlay positions.
 2. Theme CSS files override variables. Active theme loaded via `<link>` tag, swapped by JS.
 3. Admin: theme upload + dropdown selector.
 4. Clock overlay: `setInterval(1000)`, format via `Intl.DateTimeFormat` with configured timezone.
 5. Error indicator: 3 consecutive fetch failures → show "offline" badge. Auto-clear on recovery.
 6. Stagger all polling start times so no two intervals fire in the same second.
 7. Graceful shutdown: `signal.NotifyContext(ctx, syscall.SIGTERM, syscall.SIGINT)` + `server.Shutdown(ctx)`.
 8. HTTP server timeouts: `ReadTimeout`, `WriteTimeout`, `IdleTimeout`.
 ---
 ### Phase 8 — Deployment
 1. Multi-stage Dockerfile: build in `golang:1.24-alpine`, run in `alpine:3.21`.
 2. `docker-compose.yml`: `shared` network, port 8080, volume for `data/`.
 3. nginx on hantim:
   ```nginx
   location /dashboard {
       proxy_pass http://thekims-dashboard:8080;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
   }
   location /dashboard/admin {
       auth_basic "Dashboard Admin";
       auth_basic_user_file /etc/nginx/htpasswd.dashboard;
       proxy_pass http://thekims-dashboard:8080;
   }
   ```
 4. SSL via existing certbot.
 5. Raspberry Pi autostart:
   ```bash
   unclutter -idle 0 &
   xset s off && xset -dpms
   firefox-esr --kiosk https://thekims.family/dashboard
   ```
 ---
 ## Recommended Libraries
 | Purpose | Library | Notes |
 |---|---|---|
 | HTTP routing | stdlib `net/http` (Go 1.22+) | New pattern matching makes third-party routers unnecessary here. |
 | CalDAV | `github.com/emersion/go-webdav` | Maintained, clean, handles REPORT. |
 | Image resize | `github.com/disintegration/imaging` | Simple API, pure Go. |
 | JSON | stdlib `encoding/json` | Sufficient at this scale. |
 | Logging | stdlib `log/slog` (Go 1.21+) | Structured logging, built-in. |
 Avoid `gin`, `echo`, `fiber`, `gorm`, or any heavy framework. The stdlib is more capable than you'd expect coming from other ecosystems.
 ---
 ## Open Questions
 - **Photo cropping:** Landscape on portrait = heavy crop (`object-fit: cover`) or letterbox (`contain`). Recommend `cover` + `object-position: center` as default, configurable per-theme.
 - **Multi-day calendar events:** v1 lists them in each day cell. Spanning banners (like DAKboard) are complex layout — defer to a later enhancement.
 - **Credential storage:** Plaintext in `config.json`. Acceptable for single-user dashboard behind basic auth. Bitwarden Secrets Manager integration possible later.
@@ -0,0 +1,27 @@
 #!/usr/bin/env bash
 set -euo pipefail
 BUCKET="$(basename "$(cd "$(dirname "$0")" && pwd)")"
 ENDPOINT="https://s3.hantim.net"
 LOCAL_DIR="static/media"
 usage() {
  echo "usage: $0 <pull|push>"
  echo "  pull  download media from garage to $LOCAL_DIR/"
  echo "  push  upload media from $LOCAL_DIR/ to garage"
  exit 1
 }
 [[ $# -eq 1 ]] || usage
 case "$1" in
  pull)
    aws --endpoint-url "$ENDPOINT" s3 sync "s3://$BUCKET/" "$LOCAL_DIR/"
    ;;
  push)
    aws --endpoint-url "$ENDPOINT" s3 sync "$LOCAL_DIR/" "s3://$BUCKET/"
    ;;
  *)
    usage
    ;;
 esac