topos

Topos is an open-source web application for cataloguing physical storage such as file folders, archive boxes, and drawers, along with the items they contain. It provides a four-entity inventory model covering containers, items, hierarchical categories, and follow-up actions. The app runs as an offline-first Progressive Web App with a Dexie read-through cache, rendering pages instantly from IndexedDB before revalidating against the API. An optional FastAPI/SQLite backend serves as the single source of truth. A key feature is lossless Excel import: users can upload a workbook in a specific three-sheet shape, and Topos materialises the inventory including ancestor-chain categories. Import is idempotent on container external IDs, so re-importing the same file produces no duplicates. German category names are translated to English slugs at import time while preserving the original German as display names. The project is built on PluginForge, an application-agnostic plugin framework, with the Excel importer itself implemented as a plugin. This architecture is intended to support future imports, exports, QR labels, and photo attachments. A cross-platform desktop launcher for Linux, macOS, and Windows is built from the same FastAPI and React codebase using PyInstaller. Topos is in bootstrap stage and not yet production-hardened. The README advises against running it on shared infrastructure without a reverse proxy and recommends replacing the default secret key. The repository includes backend tests with pytest, frontend tests with Vitest, and a Playwright smoke spec.