A role-based library platform built with Django 5.2 — manage inventory, automate borrowing workflows, surface analytics, and deliver AI-powered book recommendations and chatbot support.

• Why This Project?
• What It Does
• Who Is This For?
• Architecture Overview
• Prerequisites
• Quick Start
  • Full-Stack (Docker Compose)
  • Standalone (Django + DB + Redis)
  • Local Development (No Docker)
• Environment Variables
• Database Requirements
• Management Commands
• Testing
• Project Structure
• Dashboards
• External Services
• Tech Stack
• Troubleshooting
• Contributing
• Additional Documentation
• License

Most library systems stop at check-in / check-out. This project goes further — it combines traditional library management with behavioral analytics and AI-powered services to create a smarter, more engaging experience for students, librarians, and administrators.

With this system you can:

• Automate the full borrowing lifecycle from request through return, with approval gates for librarians.
• Discover books through AI-powered personality-based recommendations and vector-similarity search.
• Interact with LibraBot, an embedded chatbot that answers library questions in real time.
• Analyze borrowing trends, peak usage hours, and genre popularity through role-specific dashboards.

• Role-based access control with custom user roles: admin, librarian, and student.
• Book inventory management supporting physical and digital formats.
• Borrowing lifecycle support:
  • Physical loans: PENDING → ISSUED → RETURN_REQUESTED → RETURNED
  • Digital loans: DOWNLOADED
• Librarian workflows for approving or rejecting borrow and return requests.
• Admin, librarian, and student dashboards with KPIs, logs, and borrowing analytics.
• Google Books integration — search, detail lookup, and import workflows (import restricted to admins and librarians).
• Email notifications for borrow and return events.
• Redis-backed caching with automatic signal-driven invalidation when books or genres change.
• Security hardening with CSP, HSTS, secure cookie flags, and clickjacking/MIME protections.
• Personality-based recommendations — the student dashboard calls the external Recommendation Service for personalized book suggestions powered by Big Five personality profiles.
• Embedded LibraBot chatbot — an in-app chat widget powered by the external Chatbot Service that streams AI responses via SSE.

This application is part of a multi-repository, microservice-oriented architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Root Repository                          │
│                                                             │
│  ┌───────────────────┐  ┌──────────────────┐  ┌──────────┐ │
│  │  library-management│  │ library-chatbot- │  │recommend-│ │
│  │  (Django App)      │  │ service (FastAPI)│  │ation_    │ │
│  │  :8000             │──│ :8001            │  │service   │ │
│  │                    │  │                  │  │(FastAPI) │ │
│  │                    │──┼──────────────────┘  │ :8002    │ │
│  │                    │  └─────────────────────│          │ │
│  └────────┬───────────┘                        └────┬─────┘ │
│           │                                         │       │
│  ┌────────▼───────────┐                    ┌────────▼─────┐ │
│  │  PostgreSQL + pgvec│◄───────────────────│  (shared DB) │ │
│  │  :5432             │                    └──────────────┘ │
│  └────────────────────┘                                     │
│  ┌────────────────────┐                                     │
│  │  Redis :6379       │                                     │
│  └────────────────────┘                                     │
└─────────────────────────────────────────────────────────────┘

• This repository (library-management/) is the Django web application.
• The Chatbot Service powers the LibraBot widget via SSE.
• The Recommendation Service provides personality-based and similarity-based book suggestions.
• All three services can be orchestrated together using the root docker-compose.yml in the parent directory.

To run the entire platform — Django app, chatbot, recommendation engine, PostgreSQL, and Redis — you can orchestrate all services with a single docker-compose.yml. Each service lives in its own repository, so you will clone them side-by-side and create a root compose file.

1. Create a project directory and clone all three repositories into it:

   mkdir library-platform && cd library-platform
   
   git clone https://github.com/peterkahumu/Library-Management.git library-management
   git clone https://github.com/peterkahumu/library-chatbot-service.git library-chatbot-service
   git clone https://github.com/peterkahumu/library-recommendation-service.git recommendation_service

2. Create the root docker-compose.yml in library-platform/ (the parent directory). Expand the block below and save the contents:

   Root docker-compose.yml (click to expand)

   services:
     app:
       build: ./library-management
       image: app
       command: bash -c "./wait-for-it.sh db:5432 -t 60 -- python manage.py migrate && python manage.py collectstatic --noinput && python manage.py runserver 0.0.0.0:8000"
       volumes:
         - ./library-management:/app
       env_file:
         - ./library-management/.env
       depends_on:
         - db
         - redis
       ports:
         - "8000:8000"
   
     ai_service:
       build: ./library-chatbot-service
       image: ai_services
       volumes:
         - ./library-chatbot-service:/app
       ports:
         - "8001:8000"
       env_file:
         - ./library-chatbot-service/.env
   
     recommendation_service:
       build: ./recommendation_service
       image: recommendation_service
       volumes:
         - ./recommendation_service:/app
       ports:
         - "8002:8000"
       env_file:
         - ./library-management/.env
       depends_on:
         - db
   
     db:
       image: pgvector/pgvector:pg16
       volumes:
         - postgres_data:/var/lib/postgresql/data
       env_file:
         - ./library-management/.env
       environment:
         - POSTGRES_DB=${DB_NAME:-library_management}
         - POSTGRES_USER=${DB_USER:-library_management}
         - POSTGRES_PASSWORD=${DB_PASSWORD:-library_management}
   
     redis:
       image: redis:7-alpine
       ports:
         - "6379:6379"
   
   volumes:
     postgres_data:

