How sunny-nanade/booklet-scanning-system works
Project Type and Purpose
• This is a full-stack, Python-based web application whose goal is to capture, process, and assemble high-resolution booklet scans into PDFs.
• It exposes a live camera preview and scanning API (FastAPI + Uvicorn), a browser-based UI (HTML/CSS/JS), and file-system storage for intermediate images and final PDFs.
File Structure
• Top level:
• main.py – FastAPI app entry point
• config.json – runtime parameters (crop zones, resolution)
• requirements.txt, build/ and dist/ – packaging (PyInstaller)
• app/ directory:
• core/ – business logic (config_manager.py, scanner_logic.py)
• routes/ – HTTP controllers (config_routes.py, detection.py, pdf_exporter.py, scan_flow.py)
• utils/ – helper modules (image_utils.py, overlay_utils.py, time_utils.py)
• dll_files/ – any native libs used by OpenCV or packaging
• static/ + templates/: Frontend assets (JS, CSS, HTML) for live preview, scan screen, configuration
• scans/: temporary images; output PDFs in output/ (in README, though file_tree shows scans/main/*.pdf)
• build & dist: PyInstaller build artifacts and final executable (main.exe); main.spec defines packaging rules
README for Additional Insights
• Stack: Python 3.10+, FastAPI, Uvicorn, OpenCV, PyMuPDF, jsQR
• Workflow: browser ↔ backend for camera feed and QR detection, spacebar triggers scan, core splits pages, saves images, then assembles PDF on demand
a. Main Components
• Hardware Layer: Logitech Brio MX camera, foldable acrylic rig
• Frontend Web Client: HTML templates + JS modules (camera.js, overlay.js, scanner.js, state.js, preview.js)
• Backend API: FastAPI app (main.py → routes/)
• Core Services: config_manager, scanner_logic, pdf_exporter
• Utilities: image processing, overlay drawing, time stamping
• Persistent Storage: scans/ folder (images), output/ folder or scans/main for PDFs, config.json
• Packaging/Deployment: PyInstaller build, venv environment
• Future AI Agents: Tesseract OCR integration placeholder
b. Relationships and Data Flow
1. Browser requests index.html from FastAPI → static assets loaded
2. JS camera module pulls raw frames from camera (getUserMedia) → overlay guides drawn in browser
3. JS sends QR-detection frames (via jsQR) or raw images to backend detection endpoint
4. Backend detection route uses scanner_logic + image_utils to confirm QR, name file
5. On spacebar event, JS POSTs full image to /scan endpoint → core splits left/right pages → writes to scans/
6. scan_flow route registers pages, stores metadata, triggers pdf_exporter when user finishes
7. pdf_exporter assembles images into PDF via PyMuPDF → returns URL to download
8. Filesystem holds everything; config_manager reads config.json for resolution & crop zones
c. Architectural Patterns & Design Principles
• Layered MVC-style separation: routes (controllers) → core services (models/business logic) → utils (helpers) → storage
• Configuration-driven behavior via config.json and config_manager
• Modular packaging: easily extensible by adding new routes or core modules (e.g., OCR agent)
• Single process micro-monolith suitable for packaging into a self-contained exe
d. Key Technologies & Frameworks
• FastAPI + Uvicorn – ASGI web server and HTTP API
• OpenCV – image capture, splitting, cropping
• PyMuPDF – PDF generation
• jsQR – client-side QR detection
• HTML/CSS/Vanilla JS – frontend UI
• PyInstaller (main.spec) – cross-platform packaging
Essential Elements
• Clear labels on each node (e.g., “FastAPI Routes”, “Scanner Logic Service”)
• Frontend UI – another
• Storage & Config – a fourth
• Notation for packaging/deployment path (PyInstaller build artifacts)