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:**
```python
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:**
```python
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:**
```python
from src.backend import Database
from src.backend.database import Database
from src.backend.db import CREATE_TABLE_MEDIA
```

**NEW:**
```python
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:**
```python
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:**
```python
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:**
```python
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:**
```python
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:**
```python
from src.utils.richtext import create_document, create_pdf
```

**NEW:**
```python
from src.documents import create_document, create_pdf
from src.documents.generators import create_document, create_pdf
```

### Background Tasks

**OLD:**
```python
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:**
```python
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:**
```python
from src.backend import AdminCommands
from src.backend.admin_console import AdminCommands
```

**NEW:**
```python
from src.admin import AdminCommands
from src.admin.commands import AdminCommands
```

### Configuration & Logging

**OLD:**
```python
from src.backend.settings import Settings
from src.logic.settings import Settings
from src.shared.logging import log  # This stays the same
```

**NEW:**
```python
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!