# dstark5/openlib architecture

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

- Interactive diagram: https://gitdiagram.com/dstark5/openlib
- Repository: https://github.com/dstark5/openlib

## Overview

##### Project type and purpose
- This is a cross-platform mobile/desktop/web client application built with Flutter.
- Its purpose is to let users search, download, and read books from Anna’s Archive (a “shadow library”) by scraping web responses, parsing them, and presenting them in an in-app reader.

##### File structure
- Top-level directories for each supported platform: android/, ios/, linux/, macos/, windows/, web/
- Core Dart code under lib/, subdivided into:
- services/ – networking, parsing, file I/O, database wrappers, share integration
- state/ – global or scoped state management
- ui/ – pages, widgets, theme definitions, built-in EPUB/PDF viewers
- pubspec.yaml declaring Flutter SDK, dependencies
- android/app, ios/Runner, etc. contain native host entry points and configuration

##### README for additional insights
- No backend server—purely a client that scrapes Anna’s Archive HTML, extracts mirror links, downloads files, and stores them locally.
- Features listed: trending, search/filter/sort, in-app viewer (EPUB/PDF), external reader share.

##### Main components and how to model them

A. Presentation Layer (Flutter UI)
- Pages (e.g., HomePage, SearchPage, BookInfoPage, MyLibraryPage, SettingsPage)
- Reusable components (Widget library under ui/components)
- In-app viewers (EpubViewer, PdfViewer, WebviewPage)
B. State Management
- A central “State” object or BLoC/Provider mix (lib/state/state.dart)
- Exposes methods/events to fetch data, trigger downloads, update UI
C. Services Layer
- NetworkService:
- annas_archive.dart – sends HTTP GET to Anna’s Archive search/mirror pages & parses HTML
- goodreads.dart & open_library.dart – optional metadata enrichment via public APIs
- DownloadService (download_file.dart) – handles HTTP file downloads, resumable if in roadmap
- DatabaseService (database.dart) – local metadata store (SQLite, Hive, or similar)
- FileService (files.dart) – read/write files to device storage, enforce storage path
- ShareService (share_book.dart) – platform share plugin integration
D. Data Storage & File System
- Local database (e.g., Hive/SQLite) for bookmarks, download state, user settings
- File system directories under app sandbox for downloaded ePub/PDF files
E. External Systems
- Anna’s Archive web servers (shadow library)
- (Optional) Goodreads / Open Library public APIs
- Native OS file viewers (when user opts to open in external reader)
F. Platform Host & Flutter Engine
- Android (MainActivity.kt), iOS (AppDelegate.swift), Windows, Linux, macOS host code loading Flutter engine
- Plugins auto-registered (generated_plugin_registrant)

##### Relationships & data flow
- UI invokes State methods to initiate actions (e.g., search, download)
- State dispatches calls to Services
- NetworkService fetches/parses remote HTML or API JSON, returns domain models (Book, MirrorLink, etc.)
- State stores results in DatabaseService and notifies UI to rebuild
- DownloadService writes files via FileService; on completion, State updates UI progress/status
- In-app viewer reads file via FileService and renders it in UI
- ShareService invokes platform APIs to share file or link
- All user preferences go through DatabaseService or Flutter’s SharedPreferences plugin