3. Create the required .env files:

   # Django app environment
   cp library-management/.env_example library-management/.env
   # Edit library-management/.env with your values (set DB_HOST=db and REDIS_URL=redis://redis:6379)
   
   # Chatbot service environment
   cp library-chatbot-service/.env_example library-chatbot-service/.env
   # Edit library-chatbot-service/.env — set OPENAI_API_KEY

4. Start all services:

   docker compose up --build

5. Open http://localhost:8000 for the Django app.

This starts the following services:

Note: The services communicate over Docker's internal network. Ensure DB_HOST=db and REDIS_URL=redis://redis:6379 in the Django .env file. The recommendation service shares the Django .env for database credentials.

If you only need the Django application without the AI microservices, this repository includes its own docker-compose.yml:

cd library-management
cp .env_example .env
# Edit .env — set DB_HOST=db and REDIS_URL=redis://redis:6379
docker compose up --build

Open http://localhost:8000.

This starts app (Django), db (PostgreSQL), and redis. The LibraBot widget and recommendation sections will gracefully degrade when the external services are unavailable.

If you later want the chatbot or recommendations, run the Chatbot Service and Recommendation Service separately, then set AI_SERVICE_URL and RECOMMENDATION_SERVICE_URL in your .env file.

1. Clone and set up a virtual environment:

   git clone https://github.com/peterkahumu/Library-Management.git
   cd library-management
   python -m venv .venv
   source .venv/bin/activate   # Linux/macOS
   # .venv\Scripts\activate    # Windows
   pip install -r requirements.txt

2. Configure environment variables:

   cp .env_example .env
   # Edit .env with your local PostgreSQL and Redis connection details

3. Prepare the database:

   python manage.py migrate
   python manage.py createsuperuser

4. Seed reference data (optional):

   python manage.py seed_genres
   python manage.py seed_personality_data

   The seed_personality_data command requires that you have some books in the database.

5. Start the development server:

   python manage.py runserver

6. Visit http://localhost:8000.

Create a .env file from .env_example and configure the values for your deployment.

See .env_example for the full list of variable names.

The book model includes a 768-dimensional vector field for embeddings, so PostgreSQL must have the pgvector extension installed:

CREATE EXTENSION IF NOT EXISTS vector;

If you use a managed database or a local PostgreSQL instance, verify the extension is available before running migrations. The Docker Compose setup uses pgvector/pgvector:pg16, which includes the extension out of the box.

Note: seed_personality_data requires books to already exist in your database. Run seed_genres first, then import or add books before seeding personality data.

# Local
python manage.py test

# Docker
docker compose exec app python manage.py test

Tests automatically use SQLite and LocMemCache instead of PostgreSQL and Redis, so no external services are needed. The project includes 200+ tests covering authentication, circulation workflows, dashboard analytics, caching, and form validation.

library-management/
├── LibraryManagement/        # Django project settings and root URL config
├── accounts/                 # Custom user model, forms, signals, and auth flows
├── books/                    # Catalogue, inventory, Google Books, and embeddings
├── book_circulation/         # Borrow/return workflows and transaction logic
├── dashboards/               # Role-specific dashboards and analytics
├── pages/                    # Landing page and role-based entry points
├── caching/                  # Cache keys and cache services
├── communications/           # Email delivery service
├── docs/                     # Additional project documentation
├── templates/                # Django HTML templates
├── static/                   # CSS, JS, and image assets
├── tests/                    # Integration tests
├── docker-compose.yml        # Standalone compose (Django + DB + Redis)
├── Dockerfile                # Production-ready Docker image
├── requirements.txt          # Python dependencies
├── DEVELOPER.md              # Developer setup, security, testing, and troubleshooting
└── manage.py                 # Django CLI entry point

The dashboards app exposes role-aware dashboards under /dashboard/:

This application is designed to integrate with two companion microservices:

Both services are optional — the Django application degrades gracefully when they are unavailable. Recommendation sections are omitted from the student dashboard, and the LibraBot widget shows an unavailable state.

• Chatbot widget: static/js/chatbot.js + templates/components/chatbot.html
• Recommendation hooks: dashboards/views.py calls the recommendation service via httpx
• CSP configuration: CSP_CONNECT_SRC includes http://localhost:8001 for local development

Contributions are welcome! To get started:

1. Fork this repository.
2. Create a feature branch: git checkout -b feature/your-feature-name.
3. Install pre-commit hooks: pre-commit install.
4. Make your changes and verify they pass: python manage.py test.
5. Run code formatting: black . and flake8.
6. Submit a pull request with a clear description of your changes.

Please read DEVELOPER.md for detailed guidance on local setup, security configuration, and coding standards.

This project is licensed under the MIT License.

Copyright © 2026 Peter Muhumuki.