Atelier is an open-source workspace for building a catalogue raisonné: a documented record of an artist's known works. Bring images, provenance, exhibitions, research leads, and acquisition notes together, then browse the collection in a gallery or on a dedicated display.
Tour the interface · Get started · Display frame · Make it your own · Roadmap
Actual application screens from the included demo. The artwork is original procedural sample art; catalogue entries, exhibitions, contacts, and correspondence are synthetic. A regular installation still starts empty.
Try the populated demo · Download the promotional image · GitHub social preview
Atelier is built for researchers, estate managers, galleries, and collectors who need more than a folder of images. A record can connect a work's physical description with where it was shown, how it changed hands, and what still needs to be verified.
| Workflow | Available in the source |
|---|---|
| Catalogue | Artwork records, multiple images, dimensions, medium, dating, condition, provenance notes, and verification status. |
| Browse and compare | Gallery layouts, filtering, artwork details, acquisition tracking, and a chronological timeline. |
| Document exhibitions | Show records, dates and venues, with links to the works exhibited. |
| Follow research leads | Contacts, outreach records, follow-ups, and optional Gmail integration. |
| Discover works | Saved searches, result review, and artist-specific confidence scoring. eBay API and web-scraper integrations require separate setup. |
| Share a view | CSV/JSON exports of selected record fields, a REST API, and a browser-based display mode. |
Open a work to move from its image to its medium, dimensions, condition, provenance, and exhibition history. The same records power the catalogue and its display view.
 Follow the timeline See works and exhibitions in chronological context. |
 Connect works to shows Keep exhibition history beside the collection. |
The tracker keeps a candidate work's source and acquisition status together. Discovery adds saved searches and results to review. Confidence scores help prioritize candidates; they are research aids, not authentication of artwork. Outreach records keep contacts and follow-ups alongside the research.
 Keep the research moving Review candidates and track acquisition status. |
 Review new finds Connect saved searches to a review queue. |
The outreach records above are fictional demonstration entries. No real mailbox is connected and no messages were sent.
External services need your own credentials where applicable. API quotas, availability, and site terms vary; scraper code in the repository does not mean every provider has been recently tested.
The /frame page presents the collection as a slideshow, with touch navigation and display settings. Run it in a normal browser or open it in Chromium kiosk mode on a Raspberry Pi connected to a suitable screen.
The application can run on the same computer as the display. A separate display client needs a deliberately configured, protected connection to the host. See the display hardware guide for parts, layout, and kiosk setup. A Pi and touchscreen are optional; start on a computer first.
Use Python 3.11 or newer and Git. A compiled stylesheet is included, so Node.js is only needed when editing the Tailwind theme. No API keys are needed to open an empty catalogue.
git clone https://github.com/NotADevIAmaMeatPopsicle/Atelier.git
cd Atelier
py -3 -m venv .venv
./.venv/Scripts/python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
New-Item -ItemType Directory -Force data/images | Out-Null
./.venv/Scripts/python.exe -m src.cli init
./.venv/Scripts/python.exe -m src.cli servergit clone https://github.com/NotADevIAmaMeatPopsicle/Atelier.git
cd Atelier
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
cp .env.example .env
mkdir -p data/images
.venv/bin/python -m src.cli init
.venv/bin/python -m src.cli serverOpen http://127.0.0.1:8000 and use Add Artwork to create your first record. API documentation is at /docs. Stop the server with Ctrl+C.
Keep this installation private. Atelier does not yet have application login or role-based access. Its catalogue, outreach, and connected Gmail operations share the host's authority. The default setup binds to localhost; do not expose the port to the internet. See security and private data before configuring remote access or connecting mail.
Docker Compose is included. Copy .env.example to .env, then run:
docker compose up --build -dOpen the same local URL. Data persists in ./data; docker compose down stops the service. Host access is bound to localhost by default. Automated scraping is off unless you explicitly set ENABLE_SCHEDULER=true.
The image includes the Playwright Python package, but no browser binaries. Browser-driven scrapers need additional setup. Review configuration and development before enabling discovery integrations.
After installing the Python dependencies, launch the included sample catalogue:
# Windows PowerShell
./.venv/Scripts/python.exe scripts/run_demo.py# macOS / Linux
.venv/bin/python scripts/run_demo.pyOpen http://127.0.0.1:8779/?tab=gallery. The demo generates 16 original colour studies, four exhibitions, four sample contacts, and discovery and research records. It runs the real gallery, detail, tracker, timeline, outreach, discovery, and display pages.
The demo stores its own database and images under ignored local/demo/, reuses that sample collection on subsequent launches, and refuses to overwrite an unmarked directory. It does not load your regular .env; mail, live discovery, and image-download actions are disabled. The visible Demo collection label distinguishes it from a real catalogue. Use --port 8780 if the default demo port is occupied, or --seed-only to prepare the samples without starting the server. Stop it with Ctrl+C.
See the interface walkthrough for the complete screenshot tour and image notes for provenance and promotional downloads.
Atelier began as a catalogue of the painter Dan Brown (1949–2022). Outside the explicitly labelled demo, the UI, biography, search terms, notification text, and confidence rules still reflect that artist. Changing APP_NAME alone does not retarget the whole app.
For another collection, update these together:
| Area | Starting point |
|---|---|
| Name and runtime settings | Configuration and your ignored .env |
| Branding, biography and timeline | Templates and biography data |
| Search terms and provider behavior | Scrapers and saved-search routes |
| Artist disambiguation | Confidence rules and their tests |
| Email wording | Notification templates |
Keep collection records, private research, images, credentials, and backups in local storage. Use a fresh database for a new collection. A reusable artist profile is a natural next step for the project.
Early development. The repository contains the workflows shown above, but it is not a finished multi-user or public collection-hosting service. The test suite covers confidence scoring, page rendering, and demo isolation, not every workflow or external integration.
| Planned work | Direction |
|---|---|
| Collection foundations | Guided imports, duplicate detection, image annotations, and completeness checks. |
| Scholarly records | Structured provenance chains, bibliographies, and catalogue numbering. |
| Collaboration | Login, roles, activity history, and review workflows. |
| Publishing | Print-ready catalogues and a separate public collection portal. |
| Discovery | More provider integrations and better review tools. |
The task specifications describe the longer-term plan. They are design proposals, not proof that a feature is implemented.
FastAPI and Jinja2 serve the web workspace; SQLAlchemy and SQLite store records. The frontend uses Tailwind CSS and vanilla JavaScript. Discovery uses HTTP/API clients and optional browser automation. Gmail and SMTP are optional integrations.
| Guide | Contents |
|---|---|
| Interface walkthrough | Pages, screenshots, and how the workflows connect |
| Configuration and development | Environment settings, CSS, tests, CLI commands, and source layout |
| Display hardware | Computer/Pi setup and browser kiosk mode |
| Security | Deployment boundaries and private-data handling |
| Contributing | Development and publication checks |
The software and the original sample graphics created by the demo generator are released under the MIT License. The new screenshots use those graphics and synthetic records. Artwork you import from other sources retains its own rights. See image notes. Atelier is an independent project, unaffiliated with the artists' estates or external services it can use.