Kyle Isom
0cce04b5b8
- README.md: project overview, quick start, build commands - CLAUDE.md: AI dev context, source tree, key conventions - ARCHITECTURE.md: full system spec covering data model, auth (password + FIDO2/U2F), gRPC sync API, REST API, SVG/JPG/PDF rendering, web UI, configuration, deployment, security - PROJECT_PLAN.md: 11 phases with discrete checkboxable steps - PROGRESS.md: decision log and completion tracking Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
132 lines
5.5 KiB
Markdown
132 lines
5.5 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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
|