SemesterapparatsManager/MIGRATION_GUIDE.md

Migration Guide: New File Structure

Overview

The codebase has been reorganized to improve clarity, maintainability, and separation of concerns. This guide shows how to update your imports.

New Structure Summary

src/
├── core/           # Domain models & constants (formerly in logic/)
├── database/       # Data persistence (formerly in backend/)
├── services/       # External APIs (from backend/ and logic/)
├── parsers/        # File parsing (formerly in logic/)
├── documents/      # Document generation (formerly in utils/)
├── background/     # Threading tasks (formerly in backend/)
├── admin/          # Admin commands (formerly in backend/)
├── shared/         # Cross-cutting concerns (logging, config)
├── utils/          # Pure utilities
├── ui/             # UI components (unchanged)
└── errors/         # Custom exceptions (unchanged)

Import Changes

Core Domain Models

OLD:

from src.logic import BookData, Prof, Semester, Apparat
from src.logic.dataclass import BookData, Prof
from src.logic.semester import Semester
from src.logic.constants import APP_NRS, SEMAP_MEDIA_ACCOUNTS

NEW:

from src.core.models import BookData, Prof, Semester, Apparat, ApparatData
from src.core import BookData, Prof, Semester  # Can use shorthand
from src.core.semester import Semester
from src.core.constants import APP_NRS, SEMAP_MEDIA_ACCOUNTS

Database

OLD:

from src.backend import Database
from src.backend.database import Database
from src.backend.db import CREATE_TABLE_MEDIA

NEW:

from src.database import Database
from src.database.connection import Database  # If you need specific module
from src.database.schemas import CREATE_TABLE_MEDIA

External Services & APIs

OLD:

from src.backend.catalogue import Catalogue
from src.backend.webadis import get_book_medianr
from src.logic.SRU import SWB
from src.logic.lehmannsapi import LehmannsClient
from src.logic.zotero import ZoteroController
from src.logic.webrequest import BibTextTransformer, WebRequest

NEW:

from src.services import Catalogue, SWB, LehmannsClient, ZoteroController
from src.services.catalogue import Catalogue
from src.services.webadis import get_book_medianr
from src.services.sru import SWB
from src.services.lehmanns import LehmannsClient
from src.services.zotero import ZoteroController
from src.services.webrequest import BibTextTransformer, WebRequest

Parsers

OLD:

from src.logic import csv_to_list, word_to_semap
from src.logic.csvparser import csv_to_list
from src.logic.wordparser import word_to_semap
from src.logic.pdfparser import pdf_to_text
from src.logic.xmlparser import xml_to_dict

NEW:

from src.parsers import csv_to_list, word_to_semap  # Lazy loading
from src.parsers.csv_parser import csv_to_list
from src.parsers.word_parser import word_to_semap
from src.parsers.pdf_parser import pdf_to_text
from src.parsers.xml_parser import xml_to_dict

Document Generation

OLD:

from src.utils.richtext import create_document, create_pdf

NEW:

from src.documents import create_document, create_pdf
from src.documents.generators import create_document, create_pdf

Background Tasks

OLD:

from src.backend import AutoAdder, AvailChecker, BookGrabber
from src.backend.threads_autoadder import AutoAdder
from src.backend.threads_availchecker import AvailChecker
from src.backend.thread_bookgrabber import BookGrabber
from src.backend.thread_neweditions import NewEditionCheckerThread

NEW:

from src.background import AutoAdder, AvailChecker, BookGrabber, NewEditionCheckerThread
from src.background.autoadder import AutoAdder
from src.background.availability_checker import AvailChecker
from src.background.book_grabber import BookGrabber
from src.background.new_editions import NewEditionCheckerThread

Admin Commands

OLD:

from src.backend import AdminCommands
from src.backend.admin_console import AdminCommands

NEW:

from src.admin import AdminCommands
from src.admin.commands import AdminCommands

Configuration & Logging

OLD:

from src.backend.settings import Settings
from src.logic.settings import Settings
from src.shared.logging import log  # This stays the same

NEW:

from src.shared import Settings, load_config, log
from src.shared.config import Settings, load_config
from src.shared.logging import log

File Renames

Old Path	New Path
logic/dataclass.py	core/models.py
logic/SRU.py	services/sru.py
logic/lehmannsapi.py	services/lehmanns.py
backend/database.py	database/connection.py
backend/db.py	database/schemas.py
backend/threads_autoadder.py	background/autoadder.py
backend/threads_availchecker.py	background/availability_checker.py
backend/thread_bookgrabber.py	background/book_grabber.py
backend/thread_neweditions.py	background/new_editions.py
backend/admin_console.py	admin/commands.py
utils/richtext.py	documents/generators.py
logic/csvparser.py	parsers/csv_parser.py
logic/pdfparser.py	parsers/pdf_parser.py
logic/wordparser.py	parsers/word_parser.py
logic/xmlparser.py	parsers/xml_parser.py

Quick Migration Checklist

1. ✅ Update all from src.backend import Database → from src.database import Database
2. ✅ Update all from src.logic import BookData → from src.core.models import BookData
3. ✅ Update all from src.backend.catalogue → from src.services.catalogue
4. ✅ Update all from src.logic.SRU → from src.services.sru
5. ✅ Update all from src.backend.admin_console → from src.admin
6. ✅ Update threading imports from src.backend.thread* → src.background.*

Benefits

• Clearer architecture: Each folder has a specific, well-defined purpose
• Better dependency flow: core → database/services → background → ui
• Reduced duplication: Merged 3 duplicate files (pickles.py, settings.py)
• Easier navigation: Intuitive folder names ("services" vs "logic")
• Scalability: Clear extension points for new features

Backwards Compatibility

The old backend/ and logic/ folders still exist with original files. They will be removed in a future cleanup phase after thorough testing.

Questions?

If you encounter import errors:

1. Check this guide for the new import path
2. Search for the class/function name in the new structure
3. Most moves follow the pattern: external APIs → services/, data models → core/, threads → background/

Status

✅ Migration Complete - Application successfully starts and runs with new structure!