Skip to content

Geo cover service

Purpose

The geocover domain (backend/internal/services/geocover/) lets members offer a photo for an area (a country, region or city) or for a single place. Every cover has one small camera button in its top-right corner: with no photo it opens the suggest sheet, with one it opens a menu to suggest a photo or report the current one (see Report service). A place detail without a photo shows a placeholder cover with an "Add the first photo" caption. A submission waits in a Backstage review queue and nothing publishes until a Tomoda account approves it (see Backstage service).

Aggregates

Aggregate Table Holds
Submission geo_cover_submissions The target (kind + place_key: a country code, or a region, city or place (kind place) id), its name at submission time, the submitter, the photo key, the rights confirmation time, the status (pending, approved, rejected, withdrawn), the reviewer's decision, the favourite flag, and the photo's content hash and perceptual hash

Covers live on countries, regions and locations (cover_image_key, cover_author, cover_license, cover_source_url); the catalog loader writes them too. Enums (GeoCoverKind, GeoCoverTarget, GeoCoverStatus) are in backend/internal/models/geocover.go.

HTTP endpoints

Member routes need a JWT. Submissions share ReportLimit with report filing; the upload starter has its own GeoCoverUploadLimit (10 per hour per account).

Method Path Description
POST /uploads/geo-cover {content_type} (jpeg or png): presigned PUT URL and key
GET /geo-covers/moments?kind=&key= The caller's own live moments at the target, newest first (up to 30). A place matches moments tagged to exactly that place
GET /geo-covers/photos?kind=&key= The target's approved photo set, the cover first, each anonymous
GET /geo-covers/mine?kind=&key= The caller's own submissions for the target and their status
POST /geo-covers/submissions {kind, key, upload_key \| moment_id, rights_confirmed}: queue a photo. 201
POST /geo-covers/submissions/{id}/withdraw The submitter pulls their own approved photo. 204

Refusals: 400 unless exactly one of upload_key and moment_id is sent, rights_confirmed is true, the upload exists under the caller's key, or the moment is the caller's own at that place; 404 for an unknown target; ALREADY_SUBMITTED (409) while the caller's earlier photo for the place is still pending, or when the same staged upload already backs a submission (a unique index on asset_key for uploads, so approving one can't delete the staged file another still needs).

Review

  • Queue. Oldest first per status, filterable by target (area or place), with the submitter, the staged photo, the target and the number of open reports on it. Each item says whether it is an area or a place.
  • Checks. The detail of a pending submission carries signals for the reviewer: the photo's EXIF position against the target (near, far, missing or unknown, with the distance and the limit for the kind: 1 km for a place, 50 km for a city, 500 km for a region, 3000 km for a country), and other live submissions with the identical file (any target) or a near-identical picture (same target, perceptual hash within 6 bits). Hashes are computed at submission and filled in on first view. Nothing is rejected automatically; the reviewer also rejects photos where people are the subject. The checks live in checks.go, with hashing and EXIF parsing in platform/geocover.
  • Approve. A submission made from a moment first re-checks the moment is still one of the submitter's live photos at the place; if not it returns 422 and can only be rejected. Reads the staged photo through a signed URL, decodes a JPEG or PNG, scales it to at most 1600 px wide and re-encodes it as a JPEG without metadata (platform/geocover), uploads it to geo-covers/<kind>/<key>-<sha256[:12]>.jpg, then in one transaction closes the submission and reconciles the target's cover (below). The approved row stays as part of the target's photo set. Every member photo is anonymous: the cover stores no author, so no attribution line shows, and never the submitter's name; the license Tomoda member license only marks it as a member photo. A replaced object is deleted unless a cover or an approved submission still references it. A photo that can't be decoded returns 422 and the submission can only be rejected.
  • Reject. Closes the submission; the member can submit again.
  • Photo set and cover. Every approved photo stays as the target's set. The cover is the favourite a moderator picked (POST /backstage/geo-covers/{id}/favourite), else the most recent approved photo. For an area an approval or a favourite pick replaces the existing cover. For a place a curated cover (any cover whose license is not the member license) always outranks member photos, so a member photo only becomes the place's cover when it has none; either way the place cover falls back to the provider thumbnail when no photo is left. The place detail and cards read the cover through the location's cover_image_key, so ranking is decided once, here.
  • Withdrawal. The submitter can withdraw their own approved photo: it leaves the set, stops being the favourite and the cover falls back to the next best photo.
  • Cover removal. Clearing a reported cover also takes the approved photo behind it out of the set, then the next best approved photo takes over.
  • Staged photos. An uploaded photo is deleted once the submission is decided. A submission made from a moment points at the moment's own photo, which is never deleted.
  • Shared storage rules. The catalog loader and the approve path use platform/geocover for hashed keys, rehosting and the replaced-object guard, so the two cannot drift.

Data lifecycle

  • A member's submissions go with their account, and the data export includes them (geo_cover_submissions section, geocover.NewExporter).
  • A decided submission keeps its reviewer until that account is removed.

Dependencies (deps.go)

Port Satisfied by Used for
Objects object store Reading staged photos, writing and deleting covers
Assets platform/assets.Service Verifying an upload, composing display URLs
Reports report.Store Open reports on a place
AuditLogger platform/audit.Service Submission audit rows

Where to look

Need File
Submit, review, approve service.go
Submissions and cover columns store.go, geocoverdb/queries.sql
Image and key rules backend/internal/platform/geocover/
Member screens frontend/components/geocover/