biggus-dickus/docs/VISION.md

Vision — Collection Management System (working name TBD)

Codename note: the repository folder is a throwaway working name. The real product name is undecided and must never appear in code (see the architecture spec, "Naming"). This document uses neutral terms — "the platform", "the system".

What this is

A modern collection management system (Swedish: samlingsförvaltningssystem) for museums and other heritage organizations: software for documenting, managing, and selectively publishing the objects in a collection. It is built around the Spectrum 5.0 standard (Collections Trust) and the guidance from Riksantikvarieämbetet — see reference/ for the source material this design is grounded in.

It is not primarily a web-publishing tool or a digital-asset manager. Its job is to support the internal processes of collection management — cataloguing, location/movement control, loans, condition, and so on — with selective public access layered on top.

Who it is for

• Primary (now): small and mid-sized non-profit heritage organizations — limited budget, limited or volunteer IT, who need something easy but correct.
• Roadmap: larger institutions with professional staff and IT, who need the full Spectrum process coverage, custom fields, and the option to run it in their own environment.

The design tension we hold throughout: easy by default, flexible when needed. A small org runs with a tiny subset and sensible defaults; an advanced org enables the full standard, adds custom fields, and self-hosts.

Guiding principles

1. Small, well-tested, extensible core. The accountability backbone is small and strongly typed; extensibility lives in well-bounded modules around it.
2. Make illegal states unrepresentable. Lean on Rust's type system to remove bug classes (newtype IDs, validated value objects, projection types, auth via extractors). Strong types also shrink the test surface.
3. Isolation by construction. An organization's data must never bleed into another's. We achieve this at the deployment/credential layer, not by app discipline (see architecture spec).
4. Easy to self-host. The single-tenant binary is the self-host artifact: one binary, minimal external dependencies, sensible defaults, local-disk storage option, standalone auth.
5. Standards-aligned. Spectrum 5.0 for process/data; CIDOC-CRM / LIDO and controlled vocabularies (Getty, KulturNav, Wikidata) on the roadmap for interchange.
6. Minimal custom code, reversible bets. Prefer existing crates. Pre-1.0 we choose dependencies on fit, not maturity, and isolate experimental ones behind our own traits so swapping stays cheap.
7. Clean public/private separation. The public, unauthenticated surface is a distinct, narrow boundary — which makes publishing, caching, rate-limiting, and network lockdown all clean.

Architecture in one paragraph

The application binary is always single-tenant — one running instance serves exactly one organization and knows nothing of any other. "Multi-tenancy" is purely a deployment concern: a hosted fleet runs many copies of the same binary, each with its own Postgres database and Meilisearch index (scoped credentials) against shared database/search servers, each on its own domain, independently rolled out. Self-hosting is the same binary with one database. Data isolation is therefore guaranteed by credentials and topology, not by org_id filtering in code. See specs/2026-06-02-mvp-architecture.md.

---

Feature catalogue

Each feature is tagged [MVP], [Post-MVP], or [Later]. The MVP cut is the smallest build that is genuinely useful and exercises every architectural pillar, so nothing structural is discovered late.

Catalogue core

• [MVP] Catalogue records for objects and groups of objects, with a typed inventory minimum (object number, name, count, brief description, current location, current owner, recorder, recording date).
• [MVP] Hybrid flexible fields — a field-definition registry + JSONB value layer, seeded with the Spectrum 5.0 Cataloguing field set; orgs enable a subset or the whole set without schema changes.
• [MVP] Object numbering with a configurable standard format; multiple historical numbers per object.
• [Post-MVP] Org-defined custom fields beyond Spectrum (the registry already supports it; this is the management UI + validation polish).
• [Post-MVP] Object groups / hierarchical relationships, related-object links.
• [Later] Subject-specialist templates / external cataloguing standards.

Controlled vocabularies & authority records

• [MVP] Authority records for person, organization, place — store once, link many — referenced from core and flexible fields.
• [MVP] Controlled vocabularies (term sources) for fields like material, object name, technique; fields bound to a vocabulary accept only resolved terms.
• [MVP] Multilingual labels on terms and authorities (sv/en) in the data model.
• [Post-MVP] Import/sync from external vocabularies — Getty AAT/TGN/ULAN, KulturNav, Wikidata; storing external URIs on local terms.
• [Later] Linked-open-data publishing of authorities.

