# sunny-nanade/booklet-scanning-system architecture

> Architecture diagram of the GitHub repository sunny-nanade/booklet-scanning-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sunny-nanade/booklet-scanning-system
- Repository: https://github.com/sunny-nanade/booklet-scanning-system

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware & External
    subgraph "Hardware & External"
        Cam["Logitech Brio MX\nCamera"]:::external
        Rig["Acrylic Rig"]:::external
        OCR["OCR Agent Placeholder"]:::external
        Browser["Web Browser"]:::external
    end

    %% Frontend UI
    subgraph "Frontend UI"
        subgraph "Templates"
            Index["index.html"]:::frontend
            ScanT["scan.html"]:::frontend
            ConfigT["config.html"]:::frontend
        end
        subgraph "Static Assets"
            CSS["styles.css"]:::frontend
            JS_Cam["camera.js"]:::frontend
            JS_Overlay["overlay.js"]:::frontend
            JS_Scanner["scanner.js"]:::frontend
            JS_Preview["preview.js"]:::frontend
            JS_State["state.js"]:::frontend
            JS_Main["main.js"]:::frontend
        end
    end

    %% Backend
    subgraph "Backend"
        Entry["main.py"]:::backend
        ConfigFile["config.json"]:::backend
        subgraph "Routes"
            CRoutes["config_routes.py"]:::backend
            Detect["detection.py"]:::backend
            ScanFlow["scan_flow.py"]:::backend
            PDFExp["pdf_exporter.py"]:::backend
        end
        subgraph "Core Services"
            ConfigM["config_manager.py"]:::backend
            Scanner["scanner_logic.py"]:::backend
        end
        subgraph "Utilities"
            ImgUtils["image_utils.py"]:::backend
            OverUtils["overlay_utils.py"]:::backend
            TimeUtils["time_utils.py"]:::backend
        end
        DLL["dll_files"]:::backend
    end

    %% Storage
    subgraph "Storage"
        Images["scans/main/*"]:::storage
    end

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        Spec["main.spec"]:::packaging
        BuildDir["build/"]:::packaging
        DistExe["dist/main.exe"]:::packaging
    end

    %% Data Flows
    Cam --> Browser
    Rig --> Browser

    Browser --> Index
    Browser --> ScanT
    Browser --> ConfigT
    Browser --> JS_Cam

    JS_Cam --> Detect
    JS_Scanner --> ScanFlow

    Detect --> Scanner
    Scanner --> ImgUtils
    Scanner --> OverUtils
    Scanner --> Images

    ScanFlow --> Scanner
    ScanFlow --> ConfigM
    ConfigM --> ConfigFile
    ScanFlow --> Images
    ScanFlow --> PDFExp
    PDFExp --> Images
    PDFExp --> Browser

    Entry --> CRoutes
    Entry --> Detect
    Entry --> ScanFlow
    Entry --> PDFExp
    Entry --> ConfigM
    Entry --> DLL

    CRoutes --> ConfigM
    Detect --> ImgUtils
    Detect --> Scanner

    Spec --> BuildDir --> DistExe
    DistExe --> Entry

    %% Click Events
    click Entry "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/main.py"
    click ConfigFile "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/config.json"
    click ConfigM "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/core/config_manager.py"
    click Scanner "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/core/scanner_logic.py"
    click CRoutes "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/routes/config_routes.py"
    click Detect "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/routes/detection.py"
    click ScanFlow "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/routes/scan_flow.py"
    click PDFExp "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/routes/pdf_exporter.py"
    click ImgUtils "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/utils/image_utils.py"
    click OverUtils "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/utils/overlay_utils.py"
    click TimeUtils "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/app/utils/time_utils.py"
    click DLL "https://github.com/sunny-nanade/booklet-scanning-system/tree/main/app/dll_files"
    click Index "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/templates/index.html"
    click ScanT "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/templates/scan.html"
    click ConfigT "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/templates/config.html"
    click CSS "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/static/css/styles.css"
    click JS_Cam "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/static/js/camera.js"
    click JS_Overlay "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/static/js/overlay.js"
    click JS_Scanner "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/static/js/scanner.js"
    click JS_Preview "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/static/js/preview.js"
    click JS_State "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/static/js/state.js"
    click JS_Main "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/static/js/main.js"
    click Images "https://github.com/sunny-nanade/booklet-scanning-system/tree/main/scans/main/"
    click Spec "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/main.spec"
    click BuildDir "https://github.com/sunny-nanade/booklet-scanning-system/tree/main/build/"
    click DistExe "https://github.com/sunny-nanade/booklet-scanning-system/blob/main/dist/main.exe"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef backend fill:#bfb,stroke:#333,stroke-width:1px
    classDef storage fill:#fbf,stroke:#333,stroke-width:1px
    classDef packaging fill:#ffb,stroke:#333,stroke-width:1px
```