##### Architectural patterns & design principles
- Layered/Clean Architecture:
- Separation of concerns between UI, state management, service (data) layer
- Domain models independent of UI
- Single source of truth: the State class represents app state
- Dependency inversion: UI depends on abstracted services rather than concrete HTTP or file code
- Plugin isolation: platform-specific code is confined to android/, ios/, etc., everything else remains Dart

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        A1["HomePage"]:::presentation
        A2["SearchPage"]:::presentation
        A3["BookInfoPage"]:::presentation
        A4["MyLibraryPage"]:::presentation
        A5["MyBookPage"]:::presentation
        A6["SettingsPage"]:::presentation
        A7["CategoriesPage"]:::presentation
        A8["TrendingPage"]:::presentation
        A9["ResultsPage"]:::presentation
        A10["EpubViewer"]:::presentation
        A11["PdfViewer"]:::presentation
        A12["WebviewPage"]:::presentation
        subgraph "UI Components Library"
            C1["BookCardWidget"]:::presentation
            C2["BookInfoWidget"]:::presentation
            C3["FileButtonsWidget"]:::presentation
            C4["DeleteDialogWidget"]:::presentation
            C5["ErrorWidget"]:::presentation
            C6["PageTitleWidget"]:::presentation
            C7["SnackBarWidget"]:::presentation
        end
    end

    %% State Management
    S["Global State\n(state.dart)"]:::state

    %% Services Layer
    subgraph "Services Layer"
        N1["Anna’s Archive\nNetworkService"]:::service
        N2["Goodreads API\nNetworkService"]:::service
        N3["OpenLibrary API\nNetworkService"]:::service
        Dn["DownloadService"]:::service
        Db["DatabaseService"]:::service
        Fs["FileService"]:::service
        Sh["ShareService"]:::service
    end

    %% Data Storage
    subgraph "Data Storage"
        DB[(Database)]:::storage
        FS[(File System)]:::storage
    end

    %% External Systems
    subgraph "External Systems"
        E1(("Anna’s Archive\nWeb Servers")):::external
        E2(("Goodreads\nPublic API")):::external
        E3(("OpenLibrary\nPublic API")):::external
        E4(("OS File Viewer")):::external
    end

    %% Flutter Engine & Host
    subgraph "Flutter Engine & Host"
        H1["Android Host"]:::host
        H2["iOS Host"]:::host
        H3["macOS Host"]:::host
        H4["Windows Host"]:::host
        H5["Web Host"]:::host
        M["Main Entry (main.dart)"]:::host
    end

    %% Connections
    A1 -->|"invoke actions"| S
    A2 -->|"invoke actions"| S
    A3 -->|"invoke actions"| S
    A4 -->|"invoke actions"| S
    A5 -->|"invoke actions"| S
    A6 -->|"invoke actions"| S
    A7 -->|"invoke actions"| S
    A8 -->|"invoke actions"| S
    A9 -->|"invoke actions"| S
    A10 -->|"load file"| Fs
    A11 -->|"load file"| Fs
    A12 -->|"fetch mirror HTML"| N1

    S -->|"searchBooks(query)"| N1
    S -->|"enrichMetadata(book)"| N2
    S -->|"enrichMetadata(book)"| N3
    S -->|"downloadFile(url)"| Dn
    S -->|"getSavedMetadata()"| Db
    S -->|"readFile(path)"| Fs
    S -->|"shareBook(file)"| Sh

    N1 -->|"htmlResponse"| S
    N1 -->|"http GET"| E1
    N2 -->|"jsonResponse"| S
    N2 -->|"http GET"| E2
    N3 -->|"jsonResponse"| S
    N3 -->|"http GET"| E3

    Dn -->|"writeFileStream"| Fs
    Fs -->|"store file"| FS
    Db -->|"storeMetadata"| DB
    Db -->|"readMetadata"| S

    Sh -->|"invoke share API"| E4

    %% Host relationship
    M -->|"boots"| H1
    M -->|"boots"| H2
    M -->|"boots"| H3
    M -->|"boots"| H4
    M -->|"boots"| H5

    %% Click Events
    click A1 "https://github.com/dstark5/openlib/blob/main/lib/ui/home_page.dart"
    click A2 "https://github.com/dstark5/openlib/blob/main/lib/ui/search_page.dart"
    click A3 "https://github.com/dstark5/openlib/blob/main/lib/ui/book_info_page.dart"
    click A4 "https://github.com/dstark5/openlib/blob/main/lib/ui/mylibrary_page.dart"
    click A5 "https://github.com/dstark5/openlib/blob/main/lib/ui/mybook_page.dart"
    click A6 "https://github.com/dstark5/openlib/blob/main/lib/ui/settings_page.dart"
    click A7 "https://github.com/dstark5/openlib/blob/main/lib/ui/categories_page.dart"
    click A8 "https://github.com/dstark5/openlib/blob/main/lib/ui/trending_page.dart"
    click A9 "https://github.com/dstark5/openlib/blob/main/lib/ui/results_page.dart"
    click A10 "https://github.com/dstark5/openlib/blob/main/lib/ui/epub_viewer.dart"
    click A11 "https://github.com/dstark5/openlib/blob/main/lib/ui/pdf_viewer.dart"
    click A12 "https://github.com/dstark5/openlib/blob/main/lib/ui/webview_page.dart"
    click C1 "https://github.com/dstark5/openlib/blob/main/lib/ui/components/book_card_widget.dart"
    click C2 "https://github.com/dstark5/openlib/blob/main/lib/ui/components/book_info_widget.dart"
    click C3 "https://github.com/dstark5/openlib/blob/main/lib/ui/components/file_buttons_widget.dart"
    click C4 "https://github.com/dstark5/openlib/blob/main/lib/ui/components/delete_dialog_widget.dart"
    click C5 "https://github.com/dstark5/openlib/blob/main/lib/ui/components/error_widget.dart"
    click C6 "https://github.com/dstark5/openlib/blob/main/lib/ui/components/page_title_widget.dart"
    click C7 "https://github.com/dstark5/openlib/blob/main/lib/ui/components/snack_bar_widget.dart"
    click S "https://github.com/dstark5/openlib/blob/main/lib/state/state.dart"
    click N1 "https://github.com/dstark5/openlib/blob/main/lib/services/annas_archieve.dart"
    click N2 "https://github.com/dstark5/openlib/blob/main/lib/services/goodreads.dart"
    click N3 "https://github.com/dstark5/openlib/blob/main/lib/services/open_library.dart"
    click Dn "https://github.com/dstark5/openlib/blob/main/lib/services/download_file.dart"
    click Db "https://github.com/dstark5/openlib/blob/main/lib/services/database.dart"
    click Fs "https://github.com/dstark5/openlib/blob/main/lib/services/files.dart"
    click Sh "https://github.com/dstark5/openlib/blob/main/lib/services/share_book.dart"
    click M "https://github.com/dstark5/openlib/blob/main/lib/main.dart"
    click H1 "https://github.com/dstark5/openlib/blob/main/android/app/src/main/kotlin/com/app/openlib/MainActivity.kt"
    click H2 "https://github.com/dstark5/openlib/blob/main/ios/Runner/AppDelegate.swift"
    click H3 "https://github.com/dstark5/openlib/blob/main/macos/Runner/MainFlutterWindow.swift"
    click H4 "https://github.com/dstark5/openlib/blob/main/windows/runner/main.cpp"
    click H5 "https://github.com/dstark5/openlib/blob/main/web/index.html"

    %% Styles
    classDef presentation fill:#d0e7ff,stroke:#0366d6
    classDef state fill:#d0f5d0,stroke:#28a745
    classDef service fill:#ffe0b2,stroke:#ff8c00
    classDef storage fill:#f0f0f0,stroke:#999
    classDef external fill:#e0e0e0,stroke:#666
    classDef host fill:#f5e6ff,stroke:#6f42c1
```
