ds-galo/openspec/changes/rename-shared-album-to-galo/design.md

Design

Context

See proposal.md - Why. Current state that shapes the approach:

• The Go module is shared-album (backend/go.mod:1), imported as shared-album/internal/* by ~63 files and as assets "shared-album" by 9 of them (module-root backend package holding go:embed).
• The name also appears in the binary target (Makefile), the systemd unit and its /opt/shared-album paths, the nginx upstream, the frontend package name, and the docs.
• The real deployment .env already uses PG_DATABASE=galo and S3_BUCKET=galo-data; only the code/sample defaults are stale.
• Generated artifacts (bin/, frontend/build/, frontend/.svelte-kit/) are gitignored and pick up the new name from the build.
• No user-facing string literal carries the old name: the UI already renders "Galo".

Goals / Non-Goals

Goals:

• One consistent name galo across Go module, build target, deploy unit, config defaults, frontend package, and docs.
• Preserve behavior except the intended DB-name default.
• Keep the change verifiable by the existing build/test/validate commands.

Non-Goals:

• Renaming the immutable archived change openspec/changes/archive/2026-10-10-shared-album.
• Migrating existing database contents (the default is config-driven; live .env is already galo).
• Any UI/branding change (already "Galo").

Decisions

D1. Rename the Go module to galo

Flat path, matching the current style (module shared-album, no domain). Alternatives: keep the module name (rejected - stays inconsistent) or adopt a namespaced path like github.com/.../galo (rejected - no hosting/import need, larger churn).

Impact: replace shared-album in backend/go.mod and every import/alias across the backend, then rely on the compiler (go build ./...) to prove completeness.

D2. Change the metadata DB-name default to galo

Update config.go default and .env.example. Rationale: aligns the code with the live .env (PG_DATABASE=galo). Alternative: leave the default (rejected - keeps the stale name). Trade-off: installs that omit PG_DATABASE will now target galo; deployments should set it explicitly.

D3. Rename the deploy unit and install path

deploy/shared-album.service -> galo.service, /opt/shared-album -> /opt/galo, and the nginx upstream shared_album -> galo. This is an operational change requiring re-install on the server; it stays a single unit with the same flags and EnvironmentFile.

D4. Leave history intact

The archived OpenSpec change keeps its original name - it records what happened, not what the project is called now.

D5. Frontend package rename

shared-album-frontend -> galo-frontend in package.json; regenerate package-lock.json via install so the lock name matches.

Risks / Trade-offs

• [Missed or mistyped import path] -> Compiler-enforced; do the module/import replacement first, then go build ./... && go test ./....
• [Deploy breaks on path/unit rename] -> Treat as a documented migration step: stage /opt/galo, re-install the unit, disable the old one; keep .env authoritative.
• [DB-name default surprises a fresh install] -> .env.example and docs state it; recommend keeping PG_DATABASE explicit in every .env.
• [Lockfile drift after package rename] -> Regenerate the lock rather than hand-editing only its name fields.

Migration Plan

1. Land the rename in one commit: backend module + imports, Makefile, config.go/.env.example, deploy/*, frontend package, docs.
2. Verify: cd backend && go build ./... && go test ./..., make build, openspec validate rename-shared-album-to-galo.
3. On the server: create /opt/galo, place galo binary and .env, install galo.service, systemctl disable --now shared-album, then enable --now galo.
4. Rollback: revert the commit and re-enable the old unit; no data migration is involved.