Architecture

Shelf-School is a server-rendered Django application designed to keep a school library operational on one computer. The same Mac can serve its own kiosk or a small set of circulation devices on trusted school Wi-Fi.

Deployment topology

Public surfaceCirculation devicesBorrower search, book photo, manual selection, and confirmation

Authenticated surfaceStaff browserCatalog, borrowers, reports, settings, and backups

Trusted Wi-Fi or this Mac · HTTP port 8427

Dedicated MacShelf-School

Django viewsHTML, forms, authentication, and validation

Domain rulesCopies, borrowers, loans, and signed confirmation

Local decoderzxing-cpp reads QR and ISBN barcodes

Local filesystem by default

Structured dataSQLiteBooks, copies, people, settings, and loan history

Stored filesMedia directorySchool branding and intentional catalog covers

Optional outbound requestOpen LibraryFree ISBN metadata and available cover images

The Mac is the system of record. Circulation devices do not keep a second copy of the catalog, and ISBN-intake or circulation photos are not retained after decoding.

Circulation write path

1Identify borrowerBorrower ID or name

2Identify copyPhoto, QR, ISBN, or manual search

3Validate rulesAvailability, active loan, and ambiguity

4ConfirmSigned, short-lived transaction token

5Commit loanLocked and revalidated database update

Photo identification never changes circulation state by itself. The final request locks and revalidates each selected copy inside one database transaction. A stale, repeated, or partially invalid multi-book operation cannot leave half a basket checked out.

Domain model

BookTitle or edition

1 to manyphysical items

CopyUnique QR and status

1 to manyloan history

LoanCheckout, due, return

many to 1assigned to

BorrowerStudent or employee

Staff account 1 to 1 BorrowerBorrower ID, name, and email stay synchronized.

School profile 1 per installationBranding, contact details, and default loan duration.

School class 1 to many StudentsOptional assignment; renaming updates every linked profile.

Employee position 1 to many EmployeesOptional assignment, independent of login permissions.

The database enforces one active loan per physical copy. Returned loans stay as history, and deleting or deactivating staff access does not remove the linked borrower or circulation records.

Classes and positions are protected foreign keys: assigned entries cannot be deleted. Deactivation prevents new assignments while preserving existing ones. The single borrower CSV importer validates both roles and their assignments in one transaction; it never creates authentication accounts.

Trust boundaries

PublicCirculation deskSupervised checkout and return without a student login

StaffLibrary operationsCatalog, borrowers, reports, backups, and school settings

System administratorAdvanced Django AdminExceptional technical database and permission maintenance

Named recent activity is not rendered for signed-out users. The public desk is intentionally reachable on the trusted school network; staff and advanced surfaces remain protected by Django authentication.

Storage and external services

• db.sqlite3 is the default structured store and must be backed up with media/.
• Uploaded files use local media storage on the dedicated Mac.
• zxing-cpp decodes QR and ISBN barcodes locally without a paid API.
• Open Library is contacted only for optional ISBN metadata and covers.
• No paid AI service is required.