Cartlann — Technical Overview
What's under the hood
A detailed look at the Cartlann collection management system — its object model, accession process, location hierarchy, condition and conservation records, loans, and label generation.
Object Model
A record model built for professional collections
Cartlann's object model follows the Spectrum standard — covering every field that a professional collection manager needs, without unnecessary complexity.
Descriptive Metadata
Each object carries title, object name, brief description, object type, maker attribution, date from/to with precision level (year/decade/century/circa), materials list, dimensions as structured JSON, and current condition grade.
Accession Identity
Objects carry an accession number (assigned on acquisition), a system UUID, a status field (on-loan, in-store, on-display, deaccessioned), and an is_accessioned boolean. Unaccessioned objects in the system (e.g. entries under consideration) are clearly distinguished.
Rights and Access
Rights holder and copyright status fields are standard on every object. The is_public boolean controls whether the object appears in the unauthenticated public portal. Rights data can be exported for rights clearance reporting.
Object Parts
Multi-component objects are modelled as a parent object with child ObjectPart records. Each part carries a part number, description, and its own current location — allowing components of a set to be stored or displayed separately while remaining linked to the parent record.
Configurable Numbering
Number schemes define how accession numbers are generated: format template (e.g. {INST}/{YEAR}/{SEQ:4}), institution code, prefix, sequence padding, and current sequence. Multiple schemes can be defined for different collection types or intake processes.
Search and Filter
Objects can be searched by free text across title, description, maker, and object name. Results can be filtered by status, accession state, and object type — and paginated via limit/offset for large collections.
Accession Process
Intake to record in structured steps
Cartlann models the Spectrum entry and acquisition process — separating the intake decision from the formal accession, so nothing is permanently committed until it has been properly reviewed.
Object Entries
An Object Entry records the arrival of an object before any acquisition decision is made. The entry number, entry date, reason (e.g. potential purchase, return from loan, unsolicited donation), depositor party, expected return date, and current status are all captured. Entries remain open until resolved to an acquisition or returned.
Acquisition Records
On formal acquisition, an Acquisition record is created: linked entry (if applicable), accession number from the chosen scheme, acquisition date, method (purchase, donation, bequest, transfer, found), source party, price and currency, and authorisation reference. The acquisition record is the permanent legal record of how the object entered the collection.
Number Scheme Assignment
The assignAccession API call generates and assigns the next available number from a chosen scheme atomically — preventing duplicates even under concurrent load. The format template is evaluated at generation time so numbers accurately encode the acquisition year and sequence.
Deaccession and Disposition
Objects can be formally deaccessioned by setting status to deaccessioned. The full record — including all movements, condition checks, conservation treatments, and loans — is retained for audit purposes. Nothing is deleted; the history is permanently preserved.
Location & Movement
A complete chain of custody
Cartlann's location system models your physical space to any depth, and every object movement is logged permanently — giving an unbroken chain of custody from acquisition to present day.
Hierarchical Location Tree
Locations are defined as a tree — each location has a code, name, type (building, room, bay, shelf, box, other), and an optional parent. A location at any level can hold objects. The tree can model anything from a single-room store to a multi-site institution with thousands of storage positions.
Object Movement API
Moving an object calls the /objects/{id}/move endpoint with a target location ID, reason, and optional notes. The system records the from-location, to-location, timestamp, and acting user in an ObjectMovement record. The object record's current_location_id is updated atomically.
Full Movement History
The complete movement history for any object is queryable via the movements endpoint — returning every move in chronological order with location names resolved. This history is permanent and append-only: moves cannot be deleted or backdated.
Parts Location Tracking
Each ObjectPart carries its own current_location_id, independently of the parent object. Components stored separately from the main object are individually tracked — no component is unaccounted for.
Condition & Conservation
The health of your collection, on record
Cartlann tracks the physical condition of every object over time and records every conservation treatment in full — giving curators and conservators the longitudinal data they need.
Condition Checks
Each ConditionCheck records: check date, checking person, condition grade, free-text notes, and recommended next check date. Multiple checks per object build a timeline of condition over its lifetime. The latest check is queryable directly — no need to scan the full history.
Condition Grades
The condition_grade field accepts any grading vocabulary — Good, Fair, Poor, Critical, or institution-specific schemes. Cartlann does not enforce a fixed vocabulary, allowing institutions to use their own standards while keeping grades queryable and comparable within the collection.
Conservation Treatments
ConservationTreatment records capture: treatment type, start and end dates, conservator (linked to a Party record), description of work performed, cost and currency, and outcome. Treatments are linked to the object and form a permanent treatment history that travels with the object record.
Treatment Cost Tracking
Conservation treatment costs are recorded per treatment with currency support. This enables total conservation expenditure to be calculated per object, per collection, or per time period — useful for insurance valuation, grant reporting, and resource planning.
Label Printing
Print-ready labels in seconds
Cartlann generates professional collection labels as print-ready A4 PDFs directly in the browser — no separate label software required.
Three Label Types
Labels are available in three formats: QR code (scannable with any phone camera), Code 128 barcode (for handheld scanners), or both side by side. All types encode the accession number — falling back to the object UUID for unaccessioned objects.
Three Label Sizes
Small (40×20mm, up to 52/page) for narrow barcode strips; medium (70×37mm, up to 14/page) with QR and title; large (99×57mm, up to 4/page) with full object information. All sizes are optimised for standard A4 sheet printing.
Batch Generation
Select any number of objects in the collection view and open the label printer once. Cartlann generates labels for all selected objects in a single PDF — with configurable copies per object and an institution name in the footer of each label.
In-Browser PDF
Label PDFs are generated entirely in the browser using jsPDF and bwip-js — no server-side rendering step. The PDF is downloaded directly without leaving the application.
Stack & Deployment
Modern stack, flexible deployment
Cartlann follows the same architecture and deployment model as the rest of the Ullav suite — Rust backend, Next.js frontend, Docker and Kubernetes ready.
Rust Backend
ullav-collection-server is built in Rust (Actix-web 4) with PostgreSQL for persistence. Migrations run idempotently on startup. All configuration is externalised via environment variables with *_FILE variants for Docker secrets.
Next.js Frontend
ullav-collection-browser is a Next.js 16 / React 19 / TypeScript application with Tailwind CSS. It supports English, Irish (Gaeilge), and German via next-intl. API requests go through the Next.js /api/* rewrite to avoid CORS.
Ullav Platform Auth
Authentication uses the shared ullav-user-management JWT service — the same JWT secret used across all Ullav products. There is no separate user database; SSO, RBAC, and session management are all inherited from the platform.
Docker & Helm
Both server and browser ship as Docker images with Helm charts for Kubernetes deployment. Sensitive configuration (database credentials, JWT secret) is passed via Docker secrets or Kubernetes secrets — never baked into images.
Technical FAQs
Technical questions answered
What is the technology stack?
The ullav-collection-server backend is built in Rust using Actix-web 4, with PostgreSQL for persistence. The ullav-collection-browser frontend is Next.js 16, React 19, TypeScript, and Tailwind CSS. Label generation uses jsPDF and bwip-js in the browser. Authentication is via the shared ullav-user-management JWT service.
How are accession numbers guaranteed unique?
The assignAccession endpoint uses an atomic database operation to read the current sequence, increment it, generate the formatted number, and record the acquisition — all in a single transaction. Concurrent requests cannot produce duplicate numbers regardless of load.
How does the public portal work technically?
The /public/objects endpoints are unauthenticated — no bearer token is required. They return only objects where is_public = true, and return the same fields as the authenticated endpoints (title, type, maker, date, materials, description). The frontend routes /browse to a view that calls these endpoints directly.
Can Cartlann integrate with Comad for digital surrogates?
Cartlann and Comad share the same authentication infrastructure. Digital surrogates — high-resolution scans, photographs, and documents — are stored in Comad and can be linked to Cartlann object records. Integration is via the Comad REST API using the shared JWT token. No separate login or API key is needed.
What export formats does Cartlann support?
All collection data is accessible via the REST API in JSON. LIDO XML export supports Europeana and aggregator integration. MARC 21 export enables library and archive catalogue integration for manuscript and rare book collections. Label generation exports to PDF. Custom export formats can be added as part of an institutional implementation.
How does Cartlann fit into the broader Ullav platform?
Cartlann shares authentication (ullav-user-management), deployment infrastructure (Docker/Kubernetes on ullav-net), and integration patterns with the rest of the Ullav suite. Digital assets associated with collection objects live in Comad; workflows triggered by collection events (accession approvals, loan requests) can be orchestrated through Obair.
Ready to catalogue your collection?
Get in touch to discuss how Cartlann can be deployed and configured for your institution.