# podyapolskiy/follow-my-reading architecture

> Architecture diagram of the GitHub repository podyapolskiy/follow-my-reading, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/podyapolskiy/follow-my-reading
- Repository: https://github.com/podyapolskiy/follow-my-reading

## Overview

##### Main Components and Their Roles
- API Layer (FastAPI):
- Represented by the api/ directory. It includes versioned endpoints (v1) for handling audio (api/v1/audio.py), image (api/v1/image.py), authentication (api/v1/auth.py), and related tasks (comparison, text, etc.).
- This is where incoming requests (image and audio uploads) are received from clients.

- Core Processing:
- Located in the core/ directory, this layer is responsible for processing logic. It contains modules for audio splitting (core/processing/audio_split.py) and text processing (core/processing/text.py).
- It also contains a task system (core/task_system.py) which likely orchestrates distributed computing with Huey and integrates with Redis for queuing.

- Plugin System:
- The core/plugins/ directory (with base, loader, no_mem) and the plugins/ directory illustrate a flexible plugin architecture.
- Plugins (e.g., ara_tesseract_plugin.py, en_ru_easyocr_plugin.py, whisper_plugin.py, etc.) provide support for multi-language OCR and speech processing. They extend the base functionality and allow the system to support various recognition technologies.

- Deployment and Configuration:
- The deploy/ directory includes Dockerfiles and shell scripts for containerized or standalone deployments.
- Configuration files like config.py, example.config.json, and pyproject.toml further characterize how the system is set up.

- Testing and Documentation:
- The tests/ directory provides unit tests and sample audio/image files.
- Additional documentation is provided externally (GitLab Pages and a Wiki).

##### Relationships and Data Flow
- Client Interaction:

- API to Core Processing:
- The API routes delegate tasks to the core processing modules for handling image processing, audio segmentation, and comparisons (as seen in endpoints like comparison in api/v1/comparison.py).

- Asynchronous Task Processing:
- Leveraging Redis and Huey (not explicitly found in code but inferred from README), the task system queue requests such as audio splitting or plugin-based analysis to be processed asynchronously.

- Plugin Interactions:
- The plugin loader within core/plugins ensures that the proper language/technology-specific plugin (from the plugins/ folder) is invoked per processing requirement.
- The plugins are essentially separate, interchangeable components, so represent them as modular extensions connected to the processing layer.

- External Systems:
- Although there may not be a visible database layer aside from Redis, include an “External Services” label for Redis (for caching and messaging) and Huey (as the task queue).

##### Architectural Patterns and Technologies
- Use a layered architecture: Distinguish clearly between:
- The API/controller layer (FastAPI endpoints)
- The core business logic (task system, processing modules)
- The plugin extension mechanism (for language and OCR/speech variations)

- Asynchronous and distributed processing mechanism which is central to handling audio/image processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (User Uploads)"]:::clientStyle

    subgraph "API Layer"
        API["API Endpoints (FastAPI)"]:::apiStyle
    end

    subgraph "Core Processing & Task System"
        CPModules["Core Processing Modules"]:::coreStyle
        TS["Task System (Async Processing)"]:::coreStyle
    end

    subgraph "Plugin System"
        PM["Plugin Manager"]:::pluginStyle
        PL["Plugin Extensions (OCR & Speech)"]:::pluginStyle
    end

    subgraph "External Services"
        Redis["Redis"]:::externalStyle
        Huey["Huey"]:::externalStyle
    end

    subgraph "Deployment & Configuration"
        Deploy["Deploy & Config"]:::deployStyle
    end

    Client -->|"uploads"| API
    API -->|"delegates"| CPModules
    API -->|"queuesTasks"| TS
    CPModules -->|"triggers"| PM
    PM -->|"loadsPlugins"| PL
    CPModules -->|"queuesAsync"| Redis
    TS -->|"managesAsync"| Huey
    API -->|"configuredBy"| Deploy

    click API "https://github.com/podyapolskiy/follow-my-reading/tree/main/api/v1/"
    click CPModules "https://github.com/podyapolskiy/follow-my-reading/tree/main/core/processing/"
    click TS "https://github.com/podyapolskiy/follow-my-reading/blob/main/core/task_system.py"
    click PM "https://github.com/podyapolskiy/follow-my-reading/tree/main/core/plugins/"
    click PL "https://github.com/podyapolskiy/follow-my-reading/tree/main/plugins/"
    click Deploy "https://github.com/podyapolskiy/follow-my-reading/tree/main/deploy/"

    classDef clientStyle fill:#FAD7A0,stroke:#333,stroke-width:2px,color:#000;
    classDef apiStyle fill:#AED6F1,stroke:#333,stroke-width:2px,color:#000;
    classDef coreStyle fill:#A9DFBF,stroke:#333,stroke-width:2px,color:#000;
    classDef pluginStyle fill:#F9E79F,stroke:#333,stroke-width:2px,color:#000;
    classDef externalStyle fill:#E8DAEF,stroke:#333,stroke-width:2px,color:#000;
    classDef deployStyle fill:#F5B7B1,stroke:#333,stroke-width:2px,color:#000;
```
