Skip to main content

​
Welcome, System Administrator!

This guide covers all administrative functions in the SWL Library Management System. As an admin, you have full system control including user management, catalog oversight, and system configuration.

​
Getting Started

​
Administrator Access

1

Login as Admin

Navigate to /auth/login and enter your admin credentials
2

Auto-redirect to User Management

After successful login, you’re redirected to /users - the user management page
3

Explore Admin Features

Navigate between user management, dashboard, catalog, and reports
Administrators have access to all features available to librarians, plus exclusive user and system management capabilities.

​
User Management

User management is the primary administrative function.

​
Accessing User Management

Navigate to /users to see all registered users with:
  • Pagination (10 users per page)
  • User details (name, document ID, email, role, program)
  • Action buttons for each user (edit, delete)
  • Forms for creating new users and bulk import

​
Creating New Users

1

Access User Management

Navigate to /users
2

Fill User Creation Form

Enter the following information:
  • Full Name: User’s complete name
  • Document ID: Unique identifier (will be username)
  • Email: User’s email address (must be unique)
  • Phone: Contact phone number
  • Role: Select from:
    • cliente (Student)
    • premium (Premium User)
    • bibliotecario (Librarian)
    • admin (Administrator)
  • Program Name: Required only for ‘cliente’ role
  • Password: Initial password for the user
3

Submit

Click create. The system will:
  • Validate uniqueness of document ID and email
  • Hash the password securely
  • Set program_name to NULL for non-cliente roles
  • Add user to database
4

Notify User

Inform the new user of their credentials (document ID and password)
Route Reference: User creation is handled at /users/create (POST method)
Validation Checks:
  • Document ID must be unique
  • Email must be unique
  • All required fields must be filled
  • Password is immediately hashed (never stored in plaintext)

​
Searching Users

Quickly find users with the search feature:
1

Use Search Box

Enter search term in the search field
2

Search Filters

The system searches across:
  • Full name (case-insensitive)
  • Document ID (case-insensitive)
3

View Results

Results are paginated and sorted alphabetically by nameRoute: /users/search?search=<term>&page=<num>

​
Editing Users

1

Locate User

Find the user in the user management list or via search
2

Click Edit

Each user has an associated edit form
3

Modify Fields

You can update:
  • Full name
  • Phone number
  • Role
  • Program name (for cliente role)
  • Password (optional - leave blank to keep current password)
4

Submit Changes

Click update. The system will:
  • Validate the changes
  • Update program_name logic based on role
  • Hash new password if provided
  • Commit to database
Route Reference: User editing is at /users/edit/<user_id> (POST method)
Cannot Edit:
  • Document ID (system identifier)
  • Email address (use as unique contact identifier)
To change these, delete and recreate the user.

​
Deleting Users

Caution: User deletion is permanent and cannot be undone. All associated data may be affected.
1

Locate User to Delete

Find the user in user management
2

Click Delete Button

Confirm deletion action
3

System Validation

The system checks:
  • You’re not deleting your own account (prevented)
  • User exists in database
4

Delete Execution

User record is removed from databaseRoute: /users/delete/<user_id> (POST)
Self-Deletion Prevention: The system prevents administrators from deleting their own account to avoid lockout scenarios.

​
Bulk User Import

For importing multiple users at once:
1

Prepare Import File

Format user data according to import specification (typically CSV)
2

Access Import Form

Use the bulk import form on /users
3

Upload File

Select and upload your import fileRoute: /users/bulk_import (POST)
4

Verify Results

Check that all users were created successfully
Bulk import details depend on the ImportForm implementation. Check form validation for required format.

​
Dashboard and Loan Oversight

Administrators have full access to the librarian dashboard.

​
Accessing the Dashboard

Navigate to /dashboard to view:

Loan Statistics

  • Pending requests count
  • Active loans count
  • Returned items count
  • Overdue loans count

Top Borrowed Items

Top 5 most-requested catalog items with loan counts

Status Filtering

Filter loans by: pendiente, activo, devuelto, atrasado

Loan Management

Approve, reject, and process returns for all loans

​
Loan Management Operations

Administrators can perform all librarian functions:
  • Approve Loans: /approve/<loan_id> (POST)
  • Reject Loans: /reject/<loan_id> (POST)
  • Process Returns: /loan/<loan_id>/return (POST)
For detailed loan management procedures, see the Librarian Guide.

​
Catalog and Inventory Management

​
Catalog Administration

Full catalog control at /catalog:
1

View Catalog

See all catalog entries with total and available counts
2

Search Catalog

Filter by title/name or category using search box
3

Create Catalog Entries

Add new catalog items:
  • Title or Name
  • Category (libro, computo, general)
  • Author or Brand
4

Delete Entries

