WorldCovers

Welcome to WorldCovers, a stampless cover and postmark catalog application

This build, nicknamed Warp, is version 2.0.0 (beta).

Another success is the post-office, with its educating energy augmented by cheapness and guarded by a certain religious sentiment in mankind; so that the power of a wafer or a drop of wax or gluten to guard a letter, as it flies over sea over land and comes to its address as if a battalion of artillery brought it, I look upon as a fine meter of civilization.

    -- Ralph Waldo Emerson

Table of Contents

• Project Overview
• Building
• Configuration
• Execution
• Errata

Project Overview

Version strings follow the MAJOR(\d+) . MINOR(\d+) . REVISION(\d+) format.

Current planned Milestones are alpha, beta, and rtm.

Currently only tested on Chromium (TODO: version?) on Windows 11, and Brave (1.82.170-arm64) on macOS Sequoia & Tahoe.

For licensing details, see LICENSE

Apps:

• Common Model
  • The core of the application. Describes Django data structures used by both server and clients.
• WoCo Server
  • The Django application powering the REST interface and URL routing. Contains configuration in settings.py.
• Web UI
  • The public UI at hellowoco.app is a React SPA (e.g. from Lovable) contained in frontend. Django serves it as the site home and all frontend routes, with API and admin staying under the /api/ and /admin/ URLs.

For more details see design.md

Building

Quickstart

This project uses pipenv and django. Make sure you have at least python 3.13 installed. All Django commands use pipenv run manage <cmd> — for example pipenv run manage runserver.

For full setup instructions (dependencies, database credentials, frontend build, migrations), see docs/BUILD.md.

To have the site home and routes served by the React app (e.g. at hellowoco.app), add your frontend in frontend/ and run npm run build there before deployment. The built output (frontend/dist/) is not in git, so your deploy must run the frontend build (e.g. cd frontend && npm ci && npm run build) before starting Django. See docs/DEPLOY.md and frontend/README.md.

Configuration

TODO

Execution

To run WorldCovers in production, deploy with tools/deploy.sh then manage the process via systemd:

sudo systemctl start worldcovers

To run in development, build the frontend once, then start Django (it serves the built SPA at /):

cd frontend && npm ci && npm run build && cd ..
pipenv run manage runserver

For day-to-day operator tasks (restarts, imports, backups, approving contributions), see docs/RUNBOOK.md.

For data import and management commands, see docs/TOOLS.md.

Errata

TODO: Links to repo wiki

TODO: Links to user documentation

TODO: Links to developer/contributor documentation

Of course, make sure you also visit our sponsor The US Philatelic Classics Society, and see our live version of this app!

For any issues or contributions to WorldCovers, please refer to our issue tracker or contributing guide.

Parts of this codebase were generated by AI. No PRs are automatically accepted without human review, and a good faith effort is being made to avoid leaked proprietary code and usage without attribution. Do not hesitate to contact us with questions/comments/concerns!

We hope you enjoy WorldCovers!