Files

Kyle Isom 2185bbe563 Add passwd command, fix template rendering, update deployment docs

- Add `passwd` CLI command to reset user passwords
- Fix web UI templates: parse each page template with layout so blocks
  render correctly (was outputting empty pages)
- Add login error logging for debugging auth failures
- Update README with deploy workflow and container management commands
- Update RUNBOOK for Docker-on-deimos deployment (replaces systemd refs)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-25 08:27:31 -07:00

5.5 KiB

Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

eng-pad-server is a Go service that receives engineering notebook data from the eng-pad Android app via gRPC, stores it in SQLite, and serves read-only views through a web UI. It supports password + FIDO2/U2F authentication and shareable links.

Build Commands

make all                  # vet → lint → test → build
make eng-pad-server       # build binary with version injection
make build                # compile all packages
make test                 # run tests
make vet                  # go vet
make lint                 # golangci-lint
make proto                # regenerate gRPC code
make proto-lint           # buf lint + breaking changes
make clean                # remove binary

# Run a single test:
go test -run TestFunctionName ./internal/...

Architecture

Go 1.25+, pure-Go dependencies, CGO_ENABLED=0
gRPC API: receives notebook sync from the Android app (password auth per-request over TLS)
REST API: JSON over HTTPS for web viewing, auth endpoints
Web UI: Go html/template + htmx, SVG page rendering
SQLite: via modernc.org/sqlite, WAL mode, foreign keys
Auth: Argon2id passwords + FIDO2/U2F via go-webauthn/webauthn
Router: chi (lightweight, stdlib-compatible)

Project Documents

ARCHITECTURE.md — full system specification
PROJECT_PLAN.md — implementation steps with checkboxes
PROGRESS.md — completion tracking and decisions

Keep PROJECT_PLAN.md and PROGRESS.md in sync.

Source Tree

eng-pad-server/
├── cmd/
│   └── eng-pad-server/              CLI entry point (cobra)
│       ├── main.go
│       ├── server.go                server subcommand
│       ├── init.go                  init subcommand
│       └── passwd.go               password reset subcommand
├── internal/
│   ├── auth/
│   │   ├── argon2.go                Password hashing
│   │   ├── tokens.go                Bearer token generation/validation
│   │   └── webauthn.go              FIDO2/U2F integration
│   ├── config/
│   │   └── config.go                TOML configuration
│   ├── db/
│   │   ├── db.go                    Database setup, pragmas
│   │   └── migrations.go            Schema migrations
│   ├── grpcserver/
│   │   ├── server.go                gRPC server setup
│   │   ├── sync.go                  SyncNotebook handler
│   │   ├── share.go                 Share link RPCs
│   │   └── interceptors.go          Auth interceptor
│   ├── server/
│   │   ├── server.go                REST server setup
│   │   ├── routes.go                Route registration
│   │   ├── auth.go                  Login/register endpoints
│   │   ├── notebooks.go             Notebook/page endpoints
│   │   └── middleware.go            Auth middleware
│   ├── render/
│   │   ├── svg.go                   Page → SVG rendering
│   │   ├── jpg.go                   Page → JPG rendering
│   │   └── pdf.go                   Notebook → PDF rendering
│   ├── share/
│   │   └── share.go                 Share link token management
│   └── webserver/
│       ├── server.go                Web UI server setup
│       ├── routes.go                Template routes
│       └── handlers.go              htmx handlers
├── proto/engpad/
│   └── v1/
│       └── sync.proto               gRPC service definition
├── gen/engpad/
│   └── v1/                          Generated Go gRPC code
├── web/
│   ├── embed.go                     //go:embed directive
│   ├── templates/
│   │   ├── layout.html              Shared HTML skeleton
│   │   ├── login.html               Login page
│   │   ├── notebooks.html           Notebook list
│   │   ├── notebook.html            Single notebook view
│   │   └── page.html                Page viewer (SVG embed)
│   └── static/
│       └── htmx.min.js
├── deploy/
│   ├── docker/
│   │   └── docker-compose.yml
│   ├── systemd/
│   │   ├── eng-pad-server.service
│   │   └── eng-pad-server-backup.timer
│   ├── scripts/
│   │   └── install.sh
│   └── examples/
│       └── eng-pad-server.toml
├── Dockerfile
├── Makefile
├── buf.yaml
├── .golangci.yaml
├── .gitignore
├── CLAUDE.md                        This file
├── README.md
├── ARCHITECTURE.md                  Full system spec
├── PROJECT_PLAN.md                  Implementation steps
└── PROGRESS.md                      Completion tracking

Key Conventions

Stroke point data: packed little-endian floats [x0,y0,x1,y1,...] — same binary format as the Android app
Canonical coordinates: 300 DPI. Scaled to 72 DPI for SVG/PDF output (×0.24)
Page sizes: REGULAR (2550×3300 pts), LARGE (3300×5100 pts)
Stroke styles: "plain", "dashed", "arrow", "double_arrow"
No grid rendering — grid is a tablet writing aid only
Share link tokens: 32-byte crypto/rand, URL-safe base64
gRPC auth: username+password in metadata, verified per-request
Web auth: password login → bearer token in session cookie
TLS 1.3 minimum, no exceptions

5.5 KiB Raw Permalink Blame History Unescape Escape