Archive data model
The database connects three kinds of information: observations from scanning, application records that make those observations usable, and curated context supplied by the owner. Keeping those roles visible makes it possible to ask both “where did this come from?” and “what have we learned or decided about it?”
PostgreSQL provides the shared relational catalog. JSONB holds variable metadata such as EXIF and file-analysis results. Filename search uses trigram matching; extension availability alone does not imply that semantic image or document search is implemented. Scanner model (archive-browser/app/models/scanner/file_entry.rb), current search controller (archive-browser/app/controllers/search_controller.rb).
Observations and derived records
Scanner::FileEntry wraps the scanner-owned files table and declares ordinary model instances read-only. Rows retain paths, sizes, hashes, extension categories and available embedded metadata. Rails builds its application layer from those rows instead of placing human decisions into the scanner’s discovery output.
Directories are derived from file-path ancestors. Their parent relationships, direct counts, recursive counts and byte totals support navigation without recalculating the entire tree on each request. Projects group detected source trees and carry Git information, curation notes, status and restoration URLs. Directory population (archive-browser/lib/populators/directory_populator.rb), project model (archive-browser/app/models/project.rb).
UniqueFile groups scanner occurrences by content hash. Photos, videos, audio files and documents provide typed records with paths and metadata appropriate to their views. Those media records can reference both a scanner entry through file_entry_id and shared content through unique_file_id. Code files can remain scanner records rather than gaining a dedicated code-file model. UniqueFile (archive-browser/app/models/unique_file.rb), category controller (archive-browser/app/controllers/categories_controller.rb).
| Record or field | Meaning |
|---|---|
| Scanner occurrence | A file observed at a particular path |
| UniqueFile | Shared content identity and preservation/curation state |
| Typed media record | An occurrence prepared for a specific browsing experience |
| Project | A detected or curated source tree, optionally restored |
| Active Storage attachment | Environment-specific media bytes used for display or playback |
This is a selective relationship map, not a promise that every relationship is hash-only. Local foreign keys still matter. Dropping and rebuilding the scanner table is not inherently safe merely because some data also carries content hashes.
Analysis and human context
Content-level ai_analysis stores structured analysis evidence. Separate archive_decision, decision_source and decided_at fields record the resulting keep/skip choice and who or what made it. The decision service protects earlier human choices from automatic replacement. Decision service (archive-browser/app/services/analysis_decision.rb).
Life eras add overlapping biographical context through definitions and explicit memberships. Suggestions remain separate from accepted inclusion or exclusion. People and photo analyses add another domain: portable UUIDs identify people and face annotations, while content hashes identify analyses and connect duplicate photo occurrences. Face vectors and matching work are local processing data, not confirmed identities. Era documentation (archive-browser/docs/LIFE_ERAS.md), photo-analysis model (archive-browser/app/models/photo_analysis.rb).
Catalog state and stored bytes
Preserved originals, served derivatives and database transfer packages have distinct roles. UniqueFile retains original preservation status and URI. Photo/video attachments track the display assets generated in a particular environment. Upload-run tables record local execution history rather than becoming the portable archive identity.
The incremental sync allowlist makes this separation concrete. It transfers selected path/hash-keyed metadata and resolves media relationships on import. It omits environment-specific attachment and conversion state, allowing production to prepare its own media. Era authority and the people replacement workflow have additional ownership rules. Sync table contract (archive-browser/app/services/db_sync/tables.rb).
The operations guide explains those boundaries. The capability reference keeps dated inventory counts separate from schema: having a metadata column means the system can store a fact, not that every file already has that fact populated.
Implementation notes refer to repository sources reviewed at e76e74c on October 13, 2026.