sudoku-solver

Solves Sudoku puzzles

Configure

Configure via environment variables:

Variable	Description	Default
PORT	HTTP listening port	8080
LOG_LEVEL	Log level (debug, info, warn, error)	info
LOG_FILE	Log path (set to "" to turn off)	sudoku-solver.log

CLI flags:

Flag	Description
-q, --quiet	Disable logging to stderr

Run with Podman / Docker

Pull and run the pre-built image:

podman compose up -d

Contributing

Setup

Install the following before contributing:

Dependency	Install	Purpose
Go 1.23+	brew install go	Build and test
Podman	brew install podman	Container builds and runs
golangci-lint	brew install golangci-lint	Go linting
vale	brew install vale && vale sync	Markdown prose linting
markdownlint-cli2	brew install markdownlint-cli2	Markdown formatting and linting
Tesseract	brew install tesseract	OCR digit recognition

Build

Build the CLI binary:

export CGO_CPPFLAGS="-I$(brew --prefix leptonica)/include -I$(brew --prefix tesseract)/include"
export CGO_LDFLAGS="-L$(brew --prefix leptonica)/lib -L$(brew --prefix tesseract)/lib -lleptonica -ltesseract"
go build -o sudoku-solver ./cmd/sudoku-solver

Build and run the Docker image:

podman compose -f docker-compose.build.yaml up -d --build

Lint

golangci-lint run ./...
vale *.md
markdownlint-cli2 "**/*.md"
markdownlint-cli2 --fix "**/*.md"

Test

go test ./...

Logging

• Logging uses the OpenTelemetry Logs SDK directly
• By default, logs are written to both stderr and sudoku-solver.log
• Use -q / --quiet to turn off stderr output
• Set LOG_FILE="" to turn off file logging

Purpose

• To test / validate user experience of cutting edge AI dev tools, hopefully on mobile, without having to sit at my desk, or use a computer
• To understand the code, in a way that I can follow, learn from, and repeat myself manually when playing without running this app
• To learn and practice current best practices, especially around observability

Inputs

• Screenshot of an unsolved Sudoku puzzle

Outputs

• Image of the solved Sudoku puzzle