SemesterapparatsManager

A comprehensive desktop application for managing semester course reserve collections (Semesterapparate) at the University of Education Freiburg. This tool streamlines the workflow of creating, managing, and maintaining both physical and digital course reserves, with integrated citation management powered by Zotero.

📋 Table of Contents

• Overview
• Features
• Architecture
• Installation
• Usage
• Development
• Documentation
• Contributing
• License

🎯 Overview

SemesterapparatsManager is a Python-based graphical application designed to simplify the complex workflow of academic course reserve management. It provides librarians and staff with tools to:

• Manage Physical Reserves: Track books, media, and materials reserved for courses
• Handle Digital Collections: Process, scan, and catalog digital course materials
• Automate Citations: Generate proper bibliographic citations using Zotero integration
• Communicate: Send automated emails to professors about reserve status
• Analyze: View statistics and search through historical data
• Integrate: Connect with library catalogs (SWB, DNB) and vendor APIs (Lehmanns)

Key Technologies

• Framework: PySide6 (Qt6) for cross-platform GUI
• Database: SQLite with migration support
• APIs: Integration with SWB, DNB, Zotero, OpenAI, and catalog services
• Document Processing: Word, PDF, CSV, and XML parsing
• Bibliography: Zotero-based citation management

✨ Features

Course Reserve Management

• Create & Edit: Add new semester apparatus with book and media entries
• Extend Duration: Extend existing reserves for additional semesters
• Smart Search: Find reserves by semester, professor, subject, or signature
• Availability Checking: Automated checks against library catalog
• New Edition Detection: Background thread to find newer editions of books

Digital Collection Features

• Document Parsing: Extract information from submitted Word/PDF forms
• Smart Splitting: Automatically split multi-part book sections
• Citation Generation: Create proper citations for all digital files
• ELSA Integration: Manage electronic semester apparatus (ELSA) workflows
• File Management: Track and recreate files from database

Communication & Notifications

• Email Templates: Pre-configured templates for common scenarios
• Professor Notifications: Automated emails for creation, extension, or dissolution
• Message System: Attach messages to specific reserves or broadcast to all

Data & Analytics

• Statistics Dashboard: Visualize creation and deletion trends
• Advanced Search: Multi-criteria search across all reserves
• Export: Generate reports and documentation
• Calendar View: Timeline of reserve activities

Administration

• User Management: Create, edit, and delete system users
• Professor Database: Maintain professor contact information
• Settings Configuration: Customize database paths, temp directories, API keys
• Backup & Migration: Database migration support for schema updates

🏗️ Architecture

Project Structure

SemesterapparatsManager/
├── src/
│   ├── core/              # Domain models & constants
│   │   ├── models.py      # BookData, Prof, Apparat, Semester, etc.
│   │   ├── constants.py   # Application constants
│   │   └── semester.py    # Semester handling logic
│   ├── database/          # Data persistence layer
│   │   ├── connection.py  # Database class & operations
│   │   ├── schemas.py     # SQL schema definitions
│   │   └── migrations/    # SQL migration files
│   ├── services/          # External API integrations
│   │   ├── catalogue.py   # RDS catalog scraping
│   │   ├── sru.py         # SWB/DNB library API client
│   │   ├── lehmanns.py    # Lehmanns bookstore API
│   │   ├── zotero.py      # Zotero integration
│   │   ├── webadis.py     # WebADIS automation
│   │   └── openai.py      # OpenAI API integration
│   ├── parsers/           # Document & file parsing
│   │   ├── csv_parser.py  # CSV parsing
│   │   ├── word_parser.py # Word document parsing
│   │   ├── pdf_parser.py  # PDF text extraction
│   │   ├── xml_parser.py  # XML parsing
│   │   └── transformers/  # Bibliography format conversion
│   ├── documents/         # Document generation
│   │   └── generators.py  # Word/PDF document creation
│   ├── background/        # Background tasks & threading
│   │   ├── autoadder.py   # Automatic book addition
│   │   ├── availability_checker.py  # Catalog availability
│   │   ├── book_grabber.py          # Catalog metadata retrieval
│   │   └── new_editions.py          # New edition detection
│   ├── ui/                # User interface components
│   │   ├── userInterface.py  # Main application window
│   │   ├── dialogs/       # Dialog windows
│   │   └── widgets/       # Reusable UI widgets
│   ├── admin/             # Administrative functions
│   │   └── commands.py    # Admin CLI commands
│   ├── utils/             # Utility functions
│   │   ├── files.py       # File operations
│   │   ├── sorting.py     # Custom sorting logic
│   │   └── blob.py        # Binary data handling
│   ├── shared/            # Cross-cutting concerns
│   │   ├── logging.py     # Centralized logging
│   │   └── config.py      # Configuration management
│   └── errors/            # Custom exceptions
│       └── database.py    # Database-specific errors
├── tests/                 # Test suite
├── docs/                  # Documentation
├── mail_vorlagen/         # Email templates
├── config.yaml            # Application configuration
├── main.py                # Application entry point
└── README.md

Architecture Principles

Layered Architecture:

UI Layer (PySide6 Qt Widgets)
    ↓
Background Tasks (QThread workers)
    ↓
Business Logic (Core models & operations)
    ↓
Services Layer (External API integrations)
    ↓
Data Access Layer (Database & file operations)

Key Design Patterns:

• Repository Pattern: Database class abstracts data persistence
• Service Layer: External integrations isolated in services/
• Observer Pattern: Qt signals/slots for event-driven updates
• Factory Pattern: Document and citation generators
• Strategy Pattern: Multiple parsing strategies for different file formats

🚀 Installation

Prerequisites

