postcard/PROPOSAL.md

# Proposal: `postcard` — turn a phone photo into a sendable postcard

**Status:** proposed, not built. Self-contained — written so a fresh
agent with no prior conversation context can pick this up and implement
it without anything explained first. No repo exists yet; this file is
the seed of one.

## Motivation

Upload a photo from your phone (or any device), it gets composited onto
a vintage postcard template — border, stamp corner, a handwritten-style
caption — and you get a shareable link or a downloadable image. The
caption is auto-drafted from whatever context is available for that
day (git activity, what was playing, a note title) so the postcard reads
like it was actually written *from* that day, not just a filter applied
to a photo.

Structurally this is `latent`'s upload → transform → deliver shape, with
the transform swapped from film-emulation filters to postcard
compositing, and one addition: a short generated caption line instead of
(or alongside) canvas filters. Reuse `latent`'s validated pieces
wholesale rather than re-deriving them — same phone-upload flow, same
blob+SQLite+TTL server, same no-accounts/link-is-the-credential model.

## Architecture

Static/client-heavy frontend (canvas compositing, same "no build step"
family as `latent`/`typo`/`flit`/`wisp`) plus a small single-process
server, copied from `latent/server` almost unchanged: `db.js` (SQLite
metadata), `ids.js` (opaque random IDs), `cleanup.js` (interval TTL
sweep), `ratelimit.js` (basic IP throttle on upload), `routes.js`,
`index.js`. No accounts, no auth — the link is the credential, same as
`latent`/`wisp`.

### Editing (client-side, `<canvas>`)

1. **Upload** — `<input type="file" capture>` for direct camera access,
   normal file picker as fallback (same open question `latent` already
   flagged, same answer: ship both).
2. **Template** — a handful of postcard border/stamp-corner presets
   (plain cream border, torn-edge, faded color-photo-era border) — pick
   a vibe, not a full editor. Reuse `latent`'s "presets, not sliders"
   call for the same reason: faster to ship, more toy than tool.
3. **Caption** — an editable text field, pre-filled by a generated draft
   (see below), rendered onto the card in a handwriting-style webfont.
   Editable because auto-drafted text should be a starting point, not
   the final word — the person sending it should be able to make it
   actually theirs.
4. **Postmark/stamp corner** — today's date and a small generated
   "location" stamp if EXIF GPS is present (round-tripped through the
   same reverse-geocoding approach `rewind`/`galr` already use, if one
   exists — otherwise just the date, no invented location).
5. Compositing is canvas-based, non-destructive within the session
   (recompute from the original photo + a param object, matching
   `latent`'s pattern) so switching templates doesn't require
   re-uploading.

### Caption generation

The interesting new piece `latent` didn't need. Draft a one-line caption
from whatever of these is available and non-empty for the photo's
date (EXIF date if present, else upload date):

- Git activity that day (via the same Gitea-API aggregate-count approach
  `rewind` already built — "spent the day untangling a deploy script" /
  "quiet one, no commits")
- What was playing (Spotify plays log, same source `/wrapped`/`/now`
  already read — "[artist] on repeat")
- A note/blog title from that date, if one exists

This is explicitly a **remix of existing fragments**, not a generative
free-text model call — same spirit as the haiku/found-poetry idea
below: assemble from real fragments of that day, phrase them into one
short sentence with a small set of template shapes ("Spent the day
{git_fragment}. {spotify_fragment} the whole time." /
"{spotify_fragment}. {git_fragment}, mostly."), and always leave it
editable. If none of the three sources have data for that date, fall
back to a small set of generic postcard-voice lines ("Wish you were
here. Mostly wasn't.") rather than leaving the field empty.

### Finishing paths

Same two-path split as `latent`:

1. **Instant** — composite, then download directly, entirely
   client-side, no server touched. Optional "generate share link"
   (explicit action, not automatic).
2. **Send** — uploads the composited image to server storage, returns a
   link. No delayed-reveal mechanic here (that's `latent`'s gimmick, not
   this one) — the postcard metaphor's own delay is real mail taking a
   few days to arrive, which the link doesn't need to fake.

### Server

Copied from `latent/server`'s shape almost directly:

**Table `postcards`:**

| column | type | notes |
|---|---|---|
| `id` | text PK | random opaque ID, used in the URL |
| `blob_path` | text | composited image on disk |
| `mime` | text | |
| `created_at` | integer | |
| `expires_at` | integer | TTL sweep target, same as `latent` |

**Endpoints:**

- `POST /api/upload` — body: composited image bytes. Returns `{ id, url }`.
- `GET /p/:id` — serves the postcard image directly (no develop-later
  gate — this app's whole point is immediacy, unlike `latent`).
- TTL sweep, same interval-based pattern as `latent`/`wisp`.

No auth. Rate-limit `/api/upload` the same way `latent` does.

## Non-goals

- No accounts, no "your postcards" history — every card stands alone via
  its own link, same throwaway philosophy as `latent`/`wisp`.
- No delayed-reveal mechanic — that's `latent`'s gimmick; this one's
  point is speed, not anticipation.
- No free-text LLM-generated captions — template-and-fragment assembly
  from real personal data only, kept editable, never presented as if the
  app "wrote" it.
- No collaborative/multi-recipient cards — one photo, one card, one link.

## Open questions

- **Where the day-context lookups live** — `rewind` and `/wrapped`/`/now`
  already have working Gitea-API and Spotify-log integrations; decide
  whether `postcard`'s server calls those APIs directly (network
  dependency on goonk's API being reachable) or whether this only makes
  sense as a goonk-hosted feature rather than a fully separate sibling
  project. Worth resolving before writing `routes.js`.
- **Location stamp source** — confirm whether `galr`/`rewind` already do
  reverse geocoding anywhere reusable, or whether this ships without a
  location stamp in a first pass.
- **Handwriting webfont choice and licensing** — pick one, check its
  license allows self-hosting.
- **Image size limits** — same question `latent` flagged, same likely
  answer (downscale on upload, cap stored size).
- **Retention window** — shorter than `latent`'s, probably — a postcard
  link is meant to be opened once by the recipient, not browsed later.