Media & files

• [MVP] Upload and attach images/documents to records via OpenDAL (S3 or local disk), behind a BlobStore trait.
• [Post-MVP] Thumbnails / derivative generation; per-reproduction licensing; multiple reproductions per object.
• [Later] IIIF image serving; bulk/mass ingest pipelines; dedicated image-management (DAM-style) workflows.

Search

• [MVP] Meilisearch indexing of records; basic faceted/full-text search in the admin UI.
• [Post-MVP] Saved searches, advanced filters, sort presets, search across all fields incl. flexible fields.
• [Later] Public-facing search on the published catalogue.

Audit & history

• [MVP] Append-only, immutable audit log — who/when/what with field-level before→after diffs — covering domain writes and auth/security events; surfaced as Spectrum amendment history on records.
• [Post-MVP] Auditing of sensitive reads; audit export/reporting; retention policy controls.

Publishing & public access

• [MVP] Record-level visibility (draft / internal / public) with a fixed set of never-public fields (location, valuation, insurance, personal data).
• [MVP] Public read API (OpenAPI) serving only public records, only public-safe fields (a typed PublicView projection).
• [Post-MVP] Per-field publishability flags; public collection landing pages / embeddable widgets.
• [Later] Aggregator interoperability — LIDO export, OAI-PMH harvest, feeds to K-samsök/Kringla, Europeana, Sveriges dataportal; Wikidata/ Wikimedia publishing.

Authentication & access control

• [MVP] Email/password and external OIDC login, scoped to the single org the instance serves; role/permission model enforced via typed extractors.
• [Post-MVP] Granular per-field / per-process permissions; API tokens for integrations.
• [Later] Shared identity provider + cross-org membership and fast switching (deferred by decision; revisit if multi-org usage grows).

Import / export / portability

• [MVP] Portable export: a single SQLite file (metadata incl. flattened flexible fields + vocab/authority tables) + plain media files + a manifest — a whole-org archive, openable anywhere.
• [Post-MVP] Import from Excel/CSV (the common "we have a spreadsheet" path) and from another instance's export.
• [Post-MVP] Migration tooling from legacy systems.

Reporting & output

• [Post-MVP] Templated outputs: exhibition labels, loan letters, condition reports, inventory lists; user-defined templates.
• [Later] Statistics/dashboards (records per year, % with images, etc.).

Spectrum procedure coverage

The MVP implements Cataloguing. The other Spectrum 5.0 procedures are the functional roadmap:

• [Post-MVP] Primary procedures: Object entry, Acquisition & accessioning, Location & movement control, Inventory, Loans in, Loans out, Object exit, Documentation planning.
• [Later] Secondary procedures: Rights management, Reproduction, Condition checking & technical assessment, Conservation & collections care, Valuation, Insurance & indemnity, Use of collections (incl. exhibitions), Emergency/disaster planning, Damage & loss, Deaccession & disposal, Collections review, Audit.

Internationalization

• [MVP] UI localization (Swedish + English); localized API validation/error messages; multilingual vocab/authority labels; data model carries language-tagged content values.
• [Post-MVP] Translation workflow/UI for per-field record content; additional UI locales.

Hosting, fleet & operations

• [MVP] Runs as a single instance (self-host or one hosted cell); local-disk or S3 storage; per-instance migrations on startup.
• [Post-MVP] Per-org provisioning control plane (create DB + role + Meili key + deployment + domain); batched/canary rollouts; A/B routing.
• [Post-MVP] Optional Redis (cache/sessions/rate-limit) with per-org key prefixing, added only when a real bottleneck appears.
• [Post-MVP] In-app IP-allowlist middleware as a portable fallback for self-hosters without ingress-level controls.
• [Later] Multi-Postgres sharding for large fleets; per-org Redis instances.

---

Explicitly deferred decisions (recorded so they aren't relitigated)

• Multi-org user switching / shared IdP — rare case; deferred until it demonstrably hurts.
• Database migrations machinery — not until 1.0. Pre-1.0 the data model is reshaped freely (recreate, don't migrate).
• Final product name — TBD; never hardcoded.
• Hosting/ops documentation — later, but the design keeps self-host easy throughout.