• Python 3.10 or higher
• uv - Fast Python package installer and resolver (recommended)

  # Install uv (Windows PowerShell)
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  
  # Or using pip
  pip install uv
  

Setup Steps (Using uv - Recommended)

1. Clone the repository:

   git clone https://github.com/yourusername/SemesterapparatsManager.git
   cd SemesterapparatsManager
   

2. Create virtual environment and install dependencies:

   # uv automatically creates venv and installs dependencies
   uv sync
   

3. Configure application:

   • First launch will present a setup wizard
   • Configure database path, temp directory, and API keys
   • Create admin user account

4. Run the application:

   uv run python main.py
   

Alternative Setup (Using pip/venv)

Click to expand traditional pip installation steps

1. Create virtual environment:

   python -m venv .venv
   

2. Activate virtual environment:

   • Windows (PowerShell):

     .venv\Scripts\Activate.ps1
     

   • Linux/Mac:

     source .venv/bin/activate
     

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the application:

   python main.py
   

Building Executable

To build a standalone executable:

# Using uv
uv run pyinstaller --noconfirm --onedir --windowed \
  --icon='icons/app.ico' \
  --name='SemesterapparatsManager' \
  --clean \
  --add-data='config.yaml;.' \
  --add-data='icons;icons' \
  main.py

Or use the provided build task (see pyproject.toml).

📖 Usage

First Time Setup

1. Launch Application: Run python main.py
2. Setup Wizard: Configure basic settings
   • Database location
   • Temporary files directory
   • Library catalog credentials (optional)
   • API keys (Zotero, OpenAI - optional)
3. Create Admin User: Set up your admin credentials
4. Login: Use your credentials to access the main interface

Creating a Semester Apparatus

1. Navigate: Main window → "Neuer Apparat" (New Apparatus)
2. Fill Details:
   • Semester (e.g., WiSe 2024/25)
   • Professor information
   • Course subject
   • Apparatus number
3. Add Books: Click "Buch hinzufügen" (Add Book)
   • Enter signature or search by title
   • System fetches metadata from catalog
   • Add multiple books as needed
4. Add Media: Click "Medium hinzufügen" (Add Media)
   • DVDs, CDs, or other media types
5. Save: Confirm and create the apparatus
6. Generate Email: Optionally send notification to professor

Managing Digital Collections (ELSA)

1. Upload Form: Submit Word/PDF form with book chapter information

Setting Up Development Environment

1. Install all dependencies (including dev dependencies):

   # Using uv (recommended)
   uv sync --all-extras
   
   # Or using pip
   pip install -r requirements-dev.txt
   

2. Enable logging:

   from src.shared.logging import configure
   configure("DEBUG")  # In main.py
   

3. Run tests:

   # Using uv
   uv run pytest tests/
   
   # Or with activated venv
   pytest tests/
   ```ministrative Tasks
   
   

• User Management: Admin → Users → Create/Edit/Delete
• Professor Database: Admin → Professors → Manage contacts
• System Settings: Edit → Settings → Configure paths and APIs
• Database Maintenance: Admin → Database → Run migrations

🛠️ Development

Setting Up Development Environment

1. Install dev dependencies:

   pip install -r requirements-dev.txt
   

2. Enable logging:

   from src.shared.logging import configure
   configure("DEBUG")  # In main.py
   

3. Run tests:

   pytest tests/
   

Project Standards

• Code Style: Follow PEP 8
• Type Hints: Use type annotations where possible
• Docstrings: Google-style docstrings for all public functions
• Logging: Use centralized logger from src.shared.logging
• Imports: Use new structure (see MIGRATION_GUIDE.md)

Database Migrations

To create a new migration:

1. Create file: src/database/migrations/V###__description.sql
2. Use sequential numbering (V001, V002, etc.)
3. Write idempotent SQL (use IF NOT EXISTS)
4. Test migration on copy of production database

Example:

-- V003__add_user_preferences.sql
CREATE TABLE IF NOT EXISTS user_preferences (
    user_id INTEGER PRIMARY KEY,
    theme TEXT DEFAULT 'light',
    language TEXT DEFAULT 'de',
    FOREIGN KEY (user_id) REFERENCES user(id)
);

Adding New Features

New Service Integration:

1. Create module in src/services/
2. Implement client class with proper error handling
3. Add to src/services/__init__.py
4. Document API requirements

New Document Parser:

1. Create module in src/parsers/
2. Implement parsing function returning core models
3. Add to src/parsers/__init__.py
4. Write unit tests

New UI Dialog:

1. Design in Qt Designer (.ui file)
2. Convert: pyside6-uic dialog.ui -o dialog_ui.py
3. Create dialog class in src/ui/dialogs/
4. Connect signals to business logic

Building Documentation

# Using uv
uv run mkdocs build
uv run mkdocs serve  # View at http://localhost:8000

# Or with activated venv
mkdocs build
mkdocs serve
```*[API Documentation](docs/)**: Detailed module documentation
- **[User Manual](docs/index.md)**: Complete user guide (MkDocs)

### Building Documentation

```bash
mkdocs build
mkdocs serve  # View at http://localhost:8000

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Review Checklist

• Code follows project style guidelines
• All tests pass
• New features have tests
• Documentation is updated
• No sensitive data in commits
• Import paths use new structure

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• University of Education Freiburg: Project sponsor and primary user
• Qt/PySide6: Excellent cross-platform GUI framework
• Zotero: Citation management integration
• SWB/DNB: Library catalog services

📞 Support

For questions, issues, or feature requests:

• Issues: Gitea Issues
• Email: alexander.kirchner@ph-freiburg.de
• Documentation: Read the Docs

🗺️ Roadmap

TBD

Built with ❤️ for academic libraries