Skip to content

Development

How krites is designed and built.

Where the design records live

The numbered specs live in the project wiki, not in this repository. A spec is a point-in-time decision record — written once, true of a moment, read later for its conclusions. Keeping them beside the documentation buried the documentation, so they moved.

The specs index lists them with their current status.

The specs are not the documentation. If something is only explained by a spec reference, it is not explained. The reasoning belongs in Explanation, in its own words, and the facts belong in Reference.

Settled design decisions

These are closed questions, not preferences under discussion.

Area Decision
Target hardware Apple Silicon Mac first (macOS / arm64); Linux for CI and headless use; no Windows build — the ONNX loader uses POSIX-only symbols
ML runtime ONNX Runtime for every model (face/eye, aesthetic, inpaint), with CoreML on Apple Silicon; pure Go for the deterministic maths; no Python
Cloud Local by default. Cloud is a first-class, user-choosable backend per capability, off until chosen, with disclosure before egress
Studio stack A Svelte single-page app over a Go JSON + SSE API, served in the browser
RAW Cull, preview and export all run on the embedded JPEG preview. krites does not decode RAW sensor data
Lightroom Finish-in-Lightroom is the primary workflow. XMP carries the verdict, the crop and the straighten angle — not the look, and not object removals

The reasoning behind the provider decisions is in Why the heavy providers are opt-in; the full boundary list is in What krites does not do.

The roadmap, and what "ahead" means

  1. Phase 1 — cull: ingest → blur / exposure / eye / dedup → studio review → export keepers, with XMP. Shipped.
  2. Phase 2 — develop: auto-straighten, composition crop, looks. Shipped, except that the look catalog has only its seed entry.
  3. Phase 3 — object removal: inpainting via the studio. Shipped, opt-in behind a licence gate.
  4. Phase 4 — learns your taste: adapt the cull to your keep/reject history. Not started, and not scheduled.

Phase 4 has no release date. Its design is a draft and is deliberately parked pending real usage — building a learner before there is a body of real decisions to learn from would be guessing. What exists today is the substrate: every cull records the machine's proposal alongside the human's final verdict, with the signals behind both.

Ways of working

krites follows the phpboyscout toolchain conventions: spec-first, TDD and BDD (Godog for user-facing commands, unit tests for the deterministic core), docs alongside the code, and a non-destructive guarantee pinned by tests.

The deterministic engine is held to compiling for GOOS=js GOARCH=wasm as a build target, which is what stops a verdict quietly acquiring a native dependency. See Components.

CLAUDE.md in the repository carries the full working agreement.

UI mockup

A clickable, non-functional prototype of the studio (mock data, no backend) that validated the interface before it was built:

  • Studio UI mockup — the shoot library and the cull-review grid plus loupe. The mockups README covers what it demonstrates and how to drive it (keyboard P / X / U / 1–5, filters, burst compare, cull progress, export and XMP).