Skip to main content

​
Get Up and Running

This guide will take you from zero to a fully functional library kiosk in just a few steps.
Prerequisites: Python 3.11+, pip, and git installed on your system.
1

Clone the Repository

Open a terminal and clone the repository to your local machine:
git clone <repository-url>
cd cs-library-kiosk
2

Set Up Virtual Environment

Create and activate a Python virtual environment:
python3 -m venv venv
source venv/bin/activate
3

Install Dependencies

Install all required Python packages:
pip install -r requirements.txt
This installs:
  • nicegui - Web UI framework
  • httpx - For Open Library API calls
  • bcrypt - Password hashing
  • fastapi - Backend framework
  • And other supporting libraries
4

Seed the Database

Populate the database with the initial catalog and test accounts:
python3 mock_data.py
This creates cs_library.db and seeds it with:
  • 16 books from the CS Library shelves
  • 3 test user accounts

​
Test Accounts Created

NameEmailStudent IDPassword
Kenneth Molina[email protected]12345changeme123
Jose Gaspar[email protected]11111changeme123
Professor James[email protected]99999changeme123
5

Launch the Kiosk

Start the NiceGUI server:
python3 main.py
The kiosk will be accessible at:
http://localhost:8080
The server runs on 0.0.0.0:8080 by default, making it accessible on your local network. For production deployment, configure proper firewall rules.
6

Log In and Test

Open your browser to http://localhost:8080 and test the login:
  1. Student Login: Enter student ID 12345 at the login screen
  2. Browse Catalog: View the paginated book catalog
  3. Test Checkout: Scan or enter an ISBN like 0471170828
  4. View My Books: Navigate to the My Books tab
The login screen accepts student ID input via keyboard or barcode scanner (scanner acts as keyboard input).

​
Understanding the Workflow

​
Student Workflow

​
How Checkout Works

When you scan a book ISBN:
  1. System checks local database for the book
  2. If not found, queries Open Library API
  3. Book details displayed with cover image
  4. Add to cart (supports multiple books)
  5. Confirm checkout - books marked “Checked Out”
  6. Due date automatically set to 14 days from today

​
Database Initialization

The first time you run python3 main.py, the system automatically calls:
database.py
def init_db() -> None:
    with _connect() as conn:
        conn.executescript('''
            CREATE TABLE IF NOT EXISTS users (
                id            INTEGER PRIMARY KEY AUTOINCREMENT,
                student_id    TEXT    NOT NULL UNIQUE,
                name          TEXT    NOT NULL,
                email         TEXT    NOT NULL UNIQUE COLLATE NOCASE,
                password_hash TEXT    NOT NULL,
                active        INTEGER NOT NULL DEFAULT 1,
                created_at    DATETIME DEFAULT CURRENT_TIMESTAMP
            );

            CREATE TABLE IF NOT EXISTS books (
                isbn    TEXT PRIMARY KEY,
                title   TEXT NOT NULL,
                author  TEXT NOT NULL,
                cover   TEXT NOT NULL DEFAULT "",
                status  TEXT NOT NULL DEFAULT "Available",
                shelf   TEXT NOT NULL DEFAULT ""
            );

            CREATE TABLE IF NOT EXISTS loans (
                id            INTEGER PRIMARY KEY AUTOINCREMENT,
                user_id       INTEGER NOT NULL REFERENCES users(id),
                isbn          TEXT    NOT NULL REFERENCES books(isbn),
                checked_out   DATETIME DEFAULT CURRENT_TIMESTAMP,
                due_date      DATETIME NOT NULL,
                returned      INTEGER  NOT NULL DEFAULT 0,
                returned_date DATETIME
            );
        ''')
        conn.commit()
This creates three core tables: users, books, and loans.

​
Common Tasks

​
Adding a New Book

Books are automatically added when you scan a new ISBN. The system:
  1. Queries Open Library API
  2. Retrieves metadata (title, author, cover)
  3. Caches locally in cs_library.db
database.py
async def get_book(isbn: str) -> Optional[dict]:
    """Fetch a single book by ISBN. Checks local DB first, then Open Library."""
    isbn = isbn.strip()
    
    # Check local database first
    def _fetch():
        with _connect() as conn:
            row = conn.execute(
                "SELECT * FROM books WHERE isbn = ?", (isbn,)
            ).fetchone()
        return _row(row)
    
    book = await _run(_fetch)
    
    if book:
        print(f" [DB] Found ISBN {isbn} in local database.")
        return book
    
    # Query Open Library if not found locally
    if USE_LIVE_API:
        print(f" [MISS] ISBN {isbn} not in DB — querying Open Library...")
        return await _fetch_from_open_library(isbn)
    
    return None

​
Checking Out Books

The checkout flow supports adding multiple books to a cart:
main.py
async def scan_checkout_logic():
    book = await db.get_book(checkout_input.value)
    checkout_input.value = ''
    
    if book:
        if book['status'] != 'Available':
            ui.notify('Book is already checked out!', type='warning')
            return
        
        cart_items.append(book)
        due = datetime.now() + timedelta(days=14)
        checkout_due_date.text = f'Due: {due.strftime("%B %d, %Y")}'
        
        # Update UI with book details
        checkout_cover.source = book['cover']
        checkout_title.text   = book['title']
        checkout_author.text  = book['author']

​
Renewing Books

Students can renew books from the My Books tab:
database.py
async def renew_book(loan_id: int) -> bool:
    """Extend the due date of an active loan by 14 days from today."""
    def _renew():
        now = datetime.now()
        new_due_date = now + timedelta(days=14)
        with _connect() as conn:
            loan = conn.execute(
                "SELECT id FROM loans WHERE id = ? AND returned = 0",
                (loan_id,)
            ).fetchone()
            
            if loan is None:
                return False
            
            conn.execute(
                "UPDATE loans SET due_date = ? WHERE id = ?",
                (new_due_date, loan_id)
            )
            conn.commit()
        return True
    
    return await _run(_renew)

​
Next Steps

Full Installation Guide

Detailed setup for production deployment

Core Features

Complete feature documentation

​
Troubleshooting

​
Database Not Found Error

If you see cs_library.db not found:
  1. Run python3 main.py first (creates database)
  2. Then run python3 mock_data.py to seed data

​
Import Errors

If you see module import errors: 
# Ensure virtual environment is activated
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Reinstall dependencies
pip install -r requirements.txt

​
Port Already in Use

If port 8080 is already taken, modify main.py:
main.py
ui.run(host='0.0.0.0', port=8081, title="CS Library Kiosk", favicon='favicon1.ico', dark=True)
Need help? Check the Installation Guide for more detailed troubleshooting steps.

Build docs developers (and LLMs) love

Get started for freeTalk to us