# lemon24/reader architecture

> Architecture diagram of the GitHub repository lemon24/reader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lemon24/reader
- Repository: https://github.com/lemon24/reader

## Overview

##### Main Components

a. Core Components:
- Feed Parser Module (handles Atom, RSS, JSON feeds)
- Storage Module (SQLite-based)
- Core Reader Interface
- Plugin System
- Search Engine
- Update Manager

b. Optional Interfaces:
- Web Interface
- CLI Interface

##### Key Architectural Patterns

- Plugin Architecture
- Storage Abstraction
- Feed Parser Abstraction
- Type System Integration

##### Detailed Component Breakdown

Core Layer:
**src/reader/core.py -> Central coordination**
**src/reader/_parser/ -> Feed parsing subsystem**
**src/reader/_storage/ -> Storage subsystem**
**src/reader/_plugins/ -> Plugin infrastructure**

**[External Interfaces Layer]**
- ↓
**[Core API Layer]**
- ↓
**[Service Layer]**
- ↓
**[Infrastructure Layer]**

##### Component Relationships

Key interactions:
- Feed Parser → Core Reader
- Storage → Core Reader
- Plugins ⟷ Core Reader
- Web/CLI → Core Reader
- Search Engine ⟷ Storage

##### Technical Details

- SQLite database connection
- Feed format support (Atom, RSS, JSON)
- Plugin extension points
- Search functionality
- Type system integration

##### Implementation Notes

- Clear separation between core functionality and optional components
- Plugin system extensibility
- Storage abstraction for potential future storage backends
- Parser flexibility for different feed formats

##### Data Flow Representation

Primary operations:
**External Feed → Parser → Storage**
**User Query → Core → Storage → Results**
**Plugin Hooks → Core Processing Pipeline**

Specific Recommendations:

##### Use a multi-layer hexagonal architecture style
- Core domain in the center
- Adapters (parsers, storage) in the middle layer
- External interfaces on the outer layer

##### Specific components from the codebase
- reader._app (Web Interface)
- reader._cli (CLI Interface)
- reader._parser (Feed Parsing)
- reader._storage (Data Storage)
- reader._plugins (Plugin System)

##### Clear boundaries between
- Public API (reader.core)
- Internal implementations (_parser, _storage)
- Optional components (_app, _cli)
- Plugin system integration points

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Style Definitions
    classDef core fill:#b3d1ff,stroke:#333,stroke-width:2px
    classDef plugin fill:#90EE90,stroke:#333,stroke-width:2px
    classDef interface fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef infrastructure fill:#E6E6E6,stroke:#333,stroke-width:2px
    
    %% External Interfaces Layer
    subgraph Interfaces
        WEB["Web Interface"]:::interface
        CLI["CLI Interface"]:::interface
    end

    %% Core API Layer
    subgraph CoreAPI
        CORE["Core Reader Interface"]:::core
        TYPES["Type System"]:::core
    end

    %% Service Layer
    subgraph Services
        PARSER["Feed Parser Module"]:::core
        STORAGE["Storage Module"]:::core
        SEARCH["Search Engine"]:::core
        UPDATE["Update Manager"]:::core
    end

    %% Infrastructure Layer
    subgraph Infrastructure
        PLUGINS["Plugin System"]:::plugin
        DB[(SQLite Database)]:::infrastructure
    end

    %% Parser Components
    subgraph ParserComponents
        JSON["JSON Feed Parser"]:::core
        FEEDP["Feed Parser Implementation"]:::core
        HTTP["HTTP Handler"]:::core
    end

    %% Storage Components
    subgraph StorageComponents
        BASE["Base Storage"]:::core
        ENTRIES["Entries Storage"]:::core
        FEEDS["Feeds Storage"]:::core
        TAGS["Tags Storage"]:::core
    end

    %% Relationships
    WEB --> CORE
    CLI --> CORE
    CORE --> TYPES
    CORE --> PARSER
    CORE --> STORAGE
    CORE --> SEARCH
    CORE --> UPDATE
    PLUGINS <--> CORE
    STORAGE --> DB
    SEARCH --> STORAGE
    UPDATE --> PARSER
    
    PARSER --> JSON
    PARSER --> FEEDP
    PARSER --> HTTP
    
    STORAGE --> BASE
    STORAGE --> ENTRIES
    STORAGE --> FEEDS
    STORAGE --> TAGS

    %% Click Events
    click CORE "https://github.com/lemon24/reader/blob/master/src/reader/core.py"
    click WEB "https://github.com/lemon24/reader/tree/master/src/reader/_app/"
    click CLI "https://github.com/lemon24/reader/blob/master/src/reader/_cli.py"
    click PARSER "https://github.com/lemon24/reader/tree/master/src/reader/_parser/"
    click JSON "https://github.com/lemon24/reader/blob/master/src/reader/_parser/jsonfeed.py"
    click FEEDP "https://github.com/lemon24/reader/blob/master/src/reader/_parser/feedparser.py"
    click HTTP "https://github.com/lemon24/reader/blob/master/src/reader/_parser/http.py"
    click STORAGE "https://github.com/lemon24/reader/tree/master/src/reader/_storage/"
    click BASE "https://github.com/lemon24/reader/blob/master/src/reader/_storage/_base.py"
    click ENTRIES "https://github.com/lemon24/reader/blob/master/src/reader/_storage/_entries.py"
    click FEEDS "https://github.com/lemon24/reader/blob/master/src/reader/_storage/_feeds.py"
    click TAGS "https://github.com/lemon24/reader/blob/master/src/reader/_storage/_tags.py"
    click PLUGINS "https://github.com/lemon24/reader/tree/master/src/reader/_plugins/"
    click SEARCH "https://github.com/lemon24/reader/blob/master/src/reader/_storage/_search.py"
    click UPDATE "https://github.com/lemon24/reader/blob/master/src/reader/_update.py"
    click TYPES "https://github.com/lemon24/reader/blob/master/src/reader/types.py"

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Plugin System"]:::plugin
        L3["External Interfaces"]:::interface
        L4["Infrastructure"]:::infrastructure
    end
```
