What Shelfinity is
Shelfinity is a full-stack library management system for a single library or small library network. Patrons browse the catalog and submit borrow, return, and reservation requests; staff review a single approval queue, manage the catalog, configure notification email, and pull reports. Identity is handled entirely by Keycloak — the backend validates Keycloak-issued JWTs and never stores a password.
Catalog & requests
Browse, search, and filter the catalog. Submit borrow, return, and reservation requests that route into a single admin approval queue.
One approval queue
Registration, borrowing, and returns share one review → approve/reject → notify workflow, so staff have a single place to work from.
Reservations & overdue tracking
Reserve a title that's checked out, get notified when it's available, and let a scheduled job track and remind on overdue loans automatically.
Admin reporting
Book popularity, borrowing trends, user activity, author distribution, and library-wide statistics — no spreadsheet exports required.
Keycloak-backed identity
OIDC authentication via Keycloak. The app keeps a local profile cache for joins and role checks, but never sees a plaintext password.
Configurable notifications
Admin-managed SMTP configuration drives async email for every state change — request outcomes, reservation readiness, overdue reminders.
Why it’s built this way
Every behavior documented on this site is verified against the running
codebase, not aspirational. The full specification — including the exact
business rules, entity fields, and the reasoning behind decisions like
“why Keycloak instead of a homegrown login” — lives in
docs/api/SPEC.md
in the repository. This site is the readable front door to that spec, plus
a getting-started path and a browsable API reference.
Where to go next
- New to the project? Start with Getting Started to run the full stack locally with Docker Compose.
- Want the system design? Architecture covers the service topology and technology choices.
- Building against the API? API Reference lists every resource, endpoint, and access rule.
- Need the exact state machines? Business Rules walks through registration approval, borrowing, returns, and reservations end to end.