Remove catalog items (only if no instances exist)Route: /catalog/delete/<catalog_id> (POST)

​
Instance Management

Manage physical inventory at /catalog/<catalog_id>/instances:
1

Select Catalog Item

Click on a catalog entry to manage its instances
2

Add Instances

Create physical item records:
  • Unique Code: Barcode, serial number, or identifier
  • Condition: Description of physical condition
  • Status: disponible, mantenimiento, perdido
3

Update Instance Status

Change status for maintenance or lost itemsRoute: /instance/update_status/<instance_id> (POST)
4

Delete Instances

Remove instances not part of active loansRoute: /instance/delete/<instance_id> (POST)
Instance Deletion Restrictions:
  • Cannot delete instances involved in pending, active, or overdue loans
  • Ensures data integrity and accurate loan records

​
System Configuration

​
Penalty Fee Configuration

The system uses a configurable penalty fee for overdue books: 
# In your Flask configuration (config.py)
PENALTY_FEE_PER_DAY = 5000.0  # Default: $5,000 COP per day
1

Locate Configuration

Find the config.py file in your source code
2

Modify PENALTY_FEE_PER_DAY

Change the value to your desired daily penalty amount
3

Restart Application

Restart the Flask application to apply changes
4

Verify

Check that new overdue books use the updated penalty rate
Penalty changes only affect new overdue periods. Existing frozen penalties (final_penalty) are not retroactively updated.

​
Loan Duration Configuration

Default loan period is 15 days, set in LoanService.create_loan(): 
# In app/services/loan_service.py
def create_loan(user_id, instance_id, environment=None, days=15):
To modify:
1

Edit loan_service.py

Locate the create_loan method
2

Change Default Days

Modify the days=15 parameter to your desired duration
3

Restart Application

Apply changes by restarting Flask

​
Automated Overdue Detection

The system runs a background scheduler to detect overdue loans:
  • Function: LoanService.check_overdue_loans()
  • Action: Changes ‘activo’ loans to ‘atrasado’ when due_date < current_time
  • Frequency: Configured in your scheduler setup
To modify scheduler frequency, check your APScheduler configuration in the Flask app initialization.

​
Reports and Statistics

​
Dashboard Statistics

The admin dashboard provides real-time metrics:
  • Pending Count: Requests awaiting approval
  • Active Count: Currently loaned items
  • Returned Count: Successfully returned items
  • Overdue Count: Items past due date

​
Top Items Report

View the 5 most popular items: 
-- System query (for reference)
SELECT catalog.title_or_name, COUNT(loan.id) as total
FROM catalog
JOIN item_instance ON item_instance.catalog_id = catalog.id
JOIN loan ON loan.instance_id = item_instance.id
GROUP BY catalog.title_or_name
ORDER BY total DESC
LIMIT 5
This helps identify:
  • High-demand items (consider adding more instances)
  • Usage patterns by category
  • Inventory expansion opportunities

​
Custom Reporting

For advanced reporting:
1

Access Database

Use database admin tools to query the database directly
2

Key Tables

  • user: User accounts and roles
  • catalog: Catalog entries
  • item_instance: Physical inventory
  • loan: All loan transactions
  • library_log: Visitor activity logs
3

Export Data

Extract data for external analysis (Excel, BI tools, etc.)

​
Role-Based Access Control

Understand the role hierarchy:
Full System Access:
  • All librarian functions
  • User creation, editing, deletion
  • System configuration
  • Access to all routes
Default Route: /users (user management)

​
Implementing Role Checks

The system uses the @role_required decorator: 
from app.utils.decorators import role_required

@bp.route('/users')
@role_required('admin')
def manage_users():
    # Only admin can access
    ...

@bp.route('/dashboard')
@role_required('bibliotecario', 'admin')
def admin_dashboard():
    # Both bibliotecario and admin can access
    ...
Routes without role decorators are accessible to all authenticated users.

​
User Journey Management

​
Upgrading Users

To upgrade a standard student to premium:
1

Locate User

Find the user in /users or search by name/document
2

Edit User

Click edit and change role from ‘cliente’ to ‘premium’
3

Save Changes

Submit the edit form
4

Immediate Effect

User immediately gains:
  • Access to specialized equipment
  • Multi-unit laptop requests
  • Full accessory catalog

​
Creating Librarian Accounts

1

Create New User

Use the user creation form at /users
2

Set Role to 'bibliotecario'

Select librarian role (program_name not required)
3

Provide Credentials

Give the new librarian their document ID and password
4

Train on Dashboard

Ensure they understand loan approval and return processes

​
Creating Admin Accounts

Caution: Create admin accounts sparingly. Admins have full system control including user deletion and configuration changes.
1

Create User with Admin Role

