# anxcye/anx-reader architecture

> Architecture diagram of the GitHub repository anxcye/anx-reader, 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/anxcye/anx-reader
- Repository: https://github.com/anxcye/anx-reader

## Overview

##### Main Components
- User Interface (UI) Layer: Represented by the Flutter components. In the "lib/page" and "lib/widgets" directories, you have pages for the homepage, settings, book player, reading view, and various UI controls for notes, customization, and statistics. This layer handles user interaction on all supported platforms.
- Service/Business Logic Layer: Housed in subdirectories like "lib/service" and "lib/providers". This includes modules for AI integration (under “lib/service/ai”), book management, translation (using Google/Microsoft integrations), text-to-speech, file conversion (e.g., TXT and PDF conversion), synchronization, and statistical analysis.
- Data Access Layer: Look in "lib/dao", which contains data access objects for books, book notes, reading times, and themes, and in "lib/config" for shared preferences. This layer manages local database operations and configuration settings.
- External Integrations and APIs: External services such as WebDAV for syncing, AI services (OpenAI, Claude, Gemini, and DeepSeek), and translation APIs are integrated in the service modules.
- Platform Specific Layers: Native directories (android, ios, macos, windows, linux, web) indicate that the app leverages platform-specific embedding and configuration using the Flutter engine. These directories form the bridge between the Flutter code and native platform capabilities.

##### Relationships & Interactions
- The UI layer (Flutter pages and widgets) interacts with the service layer via providers. For instance, a user action like highlighting a text or switching themes is propagated through UI widgets to the service modules.
- The service modules implement the business logic. For example, the book player service communicates with the UI to render content, and the convert_to_epub service converts various formats.
- The data access layer interacts with both UI (for local data display) and service modules (for updating state, persisting changes, and syncing).
- External services (AI, translation, sync via WebDAV) are called from within respective service modules, and responses are then managed and passed back to the UI.
- Additional configuration and logging utilities (found under “lib/utils” and “lib/providers”) assist in error handling, analytics, and version management.

##### Architectural Patterns and Design Principles
- The project is modular and adopts a layered (or MVVM/MVC-like) architecture where the presentation (UI) is decoupled from the business logic and data access.
- Provider packages (Riverpod code generation is mentioned in the README) are used for state management and dependency injection, promoting clean separation of concerns.
- Cross-platform design: Although Flutter manages the majority of the presentation, native directories handle platform-specific settings and adaptations.

##### Including Relevant Technologies
- Flutter & Dart as the main framework and language.
- Riverpod for state management and code generation (indicated by usage of build_runner).
- Native integration files for Android, iOS, etc., highlighting platform-specific adaptations.
- Integrated AI and translation services with various submodules in the service layer.
- File conversion libraries for EPUB, MOBI, PDF, TXT formats and web-based ebook renderers from “assets/foliate-js”.

