Shelf

Shelf is a full‑stack, open‑source inventory platform built to give developers granular control over asset lifecycle management. At its core, Shelf exposes a REST‑like API and a GraphQL endpoint that allow programmatic creation, update, and querying of assets, locations, bookings, and custom metadata. The application is designed around event‑driven data flows: every mutation emits a Supabase trigger that updates search indices, notifies webhooks, and syncs QR‑code payloads to a CDN. This design makes Shelf highly responsive for real‑time dashboards and mobile integrations.

• Frontend – Next.js (React) with TypeScript, leveraging server‑side rendering for SEO and incremental static regeneration. The UI uses Radix UI primitives and TailwindCSS, ensuring a lightweight bundle that can be extended with custom React components.
• Backend – Supabase (PostgreSQL + PostgREST) serves as the primary data store, authentication layer, and storage for QR images. Supabase functions (edge workers) implement business logic such as booking conflicts, reservation expiries, and custom field validation.
• Infrastructure – The stack is container‑friendly; a Docker Compose file orchestrates the Next.js server, Supabase (via supabase/cli), and optional reverse proxy. For Kubernetes, the Helm chart exposes services for the API gateway and PostgreSQL, with persistent volumes for stateful data.
• Caching & Search – A dedicated Supabase function updates a PostGIS‑enabled assets table for GPS queries, while Algolia (optional) powers instant search with fuzzy matching and faceted filters.

• QR Code & Asset Tags – Each asset is assigned a unique QR code that points to a public URL. The QR payload can be customized via templating, and the image is stored in Supabase storage buckets.
• Location & GPS Tracking – Assets can be tagged with latitude/longitude; the API exposes a /locations endpoint that returns nearby assets within a radius.
• Reservation System – Bookings are first‑come, first‑served; the API enforces overlap detection server‑side. Webhooks can be configured to trigger Slack or email notifications upon creation, cancellation, or conflict resolution.
• Custom Fields & Metadata – Developers can define arbitrary JSON schemas per asset type; the backend validates against these schemas before persisting.
• Analytics & Insights – A set of GraphQL queries aggregate usage, condition scores, and warranty expiries. The data model supports time‑series extensions via Supabase’s timescaledb extension if needed.

Shelf is self‑hostable on any environment that supports Docker or Node.js. Minimum requirements:

• CPU: 2 vCPUs (recommended 4)
• Memory: 4 GB RAM (8 GB for production workloads)
• Storage: SSD, minimum 20 GB for the database and media bucket.

For scalability, Supabase can be run on a managed Postgres cluster (e.g., DigitalOcean Managed Databases) and the Next.js app behind a CDN such as Cloudflare Workers. Horizontal scaling is achieved by running multiple instances of the Next.js server behind a load balancer; Supabase handles connection pooling automatically. The Docker image is lightweight (~200 MB) and can be updated via CI/CD pipelines.

• Plugin System – Shelf exposes a hook registry where developers can register middleware for request/response cycles, allowing custom authentication providers or data enrichment.
• APIs & Webhooks – REST endpoints (/api/assets, /api/bookings) and GraphQL subscriptions enable real‑time updates. Webhooks are configurable per event type (create, update, delete) and can target HTTP endpoints or message queues.
• SDKs – A TypeScript SDK (available on npm) wraps the REST and GraphQL APIs, providing typed models for assets, bookings, and custom fields.
• Custom Workflows – Using Supabase’s serverless functions, developers can implement approval pipelines or audit trails without modifying the core codebase.

Shelf’s documentation is hosted in a dedicated docs/ folder, written in Markdown with live code snippets and API reference tables. The community is active on Discord, where developers share plugins and troubleshoot integration issues. Licensing under the MIT license removes barriers to commercial use, while a Contributor Covenant ensures an inclusive environment.

• Enterprise IT Asset Management – Track laptops, peripherals, and network equipment with GPS tagging for mobile teams.
• Theatre & Production – Manage props, costumes, and scenic elements; schedule reservations to avoid double bookings.
• Educational Institutions – Centralize department inventories (lab equipment, media gear) with role‑based access and audit logs.
• Home & Personal Use – Keep a digital catalog of valuables, warranties, and insurance details.

Shelf offers performance through Supabase’s native PostgreSQL optimizations and optional PostGIS for spatial queries. Its flexibility stems from a schema‑less custom field system and extensible hook architecture, allowing developers to adapt the platform to niche workflows. The open‑source nature and MIT license mean no vendor lock‑in, while the active community provides rapid bug fixes and feature requests. For developers needing a turnkey inventory solution