# timkjr/bookshelf-scanner-noncuda architecture

> Architecture diagram of the GitHub repository timkjr/bookshelf-scanner-noncuda, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timkjr/bookshelf-scanner-noncuda
- Repository: https://github.com/timkjr/bookshelf-scanner-noncuda

## Overview

##### Project’s Main Components
- AI Service:
- Located in the "ai" directory. It contains image processing, segmentation, and LLM inference logic.
- Key files include src/bookscanner_ai/predict.py and utility modules (image_utils.py and path_utils.py). It also makes use of datasets and models.
- Architecturally, this service processes images by segmenting them using the YOLO model and then applying Moondream2 to extract text via LLM inference.
- Backend:
- Found in the "backend" directory, implemented with FastAPI.
- Defines the HTTP API (e.g., POST /api/predict) in its routers (predict_router.py), which receives the image, calls into the AI service, and streams results back to the client.
- Manages dependency injection, synchronous/asynchronous data streaming, and serves as the logical connector between the frontend and AI service.
- Frontend:
- Located in the "frontend" directory and built with Angular (with Bun as runtime/package manager).
- Provides user interface for image upload and displays the segmented image and recognized book details (titles, authors), updating dynamically as the backend streams the data.

##### Component Relationships and Data Flow
- The User uploads an image via the Frontend.
- The Frontend sends this image to the Backend API (using an endpoint like /api/predict).
- The Backend, upon receiving the image, invokes the AI component (bookscanner_ai) to start processing:
- First, image segmentation via YOLO detects each book.
- Then, individual book spines are cropped, possibly rotated, and forwarded to the Moondream2 model for title/author prediction.
- The Backend streams the results back to the Frontend:
- The first data chunk includes a segmented image (encoded in base64) for immediate display.
- Subsequent chunks stream recognized book details in an incremental fashion.
- Finally, the Frontend updates the UI in real-time as the data arrives.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Keep the UI (Frontend) separate from business logic (Backend) and image processing/AI logic (AI Service).
- Modularity and Scalability:
- How each service can be deployed or scaled independently, especially given the resource-intensive tasks in AI processing.
- Data Streaming:
- Since the backend streams results from the AI service to the frontend, clearly mark this asynchronous streaming communication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User"):::user

    %% Frontend Layer
    subgraph "Frontend (Angular + Bun)"
        FDir("App Directory"):::frontend
        F1("Upload Component (UI)"):::frontend
        F2("Book Prediction Service"):::frontend
        FDir --> F1
    end

    %% Backend Layer
    subgraph "Backend (FastAPI)"
        BDir("Backend Directory"):::backend
        B1("Main API (FastAPI)"):::backend
        B2("Predict Router"):::backend
        B3("API Routes"):::backend
        BDir --> B1
        B1 --> B2
        B1 --> B3
    end

    %% AI Service Layer
    subgraph "AI Service (Python – YOLO & Moondream2)"
        ADir("AI Service Directory"):::ai
        A1("Prediction Engine"):::ai
        A2("Image Utilities"):::ai
        A3("Path Utilities"):::ai
        ADir --> A1
        A1 --> A2
        A1 --> A3
    end

    %% Data Flow Connections
    U -->|"UploadImage"| F1
    F1 -->|"callsPredictionService"| F2
    F2 -->|"POST/api/predict"| B1
    B1 -->|"invokeProcessing"| A1
    A1 -->|"streamResults"| B1
    B1 -->|"updateUI"| F1

    %% Click Events - Frontend
    click FDir "https://github.com/timkjr/bookshelf-scanner-noncuda/tree/main/frontend/src/app"
    click F1 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/frontend/src/app/pages/upload/upload.component.ts"
    click F2 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/frontend/src/app/core/services/book-prediction.service.ts"

    %% Click Events - Backend
    click BDir "https://github.com/timkjr/bookshelf-scanner-noncuda/tree/main/backend/src"
    click B1 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/backend/src/main.py"
    click B2 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/backend/src/routers/predict_router.py"
    click B3 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/backend/src/routers/api.py"

    %% Click Events - AI Service
    click ADir "https://github.com/timkjr/bookshelf-scanner-noncuda/tree/main/ai/src/bookscanner_ai"
    click A1 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/ai/src/bookscanner_ai/predict.py"
    click A2 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/ai/src/bookscanner_ai/utils/image_utils.py"
    click A3 "https://github.com/timkjr/bookshelf-scanner-noncuda/blob/main/ai/src/bookscanner_ai/utils/path_utils.py"

    %% Styles
    classDef user fill:#ffebcd,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef ai fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