- Name each component explicitly using the folder structure as guidance (e.g., label “lib/page” as "UI Pages", “lib/service/ai” as "AI Services", “lib/dao” as "Data Access Objects", etc.).
- Integration points (e.g., WebDAV sync, translation APIs) and annotate key functions like “TTS”, “Conversion Services”, and “Reading Analytics”.
- Modularity—note that improvements or changes in one module (like switching AI services) have minimal impact on others due to the clear layered separation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        UI_Pages["UI Pages"]
        UI_Widgets["UI Widgets"]
    end

    subgraph "Service/Business Logic Layer"
        AI_Services["AI Services"]
        Book_Management["Book Management & Player"]
        Translation_Services["Translation Services"]
        Conversion_Services["Conversion Services"]
        TTS["Text-to-Speech"]
        StateManagement["State Management & Providers"]
    end

    subgraph "Data Access Layer"
        Database["Database Operations"]
        Config["Configuration Settings"]
    end

    subgraph "External Services & Utilities"
        WebDAV["WebDAV Sync"]
        Utilities["Utility Functions & Helpers"]
    end

    subgraph "Platform Specific Integrations"
        Android["Android"]
        iOS["iOS"]
        macOS["macOS"]
        Windows["Windows"]
        Linux["Linux"]
        Web["Web"]
    end

    %% UI Layer interactions
    UI_Pages -->|"triggers"| StateManagement
    UI_Widgets -->|"triggers"| StateManagement

    %% Business Logic interactions
    StateManagement -->|"invokes"| AI_Services
    StateManagement -->|"invokes"| Book_Management
    StateManagement -->|"invokes"| Translation_Services
    StateManagement -->|"invokes"| Conversion_Services
    StateManagement -->|"invokes"| TTS

    %% Data Access interactions
    Book_Management -->|"storesTo"| Database
    AI_Services -->|"fetches"| Database
    Translation_Services -->|"fetches"| Database
    Conversion_Services -->|"fetches"| Database
    TTS -->|"storesTo"| Database

    %% External Services interactions
    Book_Management -->|"syncsWith"| WebDAV

    Utilities ---|"supports"| AI_Services
    Utilities ---|"supports"| Translation_Services
    Utilities ---|"supports"| Conversion_Services
    Utilities ---|"supports"| TTS

    %% Platform integration
    UI_Pages ---|"rendersOn"| Android
    UI_Pages ---|"rendersOn"| iOS
    UI_Pages ---|"rendersOn"| macOS
    UI_Pages ---|"rendersOn"| Windows
    UI_Pages ---|"rendersOn"| Linux
    UI_Pages ---|"rendersOn"| Web

    %% Click Events
    click UI_Pages "https://github.com/anxcye/anx-reader/tree/develop/lib/page"
    click UI_Widgets "https://github.com/anxcye/anx-reader/tree/develop/lib/widgets"
    click AI_Services "https://github.com/anxcye/anx-reader/tree/develop/lib/service/ai"
    click Book_Management "https://github.com/anxcye/anx-reader/tree/develop/lib/service/book"
    click Translation_Services "https://github.com/anxcye/anx-reader/tree/develop/lib/service/translate"
    click Conversion_Services "https://github.com/anxcye/anx-reader/tree/develop/lib/service/convert_to_epub"
    click TTS "https://github.com/anxcye/anx-reader/blob/develop/lib/service/tts.dart"
    click Database "https://github.com/anxcye/anx-reader/tree/develop/lib/dao"
    click Config "https://github.com/anxcye/anx-reader/tree/develop/lib/config"
    click StateManagement "https://github.com/anxcye/anx-reader/tree/develop/lib/providers"
    click WebDAV "https://github.com/anxcye/anx-reader/tree/develop/lib/providers/anx_webdav"
    click WebDAV "https://github.com/anxcye/anx-reader/tree/develop/lib/utils/webdav"
    click Android "https://github.com/anxcye/anx-reader/tree/develop/android"
    click iOS "https://github.com/anxcye/anx-reader/tree/develop/ios"
    click macOS "https://github.com/anxcye/anx-reader/tree/develop/macos"
    click Windows "https://github.com/anxcye/anx-reader/tree/develop/windows"
    click Linux "https://github.com/anxcye/anx-reader/tree/develop/linux"
    click Web "https://github.com/anxcye/anx-reader/tree/develop/web"
    click Utilities "https://github.com/anxcye/anx-reader/tree/develop/lib/utils"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef service fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef data fill:#FFECB3,stroke:#FF6F00,stroke-width:2px;
    classDef external fill:#E1BEE7,stroke:#4A148C,stroke-width:2px;
    classDef platform fill:#CFD8DC,stroke:#37474F,stroke-width:2px;
    
    class UI_Pages,UI_Widgets ui;
    class AI_Services,Book_Management,Translation_Services,Conversion_Services,TTS,StateManagement service;
    class Database,Config data;
    class WebDAV,Utilities external;
    class Android,iOS,macOS,Windows,Linux,Web platform;
```