Use user creation form and select ‘admin’ role
2

Secure Credentials

Ensure strong password and secure credential transmission
3

Document Admin Access

Keep record of admin accounts for audit purposes

​
Best Practices

  • Use consistent document ID formats (e.g., student IDs)
  • Verify email addresses are valid before creating accounts
  • Set strong initial passwords and advise users to change them
  • Regularly audit user accounts for inactive or duplicate entries
  • Document role changes for accountability
  • Limit the number of admin accounts
  • Never share admin credentials
  • Regularly review user roles to ensure appropriate access
  • Monitor deletion actions to prevent data loss
  • Use the self-deletion prevention feature wisely
  • Use descriptive titles and author/brand information
  • Maintain consistent category naming
  • Regularly audit catalog for duplicate entries
  • Remove obsolete catalog items after deleting all instances
  • Use systematic unique codes (e.g., “LAPTOP-001”, “BOOK-ISBN”)
  • Document condition descriptions consistently
  • Promptly mark lost or damaged items
  • Conduct regular physical inventory checks
  • Document all configuration changes
  • Test penalty rate changes with sample calculations
  • Schedule configuration updates during low-usage periods
  • Back up database before major changes
  • Review dashboard statistics daily
  • Monitor top items for inventory planning
  • Track overdue rates to identify systemic issues
  • Generate regular usage reports for stakeholders

​
Troubleshooting Admin Issues

Cause: Document ID or email already existsSolution:
  1. Search for existing user with that document ID or email
  2. If found, edit existing user instead
  3. If not found, check for typos in your input
  4. Verify database integrity
Cause: Attempting to delete own accountSolution:
  1. Use another admin account to delete the user
  2. Or keep the account active
  3. System prevents self-deletion for safety
Cause: User session cached old roleSolution:
  1. User must log out and log back in
  2. Browser cache may need clearing
  3. Verify database was updated successfully
Cause: Instances still existSolution:
  1. Navigate to instance management for that catalog
  2. Delete all instances first (if not in active loans)
  3. Return to catalog and delete the entry
Cause: Database query or status inconsistencySolution:
  1. Refresh the dashboard page
  2. Verify loan statuses are accurate
  3. Check for stale data
  4. Run database integrity check

​
Quick Reference: Admin Routes

FunctionRouteMethodAccess
User Management/usersGETAdmin
Search Users/users/search?search=<term>GETAdmin
Create User/users/createPOSTAdmin
Edit User/users/edit/<user_id>POSTAdmin
Delete User/users/delete/<user_id>POSTAdmin
Bulk Import/users/bulk_importPOSTAdmin
Admin Dashboard/dashboardGETAdmin, Bibliotecario
Approve Loan/approve/<loan_id>POSTAdmin, Bibliotecario
Reject Loan/reject/<loan_id>POSTAdmin, Bibliotecario
Process Return/loan/<loan_id>/returnPOSTAdmin, Bibliotecario
Catalog Management/catalogGET/POSTAdmin, Bibliotecario
Instance Management/catalog/<catalog_id>/instancesGET/POSTAdmin, Bibliotecario
Update Instance/instance/update_status/<instance_id>POSTAdmin, Bibliotecario
Delete Instance/instance/delete/<instance_id>POSTAdmin, Bibliotecario

​
Database Schema Reference

Key tables and relationships:

​
User Table

- id (Primary Key)
- email (Unique)
- document_id (Unique)
- full_name
- phone
- role (cliente, premium, bibliotecario, admin)
- program_name (nullable, for cliente only)
- password_hash

​
Catalog Table

- id (Primary Key)
- title_or_name
- category (libro, computo, general)
- author_or_brand
- instances (Relationship to ItemInstance)

​
ItemInstance Table

- id (Primary Key)
- catalog_id (Foreign Key → Catalog)
- unique_code (Unique)
- status (disponible, prestado, mantenimiento, perdido)
- condition
- loans (Relationship to Loan)

​
Loan Table

- id (Primary Key)
- user_id (Foreign Key → User)
- instance_id (Foreign Key → ItemInstance)
- environment (interno, externo)
- request_date
- approval_date (nullable)
- due_date (nullable)
- return_date (nullable)
- status (pendiente, activo, atrasado, devuelto, rechazado)
- observation (nullable)
- final_penalty (frozen penalty on return)

​
Need Help?

Technical Support

For system errors, database issues, or technical problems, consult the development team or system documentation.

Policy Guidance

For user management policies, penalty rates, or operational procedures, refer to organizational guidelines.

User Training

To train librarians or premium users, use this documentation as reference material.
You’re fully equipped to administer the SWL Library Management System with confidence!

Build docs developers (and LLMs) love

Get started for freeTalk to us