eng-pad-server/CLAUDE.md

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
├── 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